
WebゲームをCapacitorでAndroidアプリ化、実機で出た6つの問題と直し方【実録#21・Webゲームをアプリ化】
Vite+TypeScriptで書いたブラウザゲームを、Reactを一切使わないまま、CapacitorでそのままパッケージしてAndroidアプリにできました。
しかも、ゲームのコードはほぼ書き換えていません。distフォルダをそのまま包むだけです。
ところが——です。
PCのChromeで完璧に動いていたゲームを、手元のMotorola実機に入れた瞬間、6か所が崩れました。重い、スクロールできない、画面が勝手に遷移する。全部、実機に入れて初めて見えた問題です。
この記事は、こういう人向けに書いています。
Reactは使っていないけど、作ったWebゲーム・Webアプリをスマホアプリにしたい人
「PCのブラウザで動くなら実機でも動くだろう」と思っている人
Capacitorの名前は聞くけど、実機で何が起きるのか知りたい人
結論から言うと、アプリ化そのものは一瞬で終わります。本番は、その後の実機テストです。
📌 まず、何を作っていたのか
題材は、私が個人で作ったWebゲームです
「バグだらけのゲームをQAテスターとして遊び、開発部に報告すると、開発部が壮大な言い訳を返してくる」という、ちょっとひねくれたゲームです。
たとえば、こんな言い訳が返ってきます。
> 「テストは書きました。通ったことは一度もありません。」
> 「タイムゾーンの問題です。お住まいの地域を変えることを検討ください。」
エンジニアなら一度は聞いたことがある(or言ったことがある)セリフですよね。この言い訳をオフラインの定型文として大量に仕込んでいます。
ちなみに、このゲームはデータ保存にSupabaseを一部使っています。その連携で警告を全部直したら逆に機能が壊れた話は実録#16に書きました。
技術構成はシンプルです。
Vite 6.3.5(ビルドツール)
TypeScript 5.6.3(フレームワークなし、素のTS)
Canvasで描画、一部にWebGLのCRT風エフェクト
データ保存にSupabaseを一部連携
ポイントは「Reactも何のUIフレームワークも使っていない」ことです。素のDOMとCanvasだけ。ここがCapacitorと相性が良かった理由でもあります。
📌 なぜExpoではなくCapacitorだったのか
私は別のアプリではExpoを使っています。なのに、なぜこのゲームだけCapacitorなのか。
答えはシンプルです。このゲームがReact Nativeではないからです。
ExpoはReact Native前提の仕組みです。React Nativeで書いていないアプリをExpoに載せようとすると、丸ごと書き直すことになります。せっかくVite+TSで完成しているWebゲームを、わざわざReact Nativeに移植する理由はありません。
ここで選択肢になるのがCapacitorです。
Capacitorは「今あるWebアプリを、ほぼそのままネイティブアプリの皮で包む」ツールです。中身はWebView。つまり、アプリの中で小さなブラウザが動いていて、そこに自分のdistフォルダを表示しているだけです。
整理すると、こういう棲み分けになります。
React Nativeで書いている → Expo
Webの技術(HTML/CSS/JS/Canvas)で完成している → Capacitor
あなたのプロジェクトはどちらでしょうか。すでにブラウザで動くものができているなら、Capacitorは最短ルートになります。
📌 Capacitorの仕組み:なぜコードを書き換えずに動くのか
Capacitorのアーキテクチャは、拍子抜けするほど単純です。
1. dist(ビルド済みのWeb成果物)を用意する
2. Capacitorがネイティブのandroidプロジェクトを生成する
3. そのアプリの中のWebViewが、distのindex.htmlを読み込む
4. WebViewの中で、いつものWebアプリが動く
設定ファイルも数行です。実際のcapacitor.config.tsはこれだけでした。
appId(アプリの識別子)
appName(表示名)
webDir(包む対象のフォルダ。distを指定)
たったこれだけ。だからコードの書き換えがほぼ不要なんです。ブラウザで動くものは、WebViewでも基本そのまま動きます。
……「基本」と書いたのがミソです。
WebViewは「PCのChrome」ではありません。スマホの実機の中で動く、画面の小さいブラウザです。ここに、今回ハマった全ての原因が詰まっていました。
📌 「PCで動く」と「スマホ実機で快適に動く」は別物だった
ビルドして、実機に入れて、起動しました。アプリは立ち上がりました。タイトルも出ました。
「お、いけたじゃん」と思った数秒後に、現実が来ます。
重いんです。PCではヌルヌル動いていたゲームが、Motorola実機ではもっさり。ゲームとして成立しないレベルでした。
これを皮切りに、実機テストで出てきた問題が合計6件。リストにするとこうです。
1. 処理が重い — ゲーム全体がもっさりして、操作が気持ちよくない
2. ステージクリア後に、なぜか別画面(ステージ作成画面)へ誤遷移する
3. スクロールできない — ステージ作成画面とバグ一覧画面で下にスクロールが効かない
4. レース課が難しすぎる — 道幅が狭い、車が速い、NPCが走っていない
5. 操作マニュアルがすぐ消える — 一度閉じると二度と見られない
6. ヒントがすぐ消える — 同上、再表示する手段がない
注目してほしいのは、この6件は1件もPCのブラウザでは再現しなかったことです。
なぜか。原因を方向性だけ先に書いておきます。
1(重い)は、Canvasの解像度とWebGLエフェクトが実機のGPUに重すぎた
2(誤遷移)は、画面遷移時のコールバックの消し忘れ。PCでは偶然踏まなかった
3(スクロール不可)は、touchmoveのpreventDefault。これがWebViewのタッチスクロールを殺していた
4(レース難しすぎ)は、PCのキーボード前提の難易度をタッチ操作に持ち込んだミスマッチ
5・6(消える)は、PCなら気にならない一度きりのUIが、スマホだと致命的だった
ここまでが「なぜ起きるか」の話です。ここは無料で全部出しました。仕組みが分かれば、AIに「touchmoveのpreventDefaultでスクロールが死ぬ問題を直して」と投げることもできます。
この記事の有料部分は、ここから先の「実際にどう直したか」「Capacitor導入から実機に入れるまでの完全手順」「次に同じことをやる人のためのチェックリスト」です。
📌 この記事で手に入るもの
読み終わると、あなたは次の状態になります。
Vite+TSのWebアプリを、コマンド数本でAndroidアプリ化できる
実機で「重い」「スクロールできない」が起きたとき、原因の当たりがつく
実機テストの前に潰すべきポイントを、チェックリストで先回りできる
有料部分の目次は、隠さず全部見せます。
1. Capacitor導入の完全手順(インストール〜実機インストールまでのコマンド全部)
2. 設計判断:なぜExpo/PWAではなくCapacitorにしたか、捨てた選択肢
3. 重さを消した2つの設定(Canvas解像度・CRTエフェクト)の具体的な変更
4. touchmoveでスクロールが死ぬ問題の、正しいpreventDefaultの当て方
5. 画面遷移でコールバックが残るバグの直し方
6. タッチ操作向けに難易度を作り直す勘所(レース課の調整)
7. 「一度きりのUI」を実機で殺さない設計
8. Wi-Fiデバッグ(USBケーブルなし)で実機テストを回す方法
9. 実機テスト前チェックリスト(コピペで使える)
10. そのまま動くコード一式(付録)
◀ 前回: EASのビルド枠を使い切っても、Expoアプリは実機に入る【実録#20・無料枠が尽きた】
📚 シリーズ全話はまとめマガジンへ
https://note.com/lazy_engineer/m/m03a726b1673c
💡 ここから先は有料です
自分でゼロから実機テストをやると、「重い」「スクロールできない」の原因特定だけで数時間溶けます。私が実機に入れて6か所踏んで直した手順とコードを、まとめて置いておきます。これは、その試行錯誤の時間を¥500で省略するものです。
---