diff --git "a/docs/ENV_04_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" "b/docs/ENV_04_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" index b609f72..06c1f56 100644 --- "a/docs/ENV_04_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" +++ "b/docs/ENV_04_\343\202\271\343\203\236\343\203\233\345\256\237\346\251\237\343\203\207\343\203\220\343\203\203\343\202\260\346\211\213\351\240\206.txt" @@ -3,67 +3,120 @@ ======================================================================== -1. 基本手順 (Basic Steps) +1. 概要 (Overview) ------------------------------------------------------------------------ -1-1. 事前準備と起動 (Preparation & Launch) - ・PC とスマホを同一の Wi-Fi ネットワークに接続する． - ・VS Code でターミナルを開く (`Ctrl + @`)． - ・以下のコマンドを実行し，ホストモードで開発サーバーを起動する． - $ pnpm --filter client dev -- --host - ・ターミナルに表示された「Network」の URL を確認する． - - 例: http://192.168.1.10:5173 - - ※ Vite のデフォルトポートは 5173 だが，状況により異なる場合がある． +1-0. 目的 + 本ドキュメントは，開発中のWebゲーム「Pixel Paint War」をスマホ実機で動作 + 確認するための手順書である． + 学校や組織のネットワーク（Fortinet等）による制限や，WSL2特有のネットワー + クの壁を回避するため，トンネリングツール「ngrok」を使用した外部公開手順 + を採用する． -1-2. PC の IP アドレス確認 (Check IP Address) - ・ターミナルに表示された Network URL (例: 192.168.1.10) を使用する． - ・表示されない場合は以下の手順で確認する． - - ■ Windows の場合 - 1. Win + R キーを押し，「cmd」と入力して Enter キーを押下する． - 2. コマンドプロンプトで以下のコマンドを実行する． - $ ipconfig - 3. 表示された「IPv4 アドレス」の数値を控える． - - ■ Mac の場合 - 1. 「システム設定」＞「ネットワーク」を開く． - 2. 接続中の Wi-Fi の「詳細」をクリックし，IP アドレスを確認する． - -1-3. スマホからのアクセス (Access from Smartphone) - ・スマホのブラウザ（Safari，Chrome 等）を起動する． - ・アドレスバーに以下の形式で URL を入力し，アクセスする． - - 書式: http://[PCのIPアドレス]:[ポート番号] - - 例: http://192.168.1.10:5173 +1-1. 前提条件 + ・WSL2 (Ubuntu等) 上で開発環境が構築済みであること． + ・ngrok の公式サイトでアカウント作成済みであること． + ・Authtoken (認証トークン) が取得済みであること． -2. トラブルシューティング (Troubleshooting) +2. ngrokのインストール (Installation) +------------------------------------------------------------------------ +Linux (WSL2) 環境へのインストール手順を記述する． +※ apt パッケージマネージャ経由ではエラーが発生しやすいため，バイナリ直接 +インストール方式を採用する． + +2-1. ダウンロードと配置 + 1. 圧縮ファイルのダウンロード + ターミナルで以下のコマンドを実行し，Linux版バイナリを取得する． + $ wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz + + 2. 解凍とインストール + ダウンロードしたファイルを解凍し，実行パスの通ったディレクトリに移動する． + $ sudo tar xvzf ngrok-v3-stable-linux-amd64.tgz -C /usr/local/bin + + 3. 動作確認 + バージョン情報が表示されるか確認する． + $ ngrok --version + ※ "ngrok version 3.x.x" 等と表示されれば成功である． + +2-2. アカウント認証 (Authentication) + ngrok のダッシュボード (https://dashboard.ngrok.com/get-started/your-authtoken) + からトークンを確認し，以下のコマンドで設定する． + + ■ トークンの登録 + $ ngrok config add-authtoken [あなたのAuthtoken] + ※ "[あなたのAuthtoken]" の部分は実際の文字列に置き換える． + + +3. デバッグ実行手順 (Execution Steps) ------------------------------------------------------------------------ -2-1. 接続できない場合の確認事項 - ■ ネットワーク設定 - ・PC とスマホが同じ Wi-Fi に接続されているか確認する． - - ※ ゲスト用 Wi-Fi など，機器間の通信が遮断されているネットワークでは接続できない． +3-1. Client設定の修正 (Update Configuration) + 開発サーバーが外部 (ngrok) からの接続を受け付けるよう，設定を変更する． - ■ ファイアウォール設定 - ・PC のセキュリティソフトやファイアウォールが，外部からの接続をブロックしている可能性がある． - - 対策: 一時的にファイアウォールを無効化するか，Node.js (node.exe) の通信を許可する設定を追加する． + ■ package.json の編集 + `apps/client/package.json` を開き，`scripts` ブロックの `dev` コマンドに `--host` オプションを追加する． - ■ WebSocket 接続エラー (Game Loop が動かない場合) - ・クライアントコード (`apps/client/src/config` 等) の接続先設定を確認する． - ・接続先が `ws://localhost:xxxx` の場合，スマホからは接続できない． - - 対策: PC の IP アドレス (例: `ws://192.168.1.10:xxxx`) に書き換える． + [修正前] + "dev": "vite" + + [修正後] + "dev": "vite --host" + +3-2. 開発サーバーの起動 (Launch Dev Server) + まず，ローカル環境でアプリケーションを起動する． + + ■ Clientアプリの起動 + プロジェクトルートで以下のコマンドを実行する． + $ pnpm --filter client dev + ※ ターミナルに `Network: http://x.x.x.x:5173/` と表示されれば設定成功である． + +3-3. ngrokによる公開 (Expose via ngrok) + 新しいターミナルウィンドウを開き，以下の手順でトンネルを作成する． + + 1. ngrokの起動 + Vite の Host ヘッダーチェックを回避するため，オプションを付与して実行する． + $ ngrok http 5173 --host-header="localhost" + + 2. 公開URLの確認 + 起動後に表示されるステータス画面から，"Forwarding" の行を確認する． + + Session Status online + Account User Name (Plan: Free) + Forwarding https://xxxx-xxxx.ngrok-free.app -> http://localhost:5173 + + 上記の "https://xxxx-xxxx.ngrok-free.app" が公開URLとなる． + +3-4. スマホからのアクセス (Access from Smartphone) + 1. URLの共有 + 発行された URL をスマホに送信する（QRコード作成ツールやチャット等を使用）． + + 2. ブラウザでの確認 + スマホのブラウザ（Chrome，Safari等）で URL にアクセスする． + タイトル画面が表示されれば接続成功である． -3. 外部ネットワークからの接続 (Port Forwarding) +4. 注意事項とトラブルシューティング (Notes & Troubleshooting) ------------------------------------------------------------------------ -3-0. 概要 - ・VSCode 標準のポート転送機能を使用し，異なるネットワーク（4G/5G や外部 Wi-Fi）からデバッグを行う手順． +4-1. Freeプランの制限 + ・同時接続数: Freeプランでは同時に1つのポートしか公開できない． + ・Client/Server構成の注意: + 本手順ではフロントエンド (Port 5173) のみ公開している． + バックエンド (Port 3000) への WebSocket 通信が必要な場合，ゲーム開始時 + に接続エラーとなる可能性がある． + - 対策: UIレイアウトや描画負荷の確認を主目的として使用する． -3-1. 設定手順 - 1. VSCode 下部パネルの「ポート (Ports)」タブを選択する． - 2. 「ポートの追加」ボタンを押し，Live Server のポート番号（例: 5500）を入力する． - 3. 追加されたポートの「可視性 (Visibility)」列を右クリックし，「パブリック (Public)」に変更する． - 4. 「転送されたアドレス」列に表示された URL をコピーする． - - 書式: https://[ランダムな文字列].vscode-server.net... - 5. 発行された URL をスマホに送り，ブラウザで開く． \ No newline at end of file +4-2. エラー対応 + ■ "ERR_NGROK_3200" (Tunnel already open) + ・既に別のターミナルで ngrok が起動している場合に発生する． + - 対策: 起動中の ngrok を終了 (Ctrl + C) してから再実行する． + + ■ "Invalid Host Header" (画面が真っ白になる) + ・Vite が不正なドメインからのアクセスを拒否している． + - 対策: 起動コマンドに `--host-header="localhost"` が含まれているか再確認する． + + ■ "ERR_CERT_AUTHORITY_INVALID" (Fortinet等の警告) + ・ngrok を使用せずローカルIPで接続しようとした場合に，組織内ネットワーク + のセキュリティ機器にブロックされる現象である． + - 対策: 必ず本手順の ngrok 経由 (https) で接続する． \ No newline at end of file