はじめに
同僚のジュニアエンジニアが開発用サーバー上で Web アプリを開発し、チームメンバーにレビューを依頼したところ、「開発者の PC では動くのにレビュアーの PC では API へのアクセスがうまくいかない」というトラブルが発生しました。
原因は VSCode の Remote SSH 拡張機能によるポート自動転送でした。同じような状況でハマる方の参考になればと思い、記録しておきます。
状況
開発者は VSCode の Remote SSH 機能を使って開発用サーバーに SSH 接続し、サーバー上で直接 Web アプリを開発していました。
ある程度実装が進んだところでチームメンバーにレビューを依頼し、開発用サーバーのアドレス（http://<サーバーアドレス>:3000 など）を共有しました。
レビュアーの PC からアプリ自体は表示できていたものの、API アクセスが常にエラーになるという報告が上がりました。
開発者自身の PC からは問題なく動作しているため、原因の見当がつきません。
チャットでのトラブルシュート
チャットで状況を確認しながらトラブルシュートを進めました。
- ブラウザのコンソールエラーを確認 →
net::ERR_CONNECTION_REFUSED - サーバー側のプロセスが起動しているか確認 → 正常に起動中
などの基本的な確認は行いましたが、原因は特定できませんでした。 チャットのやり取りだけでは原因が特定できず、最終的には画面共有で直接確認することにしました。
画面共有で判明した原因
開発者の画面を共有してもらったところ、VSCode のポートパネルに自動転送されているポートの一覧が表示されているのを確認しました。
原因は VSCode Remote SSH 拡張機能のポート自動転送機能でした。
何が起きていたのか
フロントエンドのコードを確認したところ、バックエンド API のエンドポイントが http://localhost:8080 にハードコードされていました。
Remote SSH 拡張機能には、アプリケーションが特定のポートでリッスンし始めると、そのポートをローカルマシンへ自動的にポートフォワードする機能があります。
開発用サーバー (port 8080) ←SSH接続+自動ポートフォワード→ 開発者のローカル (localhost:8080)アプリ自体は開発用サーバーのアドレスで共有されていたため、レビュアーの PC からもフロントエンドは表示できていました。
しかし、フロントエンドから発行される API リクエストの宛先は http://localhost:8080 — つまりリクエストを送信しているブラウザが動いている PC の localhost です。
開発者の PC では VSCode が自動でポートフォワードを行っていたため localhost:8080 が開発用サーバーのバックエンドに透過的に繋がっており、問題が表面化していませんでした。
一方レビュアーの PC にはその転送が存在しないため、http://localhost:8080 はどこにも繋がらず ERR_CONNECTION_REFUSED になっていました。
この機能はローカル開発時には非常に便利ですが、自分だけしか使わないことを前提とした設定になりがちです。
他者にレビューしてもらう場合は、API エンドポイントをローカルアドレスではなくサーバーの実際のアドレスに変更する必要があります。
解決策
フロントエンドの API エンドポイント設定を http://localhost:8080 から、開発用サーバーのアドレスを使った http://<サーバーアドレス>:8080 に変更することで、レビュアーの PC からも正常にアクセスできるようになりました。
具体的には以下のように環境変数を用いて切り替えられるようにしました。
# .env.development.local（開発者のローカル用）
VITE_API_BASE_URL=http://localhost:8080
# .env.development（チーム共有用）
VITE_API_BASE_URL=http://<サーバーアドレス>:8080まとめ
今回のトラブルの根本原因は、バックエンドの API エンドポイントが http://localhost:8080 にハードコードされており、VSCode Remote SSH のポート自動転送によって開発者本人の環境では問題が隠れていた点でした。
アプリ自体は開発用サーバーのアドレスで共有できていたため「なぜ人によって動かないのか」が一見わかりにくく、原因特定に時間がかかりました。
便利な機能ほど裏で何が起きているかを把握しておくことが重要だと改めて感じました。
コメント