VS Codeは手元のWindowsまたはLinuxにインストールし、ソースコード、ビルドツール、macOS専用の拡張機能はリモートMac側で動かしてください。SSHログインを先に成功させ、VS Code Server、遠隔側のShell、Apple Silicon対応、実プロジェクト、再接続を順に確認すれば、設定の失敗箇所を特定できます。

この構成は、コマンドライン中心の開発や自動ビルドに向いています。Xcodeの画面操作、シミュレーター、署名確認などが必要な工程では、SSHに加えてリモートデスクトップを用意してください。

このガイドの対象

WindowsまたはLinuxでコーディングしながら、Swift、Xcode、macOS専用ツールチェーンをリモートMacで実行したい開発者向けです。

チーム共通の開発ノード、ユーザーごとの権限分離、常時稼働するビルド環境を整えたいDevOpsエンジニアにも適しています。すでにSSHではログインできるものの、拡張機能、PATH、デバッグ、再接続で止まっている場合も、後述の確認順で切り分けられます。

VS Code Remote SSHの構成を4つに分ける

VS Code Remote SSH リモート Macの構成は、次の4要素を別々に考えると混乱しません。VS Codeの公式Remote Development概要でも、ローカル側のクライアントと遠隔側の開発環境を分けて説明しています。

  • ローカルのVS Code：画面表示、操作、接続管理を担当します。
  • SSH通路：手元のPCとMacの間で認証と通信を行います。
  • VS Code Server：リモートMac側でVS Codeの遠隔操作を受け持ちます。
  • 遠隔側のツールチェーン：Git、コンパイラー、言語サーバー、デバッガー、プロジェクト依存関係を実行します。

Remote Developmentの公式概要では、ソースコードや開発ツールを遠隔環境で扱う方式が説明されています。したがって、端末でSSHに入れただけでは、VS Codeによる開発環境全体が使えるとは判断できません。

受け入れ基準は、次の4段階に分けます。

  • 接続可能：鍵認証でSSHに入り、対象ホストを識別できる。
  • 編集可能：VS Code Serverが起動し、遠隔ワークスペースを開ける。
  • ビルド可能：遠隔側の依存関係、タスク、デバッガーが実際に動く。
  • 復旧可能：切断、Macの再起動、長時間処理の後でも再接続できる。

まずmacOS Remote Loginと鍵認証を確認する

Mac側では「システム設定」の共有項目からRemote Loginを有効にし、接続を許可するユーザーを限定します。AppleのRemote Login公式ガイドでも、SSHによる接続を受け付ける機能として案内されています。

最初からVS Codeで接続せず、次の順番で確認してください。

  1. Macのホスト名またはIPアドレスを確認します。
  2. 接続対象のユーザー名と、許可されたログインユーザーを一致させます。
  3. 公開鍵をMac側のSSH設定へ登録します。
  4. 手元の端末からssh user@hostを実行します。
  5. whoami、pwd、uname -mを実行し、ユーザー、作業場所、CPUアーキテクチャを記録します。
  6. パスワード入力を求められる場合は、鍵の指定、SSHエージェント、Mac側の公開鍵配置を確認します。

Appleのターミナルからサーバーへ接続する手順も、まず端末から接続する流れを示しています。ここで失敗するなら、VS Codeのログを調べても根本原因は解決しません。

SSHの接続先をIPアドレスだけで管理すると、別のMacへ接続しても気付きにくくなります。ホスト別の別名、ユーザー名、鍵ファイルをSSH設定にまとめ、接続直後にhostnameとwhoamiを確認してください。

VS Code Serverと遠隔側拡張機能を分けて検証する

端末SSHが通ったら、手元のVS CodeにRemote - SSH拡張機能を導入し、接続先を選びます。初回接続では、VS CodeがリモートMac側のVS Code Serverを準備し、セッションを開始します。公式のRemote - SSH設定ガイドでは、接続先の登録、リモートフォルダーの選択、ターミナル利用までの流れが説明されています。

確認すべき証拠は次のとおりです。

  • 初回接続：接続先のホスト名が想定どおりで、VS Code Serverのセットアップが完了する。
  • ワークスペース接続：Mac上の実在するプロジェクトディレクトリを開ける。
  • 遠隔ターミナル：whoami、pwd、echo $PATHの結果がMac側の値になる。
  • 再接続：VS Codeを閉じて接続し直しても、同じMacとプロジェクトを開ける。

VS Code Serverの導入で停止する場合は、Mac側から必要なファイルを取得できるか、または手元のVS Codeから転送できるかを確認します。エラーの段階は、Remote - SSHのトラブルシューティング公式資料に沿って、SSH認証、Server導入、セッション開始の順に切り分けてください。

拡張機能はすべて同じ場所で動くわけではありません。VS Codeの遠隔拡張機能の実行場所に関する公式説明を確認し、言語サービス、デバッガー、フォーマッター、ビルド連携がローカルとリモートのどちらで起動するかを個別に確認します。

PATHとプロジェクト依存関係を固定する

Remote SSH接続後に「手元の端末では動くのに、VS Codeのタスクでは失敗する」場合、対話的なログインShellとVS Code Serverの起動環境が異なっている可能性があります。

遠隔側のVS Codeターミナルで、次の値を確認します。

  • which git、which swift、which xcodebuild
  • echo $PATH
  • whoami
  • pwd
  • プロジェクトが想定するNode.js、Python、Goなどのバージョン
  • Gitのユーザー設定、SSH鍵、署名設定

シェル設定を手作業で追加するだけでは、別ユーザーや新しいセッションで再現できません。プロジェクトのロックファイル、バージョン管理ツール、初期化スクリプト、CI用のセットアップ処理を使い、依存関係と環境変数を明示してください。

特に、VS Codeのタスク、デバッグ構成、Gitフック、外部スクリプトは、それぞれ異なる起動経路を持つことがあります。ターミナルで成功したコマンドを、そのままタスクでも実行し、実行ユーザー、作業ディレクトリ、PATHをログへ出すと差分を発見できます。

Apple Siliconと拡張機能の互換性を個別に判定する

Apple SiliconのリモートMacを選んでも、すべての開発用拡張機能が自動的に対応するわけではありません。確認対象は、MacのCPUアーキテクチャ、プロジェクトのターゲット、拡張機能の実行場所、拡張機能が呼び出す外部バイナリです。

uname -mで遠隔Macのアーキテクチャを確認したうえで、次を分けて検証します。

  • 言語サーバーが遠隔Macで起動するか。
  • デバッガーが対象ランタイムを認識するか。
  • フォーマッターやリンターの実行ファイルが動くか。
  • 拡張機能が必要とするNode.jsなどのランタイムが遠隔側にあるか。
  • プロジェクトのターゲットアーキテクチャと依存バイナリが一致するか。

拡張機能のインストール成功は、ビルドやデバッグの成功を意味しません。対応アーキテクチャが不明な場合は、拡張機能の公式サポート情報とリリースノートを確認し、実際のコマンドをプロジェクト内で実行してください。

実プロジェクトで編集、ビルド、デバッグを通す

空のフォルダーを開くだけでは、開発環境の検証として不十分です。実際に使うリポジトリを取得し、次の順で確認します。

  1. VS Codeから遠隔Mac上のリポジトリを開きます。
  2. 依存関係をプロジェクト指定の方法でインストールします。
  3. ソースファイルを編集し、保存時の言語サービスを確認します。
  4. VS Codeのタスクからビルドまたはテストを実行します。
  5. Gitの差分確認、ブランチ切り替え、コミット前の検証を行います。
  6. デバッガーを起動し、ブレークポイント、変数表示、ステップ実行を確認します。
  7. 必要なポートを転送し、ローカルのブラウザーやクライアントから動作を確認します。

Xcodeプロジェクトでは、コマンドラインからのビルドと、Xcode画面で必要な操作を分離してください。xcodebuildやテストスクリプトで完結する工程はSSHで処理できますが、シミュレーターの操作、証明書の選択、署名ダイアログなどはGUI接続が必要になることがあります。

この場合は、Macのレンタルプランを確認するページで、Apple Siliconの有無、root権限、SSHとリモートデスクトップの提供条件を確認し、契約前に自分のプロジェクトで同じ受け入れテストを実施してください。

接続方式を決めるための判定リスト

次の項目を上から確認し、該当する条件で運用方式を決めてください。チェックが付かない項目を無理に通過扱いにすると、接続後のビルド失敗やGUI作業の中断につながります。

一時的なビルドやテスト

  • [ ] SSH鍵認証で接続できる。
  • [ ] VS Code Serverが起動し、実プロジェクトを開ける。
  • [ ] 依存関係の導入とビルドが遠隔Mac側で完了する。
  • [ ] Xcodeの画面操作やシミュレーターを必要としない。

すべて確認できるなら、SSHのみの構成で進められます。どれか1つでも未確認なら、まず該当する工程を修正してから利用を開始してください。

日常的な遠隔開発

  • [ ] 遠隔ターミナルのPATH、ユーザー、作業ディレクトリが記録されている。
  • [ ] プロジェクトのロックファイルまたは初期化スクリプトで環境を再現できる。
  • [ ] 使用する言語サーバー、デバッガー、フォーマッターを遠隔側で確認できる。
  • [ ] VS Codeを終了しても、同じホストへ再接続できる。

すべて確認できる場合は、VS Code Remote SSHを主経路にします。PATHだけが不一致なら、拡張機能を増やす前にShell設定とプロジェクト初期化処理を修正してください。

Xcode画面やシミュレーターを使う開発

  • [ ] CLIビルドとGUI操作を工程ごとに分離している。
  • [ ] Xcode、シミュレーター、署名確認に使える画面接続がある。
  • [ ] SSHが切断されても、長時間処理のログを確認できる。
  • [ ] GUI接続が停止しても、コマンドライン工程を再開できる。

CLI項目だけを満たす場合はSSHを主経路にし、画面操作が必要な工程だけリモートデスクトップを併用してください。

複数人で共有する開発ノード

  • [ ] ユーザーごとにアカウントとSSH鍵を分けている。
  • [ ] プロジェクトディレクトリの所有者とアクセス権を定義している。
  • [ ] 共有アカウントや不要なroot操作に依存していない。
  • [ ] VS Code Serverと各ユーザーのホーム領域を分離している。

この条件を満たせない場合は、便利さを優先して共有運用へ進まず、まずアカウント境界と認証情報の扱いを見直してください。

常駐ビルドや自動化

  • [ ] Mac再起動後に必要なサービスが戻る。
  • [ ] SSH切断後も必要な処理を継続できる。
  • [ ] ビルドログと失敗理由を後から確認できる。
  • [ ] 異常終了後の再実行手順が決まっている。

ここまで確認できない環境は、一時的な開発には使えても、常時稼働するビルドノードとしては保留にしてください。

接続後のFAQ

WindowsからリモートMacへ接続する基本手順

Windows側のVS CodeにRemote - SSHを追加し、Mac側でRemote Loginと鍵認証を設定します。先にPowerShellなどからSSH接続を成功させ、接続先のユーザーとホスト名を確認してからVS Codeで同じ接続先を選択します。初回はVS Code Serverの導入ログも確認してください。

VS Code Serverの配置場所

VS Code Serverは、操作しているWindowsやLinuxではなく、接続先のリモートMac側で動きます。ローカルのVS Codeは画面と操作を担当し、遠隔側のServerがファイル検索、ターミナル連携、言語サービスなどを受け持ちます。拡張機能の実行場所は個別に異なるため、公式仕様を確認してください。

Remote SSH後にPATHが変わる場合

ログインShellで読まれる設定と、VS Code Serverの起動時に読まれる設定を分けて比較します。遠隔ターミナルでwhich、echo $PATH、whoami、pwdを実行し、失敗したタスクの実行環境と照合してください。個人のShell設定ではなく、プロジェクトの初期化処理で必要な環境を再現します。

Apple Siliconで拡張機能が動かない場合

拡張機能のインストール状態ではなく、言語サーバー、デバッガー、フォーマッター、外部バイナリがどこで実行されるかを確認します。対象拡張機能の公式サポート範囲にApple Siliconが含まれるか確認し、遠隔Macのアーキテクチャと依存ランタイムを実コマンドで検証してください。

XcodeプロジェクトをRemote SSHだけで扱えるか

ソース編集、Git、CLIビルド、テスト、スクリプト実行はRemote SSHで扱える場合があります。一方、Xcodeの画面、シミュレーター、署名関連のGUI操作はSSHだけでは完結しないことがあります。プロジェクトの工程をCLI部分とGUI部分に分け、必要なときだけリモートデスクトップを併用します。

長期運用前に安全性と復旧性を確認する

開発ノードとして使うなら、接続できることよりも、誰が何を実行できるかを先に決めます。SSH鍵、リポジトリの認証情報、署名資産、VS Code拡張機能の権限をユーザー単位で管理し、共有アカウントへの集約を避けてください。

確認項目は次のとおりです。

  • SSHの許可ユーザーが必要最小限になっている。
  • プロジェクトディレクトリの所有者とアクセス権が明確である。
  • VS Code Serverの待受方法を確認している。
  • 秘密鍵や署名ファイルをプロジェクトへ平文で保存していない。
  • Mac再起動後にRemote Loginと必要なサービスが戻る。
  • 長時間のビルドが切断後も想定どおり終了する。
  • 異常終了時にログから失敗箇所を追跡できる。

VS Code Remote SSHの接続仕様や既知の問題は、公式FAQとトラブルシューティング資料で定期的に再確認してください。macOSや拡張機能のバージョンを更新した後は、少なくとも実プロジェクトの読み込み、ビルド、デバッグ、再接続を再実行します。

現在のWindowsやLinuxだけで開発を続ける方法は、macOS専用ツールが必要になるたびに別マシンへ移動し、環境差分、GUI操作、常時稼働の不足を抱えやすい構成です。Linux上の仮想環境や一時的な共有端末も、Apple Silicon、署名、Xcodeの画面操作を同時に満たせるとは限りません。

SSHMacのリモートMacなら、SSHを中心にしたVS Code開発と、必要な場面のリモートデスクトップを同じ実機環境で確認できます。まず実プロジェクトの受け入れテストを行い、チップ構成、root権限、接続方式、利用期間が合う場合だけ、SSHMacの案内ページから一時利用または継続運用の条件を確認してください。