Cocos Creator WeChat ミニゲーム構築・デバッグ完全ガイド：Build パネルから開発者ツールまで

数週間かけて、ようやく Cocos Creator でゲームが完成した。

コードも書き終え、素材もインポートし、アニメーションも動いている。Build パネルを開いて WeChat ミニゲームプラットフォームに公開しようとした——ここからが本当の難所だ。

libVersion フィールドのエラー。実機の黒画面。パッケージサイズ超過。iOS 構築の直接失敗。これらはゲーム開発チュートリアルには出てこないが、どれも公開の段階でプロジェクトを止めてしまう。

この記事では、Build パネルの各パラメータの設定方法から、構築出力ディレクトリ内のファイルの役割、WeChat 開発者ツールでの実機デバッグ手順まで、フロー全体を分解して解説する。最後に 2026 年の WeChat ミニゲームインセンティブ政策も読み解く——公開後の収益最大化も事前に計画しておきたいところだ。

Cocos プロジェクトを WeChat ミニゲームに公開する準備中の方、すでに落とし穴を踏んで解決策を探している方に、このガイドが役立てば幸いだ。

Build パネルのパラメータ設定

まず Build パネルを開く。

Cocos Creator では 2 つの方法がある。メニューバーから「プロジェクト → 構築・公開」をクリックするか、ショートカット Ctrl+Shift+B（Mac は Cmd+Shift+B）を押す。パネルが開くと、公開パスから初期シーン、MD5 Cache から AppID まで、さまざまなパラメータが並ぶ——初めて見ると戸惑うかもしれない。

一つずつ見ていこう。

共通パラメータ：基本設定

公開パス：構築出力ディレクトリの場所。デフォルトではプロジェクトルートに build フォルダが生成される。別パスにも変更できるが、デフォルトのままがおすすめ——出力ディレクトリ構造が固定され、後のデバッグも楽になる。

初期シーン：ゲーム起動時に最初に読み込むシーン。通常は Boot シーンか Loading シーンを選ぶ。複数エントリがある場合は、メインエントリを選択する。

構築対象シーン：プロジェクト内の全シーンが一覧表示される。パッケージに含めるシーンにチェックを入れる。チェックなしのシーンは最終パッケージに含まれない。よくある問題：全シーンにチェックを入れてパッケージサイズが膨らむケース。本当に必要なシーンだけ選び、他はリモートリソースサーバーに置くのが定石だ。

MD5 Cache：これを有効にすべきか？

有効にすると、全リソースファイル名に MD5 サフィックスが付く。メリット：リソース更新時にクライアントがファイル変更を自動検出し、古いキャッシュの読み込みを防げる。デメリット：コード内のリソースアクセス方法を変更する必要がある。

例えば元々 resources.load('texture/hero') だった場合、MD5 Cache 有効後は URL が texture/hero-abc123.png のようになる。この API で正しい URL を取得する：

// MD5 サフィックス付きリソースパスを取得
const url = assetManager.utils.getUrlWithUuid('texture/hero', {
    isScene: false,
    type: 'png'
});

この API は Cocos Creator 3.x の標準用法。2.x ではロジックがやや異なるが、核心は同じ——リソースパスをハードコードせず、エンジンに任せること。

WeChat ミニゲーム専用パラメータ：プラットフォーム設定

AppID：必須項目。

AppID がないと構築ボタンを押した時点でエラーになる。テスト用 AppID も使えるが、機能制限が多い——オープンデータドメインが使えない、本番公開できない、広告収益化も制限される。

AppID 申請フロー：WeChat 公式プラットフォームにログイン → ミニプログラム管理 → ミニゲーム追加 → AppID 取得。審査に 1〜3 日かかるので、早めに準備しておこう。

デバッグモード：構築出力にデバッグ関連のコードとリソースが追加される。本番公開時はオフ推奨だが、開発段階ではオンにしておくとデバッグ時間を大幅に節約できる。

エンジン分離：パッケージサイズを大幅に削減できるオプション。

有効にすると、Cocos エンジンコードはゲーム本体にパッケージされず、WeChat サーバーから読み込まれる。前提条件：

• Debug Base Library バージョン ≥ 2.9.0（WeChat 開発者ツールで設定）
• WebAssembly 機能には WeChat クライアント v7.0.17 以上が必要

メリット：初回パッケージを 4MB 以下に抑えられる。デメリット：エンジン読み込みに時間がかかり、初回起動時に短い待ち時間が発生する。リソースが多いプロジェクトなら、エンジン分離はほぼ必須と考えてよい。

サブドメイン設定：ランキング、フレンド共有などオープンデータドメイン機能を使う場合、ここでサブドメイン情報を設定する。サブドメインは独立した実行環境で、メインゲームと分離され、ソーシャルデータを処理する。設定ミスはランキング機能の不具合につながる。

見落としがちなポイント

構築パネル下部に「構築」ボタンがあり、その横に「生成」ボタンがある。

「構築」を押しただけで終わりと思う人が多い。実際、「構築」は出力ディレクトリを生成するだけで、最終的なコードパッケージはまだ作られていない。「生成」をクリックして初めて、game.js、game.json などのエントリファイルが生成される。

初回公開時、私も「構築」だけ押して WeChat 開発者ツールにインポートし、「エントリファイルが見つかりません」エラーに遭遇した——「生成」を押していなかったのが原因。この小さなポイント、公式ドキュメントには書いてあるが見落としやすい。

構築出力の解析とよくある落とし穴

構築完了後、プロジェクトルートの build フォルダを確認しよう。

中に wechatgame ディレクトリがある——WeChat ミニゲームプラットフォーム向けの構築出力だ。このディレクトリを開くと、さまざまなファイルとフォルダが見える。Cocos が生成したものもあれば、WeChat ミニゲーム固有の設定もある。一つずつ役割を見ていこう。

主要設定ファイルの解説

game.js：エンジン起動エントリ。

WeChat ミニゲームプラットフォームがゲームを読み込む際、最初に実行されるファイル。Cocos エンジンの初期化コードとシーン読み込みロジックが含まれる。手動で編集する必要はないが、構築に問題がある場合は構文エラーがないか確認する。

game.json：グローバル設定ファイル。

{
    "deviceOrientation": "portrait",
    "networkTimeout": {
        "request": 60000,
        "connectSocket": 60000,
        "uploadFile": 60000,
        "downloadFile": 60000
    },
    "enginePlugins": [
        "cocos"
    ],
    "optimization": {
        "render": true,
        "fps": true
    }
}

主要フィールドの説明：

• deviceOrientation：画面方向。portrait は縦、landscape は横
• networkTimeout：ネットワークリクエストのタイムアウト（ミリ秒）
• enginePlugins：エンジンプラグイン設定。エンジン分離有効時は "cocos" が表示される
• optimization：パフォーマンス最適化オプション。render と fps はデフォルトで有効

project.config.json：WeChat 開発者ツールのプロジェクト設定。

{
    "miniprogramRoot": "./",
    "setting": {
        "urlCheck": false,
        "es6": true,
        "postcss": true,
        "minified": true
    },
    "compileType": "game",
    "libVersion": "2.25.0",
    "appid": "wx1234567890abcdef",
    "projectname": "my-game"
}

ここに落とし穴がある——libVersion フィールドだ。

落とし穴リスト：5 つのよくある問題

落とし穴 1：libVersion フィールドが無効

症状：WeChat 開発者ツールで基本ライブラリバージョンが無効というエラー。

原因：Cocos 構築時に自動生成された libVersion が、WeChat プラットフォームが現在サポートするバージョンと一致しない。例えば出力が "2.25.0" でも、開発者ツールには "2.20.3" や "latest" しかない。

解決策：project.config.json の libVersion を手動で "widelyUsed" または "latest" に変更。

{
    "libVersion": "widelyUsed"
}

widelyUsed は WeChat が推奨する安定版で互換性が最も高い。latest は最新版で機能は多いが新たな問題もある。まず widelyUsed で試し、安定したら latest を検討しよう。

落とし穴 2：self is not defined

症状：構築は成功するが、実機実行時に self is not defined エラー。

原因：プロジェクトで socket.io ライブラリを使用している。WeChat ミニゲーム環境には window.self グローバルオブジェクトがなく、socket.io の一部バージョンがこれにアクセスしようとする。

解決策：socket.io v1.4.4 に変更。

npm install [email protected] --save

v1.4.4 は WeChat ミニゲーム環境と互換性のある最後の安定版。それ以降のバージョンは大幅にリファクタリングされ、self への依存が追加されている。高バージョンが必須の場合は、ソースを手動でパッチし self を window または global に置き換える。

落とし穴 3：循環参照 JSON エラー

症状：構築時に JSON ファイルの循環参照エラー。

原因：コード内のグローバルオブジェクトが誤ってシリアライズされている。例えば window.global に複雑なオブジェクトが格納され、構築時に Cocos が JSON 変換を試みると、オブジェクト内部に循環参照を発見する。

解決策：window.global の初期化ロジックを確認。

// 誤った書き方：グローバルオブジェクトに自身への参照
window.global = {
    self: window.global  // 循環参照
};

// 正しい書き方：自身への参照を避ける
window.global = {
    config: {},
    gameState: {}
};

構築前にこのような循環参照を除去する。複雑なオブジェクトを保存する必要がある場合は、JSON.stringify と JSON.parse で手動シリアライズし、循環参照部分をスキップする。

落とし穴 4：エンジン分離後に MiniGameCenter が消失

症状：エンジン分離を有効にして構築成功したが、WeChat 開発者ツールで MiniGameCenter 関連機能が見つからない。

原因：MiniGameCenter は WeChat ミニゲームのサービスコンポーネントで、エンジンコードに依存する。エンジン分離後、MiniGameCenter の一部機能が無効になる。

解決策：一時的にエンジン分離をオフにする。

MiniGameCenter の全機能（広告テスト、アプリ内課金など）が必要なら、まずエンジン分離をオフにしてエンジンコードを初回パッケージに含める。機能テスト完了後、本番公開前にエンジン分離を再検討しよう。

落とし穴 5：iOS 構築失敗

症状：iOS プラットフォーム版の構築時に、依存ライブラリやリソースファイルが見つからないエラー。

原因：iOS 構築フローは WeChat ミニゲームより複雑。以下を確認：

• Xcode バージョンが一致しているか（Xcode 12 以上推奨）
• 依存ライブラリのパスが正しいか（Podfile や Carthage 設定を確認）
• リソースファイルが完全か（特に画像、音声ファイル）

解決策：

1. Xcode を開き、構築ログで具体的なエラーメッセージを確認
2. Podfile の依存ライブラリバージョンとローカルインストール版が一致しているか確認
3. 構築キャッシュをクリア：rm -rf build/ios、再構築

iOS 構築の問題は多岐にわたる。具体的なエラーは個別に分析が必要だが、多くの場合キャッシュクリアと再構築で解決する。

パッケージサイズ制限：サイズを抑える方法

WeChat ミニゲームには 2 つのパッケージサイズ制限がある：

• 初回パッケージ：4MB
• 合計パッケージ：20MB（初回 + サブパッケージ）

超過したらどうするか？

方法 1：リソースのリモート化

大部分の画像・音声をリモートサーバーに置き、初回パッケージにはコードと必要最小限のリソースだけを含める。Cocos の assetManager はリモート URL からのリソース読み込みをサポート：

assetManager.loadRemote('https://your-server.com/assets/hero.png', (err, texture) => {
    if (err) {
        console.error('リソース読み込み失敗', err);
        return;
    }
    // 読み込んだリソースを使用
});

リモートリソース読み込みの課題：初回読み込みに時間がかかり、プレイヤー体験に遅延が生じる。よく使うリソースは初回パッケージに残し、あまり使わないものをリモートに置くのがベター。

方法 2：サブパッケージ読み込み

WeChat ミニゲームはサブパッケージをサポート。ゲームを複数モジュールに分割し、各モジュールを 1 つのサブパッケージにする。プレイヤーが特定シーンに入った時点で対応サブパッケージを読み込む。

// game.json でサブパッケージを設定
{
    "subpackages": [
        {
            "name": "level-1",
            "root": "subpackages/level-1"
        },
        {
            "name": "level-2",
            "root": "subpackages/level-2"
        }
    ]
}

サブパッケージ読み込みには Cocos の構築フローの追加設定が必要。詳細は Cocos 公式ドキュメントの「サブパッケージ構築」章を参照。

WeChat 開発者ツールでのデバッグ

構築が完了したら、WeChat 開発者ツールに進む。

ここで多くの人が間違える——「新規プロジェクト」をクリックして誤ったディレクトリを選ぶ。正しくは「プロジェクトをインポート」をクリックし、Cocos 構築出力の build/wechatgame ディレクトリを選択する。

インポート後、プロジェクト設定画面が表示される。主要な設定項目：

基本ライブラリバージョン設定

右上の「詳細」ボタンをクリックし、「ローカル設定」タブを開く。

「デバッグ基本ライブラリ」のドロップダウンがある。ここで widelyUsed または latest を選択——先ほど project.config.json を修正したのと同じ。存在しないバージョンを選ぶとツールがエラーを出す。

合法ドメインの検証をスキップ

テスト段階では、リソースサーバーのドメインが WeChat 公式プラットフォームにまだ登録されていないことがある。この場合「合法ドメイン、web-view（ビジネスドメイン）、TLS バージョン、HTTPS 証明書を検証しない」にチェックを入れる。

チェック後、ツールは未登録ドメインへのリクエストをブロックしなくなる。ただし本番公開前にドメインをホワイトリストに追加すること——さもないとプレイヤーがリモートリソースを読み込めない。

実機デバッグのフロー

ツールバーの「実機デバッグ」ボタンをクリック。

WeChat 開発者ツール v1.05 以降では実機デバッグ v2 が提供されている。旧版と比べて改善点：

1. QR コードプレビューがより安定
2. リモートデバッグと Chrome DevTools のシームレス連携
3. ブレークポイントデバッグ、パフォーマンス監視の同期表示

具体的なフロー：

1. 「実機デバッグ」をクリックして QR コードを生成
2. スマートフォンで WeChat を開き、QR コードをスキャンしてデバッグモードに入る
3. ツール画面右側にデバッグパネルが表示される——Chrome DevTools と同様

デバッグパネルの主要機能：

• Console：ログ出力を確認。console.log の内容がリアルタイム表示
• Sources：ソースコードを確認。ブレークポイント設定も可能
• Network：ネットワークリクエストを確認。リソース読み込みの成否をチェック
• Memory：メモリ分析ツール。メモリリークの有無を確認

実機デバッグはシミュレータより現実に近い。特に低スペック Android 端末では、シミュレータと実機のパフォーマンス差が大きい。複数機種で実機デバッグを繰り返すことを推奨。

パフォーマンス監視ツールの使い方

WeChat 開発者ツールにはパフォーマンス監視ツール一式が搭載されている。

ツールバー右側の「開発ツールボックス」ボタンをクリックすると、診断パネルが開く。主要機能：

実機パフォーマンス監視

QR コードをスキャン後、スマートフォンでゲームを実行すると、ツールが FPS、メモリ、CPU データをリアルタイム表示。

データはグラフ形式で表示される：

• FPS が安定しているか（60FPS が理想、30FPS 以下で明らかなカクつき）
• メモリが継続的に増加していないか（増え続けるならメモリリークの可能性）
• CPU 使用率が高すぎないか（50% 超えは計算負荷が高いサイン）

初回画面レンダリング分析

「初回画面レンダリング」オプションをクリックすると、ゲーム起動から初回画面完全表示までの時間を記録。

このデータは非常に重要。プレイヤーの待ち時間が 3 秒を超えると、離脱率が明らかに上昇する。初回画面レンダリングが 3 秒超なら最適化が必要：

• 初回画面のリソース数を削減
• 画像サイズを小さく
• 非必須リソースを初回画面後に読み込む

読み込みパフォーマンス分析

全リソースの読み込み時間が一覧表示される。どのリソースが最も遅いか把握し、ピンポイントで最適化できる。

例えば 2MB の PNG 画像が 500ms かかる場合：

• WebP 形式に変換（サイズ 30〜50% 削減）
• 画像解像度を圧縮
• キャッシュにプリロード

ランタイムパフォーマンス分析

ゲーム実行中のパフォーマンスボトルネックを記録。

シーン切り替え時に FPS が急落する場合、ツールが原因を特定——アニメーション計算量過多、スクリプト実行時間過長など。

高性能モード：iOS 向け最適化

iOS 端末では、WeChat ミニゲームに「高性能モード」がある。

有効にすると、ゲームは WeChat クライアントとプロセスを共有せず、独立プロセスで実行される。CPU とメモリリソースがより独立し、パフォーマンスが大幅に向上。

公式テストデータ：iPhone 11 Pro Max で水族館 Demo の FPS が 13 から 49 に向上——かなりの改善幅だ。

有効化方法

1. WeChat 公式プラットフォームにログイン
2. 「生産提效包」管理ページに入る
3. iOS 高性能モードサービスを開通

開通後、game.json に設定を追加：

{
    "iOSHighPerformance": true
}

メモリ制限に注意

高性能モードには追加のメモリ制限がある：

• 2GB RAM 端末（iPhone 8、iPhone 7）：1GB 制限
• 3GB RAM 端末（iPhone 11、iPhone 12）：1.4GB 制限

制限超過でメモリ警告、最悪クラッシュ。リソースが多いゲームはメモリピークに注意。

実測のアドバイス：

• 高性能モード有効後、FPS は明らかに向上するがメモリ使用量も増加
• 低スペック端末（iPhone 8）ではリソースを 800MB 以下に抑えるのが安全
• 高スペック端末（iPhone 12）では 1.2GB まで許容可能

高性能モード有効後は、実機パフォーマンス監視を実行し、FPS とメモリが安全範囲内か確認しよう。

2026 年 WeChat ミニゲーム政策の解説

ゲームが公開されたら、次は運営と収益だ。

2026 年、WeChat ミニゲームは新しいインセンティブ政策を発表——開発者にとって追い風だ。主要条項を簡潔に解説する。

IAP（アプリ内課金）インセンティブ新政策

アプリ内課金で収益化するゲームには、初回公開期の追加インセンティブがある。

インセンティブ比率：100% 超

内訳：

• 基本分配：70%（開発者 70%、WeChat プラットフォーム 30%）
• 初回公開インセンティブ：追加 40%

合計すると、初回公開期の開発者実質比率は 70% + 40% = 110%。その通り、流水の 10% 多い。

このインセンティブには時間枠がある——新規ゲーム初回公開期の最初 1000 万元流水が 110% インセンティブ対象。1000 万元超過後は基本 70% に戻る。

インセンティブ金上限：400 万元（2026 上半期）

1 ゲームの初回公開期インセンティブ上限は 400 万元。流水が 1000 万元を突破した場合、インセンティブ金は比例計算：1000 万 × 40% = 400 万——ちょうど上限。

初回成長インセンティブ：流水 200 万元ごとに追加 5% 現金

初回インセンティブに上乗せ。例えば初回公開期流水 600 万元の場合：

• 基本分配：600 万 × 70% = 420 万
• 初回インセンティブ：600 万 × 40% = 240 万（上限 400 万以内）
• 成長インセンティブ：600 万 ÷ 200 万 = 3 回、各 5%、合計 600 万 × 15% = 90 万

合計：420 + 240 + 90 = 750 万元

比較：インセンティブ政策なしなら 600 万流水で 420 万のみ。政策適用で 330 万多く受け取れる。

IAA（広告収益化）インセンティブ新政策

広告収益化（IAA）のゲームにもインセンティブがある。

軽量 IAA ゲーム：30 日間流水 40% インセンティブ金

軽量ゲームとはカジュアル、パズル、マッチ 3 などシンプルなゲームプレイのもの。ユーザー数は多いが個人の課金意欲は低く、広告収益化に適している。

計算方法：公開後 30 日間の広告流水 × 40% をインセンティブ金として支給。

中重度 IAA ゲーム：90 日間流水 35% インセンティブ金

中重度ゲームとはアクション、RPG、ストラテジーなど複雑なゲームプレイのもの。ユーザー数は相対的に少ないが、個人のプレイ時間が長く、広告表示回数も多い。

計算方法：公開後 90 日間の広告流水 × 35%。

収益最大化戦略

政策条項がわかったら、どう最大化するか？

初回公開タイミングの計画

初回インセンティブ期は最初 1000 万元流水のみ対象。ゲームのポテンシャルが大きいなら、ユーザーアクティビティが高い時期（夏休み、祝日など）に初回公開を設定しよう。インセンティブ期間内に流水を素早く伸ばせる。

例：

• 通常期間の初回公開：インセンティブ期流水 500 万、インセンティブ金 200 万
• 冬休みの初回公開：インセンティブ期流水 1000 万、インセンティブ金 400 万（上限）

2 倍の差。

流水ペースのコントロール

インセンティブ金は流水比例で支給される。流水が急成長するとインセンティブ期が早く終わる。段階的プロモーションを検討：

1. 初回公開期：小規模プロモーションでユーザーフィードバックをテスト
2. インセンティブ期間内：大規模プロモーションで流水を急伸
3. インセンティブ期後：安定運営、コスト管理

インセンティブ期間内の流水最大化と、プロモーションコスト過多の回避を両立できる。

収益化モデルの選択

アプリ内課金か広告収益化か？

• シンプルなゲームプレイ、大量ユーザー：広告収益化が適切。軽量 IAA インセンティブ 40%
• 複雑なゲームプレイ、課金意欲が高いユーザー：アプリ内課金が適切。初回インセンティブ 110%

ハイブリッド収益化も可能——アプリ内課金メイン、広告サブ。WeChat プラットフォームもハイブリッドをサポートし、インセンティブ政策はそれぞれ計算される。

審査資格チェックリスト

公開前に必要な資格：

• ソフト著作権：ゲームコードの著作権帰属を証明
• ICP 登録：ドメイン登録。リモートリソースサーバーがある場合に必要
• 版号：ネットゲーム出版物番号。正式リリースに必須（ミニゲームは現在「試運営」資格で先行可能、版号は後から追加）
• プライバシーポリシー：ゲーム起動時に表示し、ユーザー同意後に入場
• 未成年者向け依存症対策：実名認証、プレイ時間制限、課金上限

申請にかかる期間：

• ソフト著作権：1〜2 か月
• ICP 登録：1〜2 週間
• 版号：3〜6 か月（最長）
• 依存症対策機能：開発 1〜2 週間、WeChat 公式 API 連携

早めに計画を。版号申請が最も長いので、ゲーム開発段階から準備を始めよう。

政策情報は WeChat 公式コミュニティの 2026 年インセンティブ政策ドキュメントに基づく。具体条項は変更される可能性があるため、公開前に WeChat 公式プラットフォームで最新版を確認すること。

まとめ

Cocos Creator で WeChat ミニゲームを公開するフローは短くはないが、分解すれば各ステップに道筋がある。

Build パネルのパラメータ：AppID 必須、MD5 Cache 有効後の URL 変換、エンジン分離の前提条件、「構築」と「生成」の違い。

構築出力ディレクトリ：game.js、game.json、project.config.json それぞれに役割がある。落とし穴リストの 5 問題——libVersion 無効、self 未定義、循環参照、MiniGameCenter 消失、iOS 構築失敗——それぞれに対応する解決策がある。

WeChat 開発者ツールのデバッグ：プロジェクトインポート、基本ライブラリバージョン設定、実機デバッグ、パフォーマンス監視。iOS 高性能モードは FPS を大幅に向上させるが、メモリ制限に注意。

2026 年インセンティブ政策：アプリ内課金初回 110%、インセンティブ上限 400 万元、広告収益化 35〜40%。初回公開タイミング、流水ペース、収益化モデル——この 3 点を計画すれば収益は倍増も可能。

公開準備中なら、この順序で進めよう：

1. Build 設定を確認し、パラメータ説明と照合
2. 構築完了後、落とし穴リストで問題をチェック
3. 実機デバッグを複数回実行し、FPS とメモリを監視
4. 公開前に資格を準備し、初回公開タイミングでインセンティブを最大化

WeChat ミニゲームプラットフォームの政策と技術詳細は急速に更新される。この記事は 2026 年上半期の公式ドキュメントと実践経験に基づく。今後の更新で再確認が必要になるかもしれないが、構築フローとデバッグ方法の核心は安定している。

質問があれば、コメント欄で交流しよう。