VSCodeでリモート開発する方法

VSCode（Visual Studio Code）には、ローカルPCとは別の環境を利用して開発できる「リモート開発」の仕組みがあります。

VSCodeの画面自体は手元のPCで操作しながら、ソースコードの保存やプログラムの実行、ターミナル操作、デバッグなどをリモート側の環境で行えるのが特徴です。

たとえば、Windows PCからLinuxサーバーへ接続して開発したり、Windows上のWSLをLinux開発環境として利用したり、Dockerコンテナの中をそのまま開発環境として利用したりできます。

リモート開発を活用すると、開発環境をローカルPCから分離できるため、OSやライブラリの違いによるトラブルを減らしやすくなります。

また、高性能なサーバーやクラウドVMを利用すれば、ローカルPCの性能に依存しにくい開発環境を構築することも可能です。

VSCodeで利用できる主なリモート開発方法

VSCodeでは、主に次の方法でリモート開発を行えます。

• Remote – SSH
• WSL
• Dev Containers
• Remote – Tunnels

これらは用途や接続先が異なるため、開発環境に合わせて使い分けることが重要です。

Remote – SSH

Remote – SSHは、SSHで接続できるリモートマシンをVSCodeの開発環境として利用する方法です。

LinuxサーバーやクラウドVMで利用されることが多いですが、条件を満たすWindowsやmacOSのSSHホストへ接続することもできます。

リモートサーバーに保存されているファイルをVSCodeから直接編集できるため、ファイルをローカルPCへコピーして作業する必要がありません。

WSL

WSLは「Windows Subsystem for Linux」の略で、Windows上でLinux環境を利用するための仕組みです。

VSCodeのWSL拡張機能を使えば、Windows版VSCodeの画面を利用しながら、Linux側のPythonやNode.js、Gitなどを使って開発できます。

WindowsユーザーがLinux向けのWeb開発やプログラミングを行う場合に適しています。

Dev Containers

Dev Containersは、DockerコンテナをVSCodeの開発環境として利用する仕組みです。

Node.jsやPythonなどのランタイム、ライブラリ、VSCode拡張機能などをコンテナ側にまとめて管理できます。

チームメンバー全員で同じ開発環境を利用したい場合にも便利です。

Remote – Tunnels

Remote – Tunnelsは、SSHサーバーを用意せずにリモートPCやVMへ接続できる仕組みです。

MicrosoftのDev Tunnelsを利用して接続するため、SSHポートを直接公開しにくい環境でも利用できる場合があります。

ただし、企業や組織で利用する場合は、ネットワークやセキュリティポリシーで使用が許可されているか確認する必要があります。

Remote – SSHでリモート開発する方法

リモートサーバー上で開発したい場合は、Remote – SSHが代表的な方法です。

SSH接続できるサーバーがすでに用意されていれば、比較的簡単にVSCodeから接続できます。

SSHで接続できるか確認する

最初に、VSCodeを使わず通常のSSHコマンドでサーバーへ接続できることを確認します。

WindowsではPowerShellやWindows Terminal、macOSやLinuxではターミナルを開き、次のように実行します。

ssh username@example.com

IPアドレスを指定する場合は、次のようになります。

ssh username@192.168.1.100

AWS EC2などでは、次のようにユーザー名とIPアドレスを指定することもあります。

ssh ubuntu@203.0.113.10

この段階でSSH接続できない場合は、VSCode側からも接続できません。

まず、SSHサーバーの設定、ユーザー名、IPアドレス、ポート番号、ファイアウォールなどを確認します。

Remote – SSHをインストールする

VSCodeを起動し、左側の「拡張機能」を開きます。

検索欄に次のように入力します。

Remote - SSH

Microsoftが提供しているRemote – SSH拡張機能をインストールします。

WSLやDev Containersなども使う予定がある場合は、「Remote Development」拡張機能パックを利用する方法もあります。

VSCodeからSSHサーバーへ接続する

Remote – SSHをインストールしたら、コマンドパレットを開きます。

WindowsやLinuxでは、次のショートカットを使用します。

Ctrl + Shift + P

macOSでは次のショートカットです。

Command + Shift + P

コマンドパレットから、次のコマンドを選択します。

Remote-SSH: Connect to Host...

続いて、接続先のホストを指定します。

たとえば次のように入力します。

username@example.com

接続すると新しいVSCodeウィンドウが開き、リモート側にVSCodeと連携するためのサーバーコンポーネントがセットアップされます。

リモート側のフォルダを開く

SSH接続が完了したら、VSCodeの「File」メニューから「Open Folder」や「Open…」などを選び、リモート側のフォルダを開きます。

たとえば、次のようなディレクトリを指定します。

/home/user/project

このとき、ファイルはローカルPCにコピーされるわけではありません。

実際のソースコードはリモートサーバー側に保存されたままです。

リモート側のターミナルを利用する

Remote – SSHで接続した状態でVSCodeの統合ターミナルを開くと、基本的にはリモート側のシェルが起動します。

たとえば次のコマンドを実行します。

pwd

次のようにリモートサーバー上のパスが表示されれば、リモート側のターミナルを操作していることが確認できます。

/home/user/project

PythonやNode.js、Gitなどのコマンドも、原則としてリモート側の環境で実行されます。

SSH設定ファイルを利用する方法

毎回ユーザー名やホスト名を入力するのが面倒な場合は、SSH設定ファイルを利用すると便利です。

SSH設定ファイルの場所

macOSやLinuxでは、一般的に次のファイルを使用します。

~/.ssh/config

Windowsでは、通常は次の場所にあります。

C:\Users\ユーザー名\.ssh\config

SSHホストを登録する

たとえば次のように記述します。

Host development-server
    HostName 203.0.113.10
    User ubuntu
    IdentityFile ~/.ssh/id_ed25519

この設定を行うと、通常のターミナルから次のコマンドで接続できるようになります。

ssh development-server

VSCodeの「Remote-SSH: Connect to Host…」にもdevelopment-serverが表示されるため、接続操作を簡略化できます。

SSH公開鍵認証を利用する方法

Remote – SSHではパスワード認証も利用できますが、継続的な開発ではSSH公開鍵認証を利用する方法が一般的です。

公開鍵認証を利用すると、パスワード入力の手間を減らしながら安全に接続しやすくなります。

SSH鍵を作成する

Ed25519形式のSSH鍵を作成する場合は、次のコマンドを実行します。

ssh-keygen -t ed25519

通常は次の2つのファイルが作成されます。

~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub

id_ed25519は秘密鍵です。

秘密鍵は他人に渡したり、Gitリポジトリへ登録したりしないよう注意が必要です。

id_ed25519.pubは公開鍵です。

公開鍵は接続先のサーバーへ登録します。

公開鍵をサーバーへ登録する

Linuxサーバーの場合は、一般的に接続先ユーザーの次のファイルへ公開鍵を登録します。

~/.ssh/authorized_keys

正しく設定できれば、SSH鍵を使ってサーバーへ接続できるようになります。

VSCodeの拡張機能はローカルとリモートのどちらで動くのか

VSCodeのリモート開発では、すべての拡張機能が同じ場所で動作するわけではありません。

拡張機能の種類によって、ローカル側で動作するものとリモート側で動作するものがあります。

UI関連の拡張機能

テーマなど、主にVSCodeの画面表示に関係する拡張機能はローカル側で動作することがあります。

プログラミング関連の拡張機能

PythonやPHPなどの言語サーバー、デバッガー、Lint関連の拡張機能は、リモート環境側で動作する場合があります。

VSCodeは拡張機能の性質に応じて、ローカル側またはリモート側で動作させます。

Remote – SSH接続中に拡張機能の画面を開くと、ローカル側とリモート側のインストール状況を確認できます。

ポートフォワーディングを利用する方法

リモートサーバー上でWebアプリケーションを開発するときは、ポートフォワーディングを利用すると便利です。

たとえば、リモートサーバー上で次のように開発サーバーを起動したとします。

npm run dev

アプリケーションがリモート側の3000番ポートで動作している場合、VSCodeのポート転送機能を利用するとローカルPCのブラウザからアクセスできます。

VSCodeからポートを転送する

VSCodeの「Ports」ビューなどから、リモート側のポート番号を指定して転送できます。

たとえばリモート側の3000番ポートを転送すると、ローカルPCから次のようなURLでアクセスできます。

http://localhost:3000

ただし、ローカル側の3000番ポートがすでに使用されている場合などは、別のローカルポートへ割り当てられることがあります。

SSH設定ファイルから転送する

SSHの設定ファイルにLocalForwardを設定する方法もあります。

Host development-server
    HostName 203.0.113.10
    User ubuntu
    LocalForward 127.0.0.1:3000 127.0.0.1:3000

この設定では、ローカルPCの3000番ポートへのアクセスを、リモートサーバー側の3000番ポートへ転送します。

WSLを使ってリモート開発する方法

Windowsユーザーの場合は、WSLを利用した開発も便利です。

WSLを利用すると、Windows上でLinux環境を動かせます。

WSL拡張機能を利用する

VSCodeへWSL拡張機能をインストールすると、Windows版VSCodeからWSL環境へ接続できます。

たとえばWSLターミナルで次のようにプロジェクトへ移動します。

cd ~/projects/sample

続いて次のコマンドを実行します。

code .

すると、そのフォルダをWSL環境としてVSCodeで開けます。

VSCodeの統合ターミナルを開いた場合も、基本的にはWSL側のシェルが起動します。

WSLではファイルの保存場所に注意する

WSLでは、Windows側のファイルを次のようなパスから利用できます。

/mnt/c/Users/...

一方、Linux用のツールを中心に利用する場合は、次のようなWSLのLinuxファイルシステムへプロジェクトを保存したほうが、ファイルI/Oのパフォーマンス面で有利な場合があります。

/home/user/projects/

または、

~/projects/

ただし、Windows側のツールを中心に利用するのであれば、Windows側へファイルを置いたほうが適している場合もあります。

利用するツールに合わせて保存場所を選ぶことが重要です。

Dev Containersでリモート開発する方法

Dockerを利用している場合は、Dev Containersを使ってコンテナ自体を開発環境にできます。

Dev Containersのメリット

Dev Containersでは、プログラミング言語やライブラリ、VSCode拡張機能などを設定ファイルで管理できます。

そのため、チームメンバーごとに開発環境が異なる問題を減らしやすくなります。

たとえば、次のような環境を統一できます。

Node.js
Python
PHP
Git
各種CLIツール
VSCode拡張機能

devcontainer.jsonを作成する

通常は、プロジェクト内に次のようなファイルを用意します。

.devcontainer/
└── devcontainer.json

または、プロジェクトルートに.devcontainer.jsonを置く方法もあります。

設定例は次のとおりです。

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node",
  "forwardPorts": [3000],
  "customizations": {
    "vscode": {
      "extensions": [
        "streetsidesoftware.code-spell-checker"
      ]
    }
  }
}

forwardPortsでは、コンテナ側のポートをVSCodeから利用しやすいよう指定できます。

customizations.vscode.extensionsでは、コンテナ環境で利用するVSCode拡張機能を指定できます。

コンテナでプロジェクトを開く

設定ファイルを作成したら、コマンドパレットから次のコマンドを実行します。

Dev Containers: Reopen in Container

すると、VSCodeがコンテナ環境としてプロジェクトを開き直します。

Docker ComposeとDev Containersを組み合わせる

Dev Containersは、単一コンテナだけでなくDocker Composeを利用した複数コンテナ構成にも対応しています。

たとえば次のような構成で開発できます。

Webアプリ
↓
Node.js

データベース
↓
PostgreSQL

キャッシュ
↓
Redis

Webアプリケーション、データベース、キャッシュなどを別々のコンテナとして管理しながら、VSCodeから開発できます。

Remote – SSHとDev Containersを組み合わせる

Remote – SSHとDev Containersを組み合わせれば、リモートサーバー上のDockerコンテナをそのまま開発環境として利用できます。

構成は次のようになります。

ローカルPC
↓
Remote - SSH
↓
リモートサーバー
↓
Docker
↓
Dev Container

まずRemote – SSHでサーバーへ接続し、リモートサーバー上のプロジェクトを開きます。

続いて、コマンドパレットから次のコマンドを実行します。

Dev Containers: Reopen in Container

すると、リモートサーバー上で動作しているコンテナをVSCodeの開発環境として利用できます。

高性能なCPUやGPUを搭載した開発サーバーを利用したい場合にも便利な構成です。

Remote – Tunnelsを利用する方法

SSHサーバーを用意しにくい場合は、Remote – Tunnelsを利用する方法があります。

Remote – Tunnelsでは、MicrosoftのDev Tunnelsを利用してリモートマシンと接続します。

code tunnelを実行する

リモート側で、次のコマンドを実行します。

code tunnel

認証などを行うとトンネルが作成され、対応するVSCodeやブラウザからリモート環境へ接続できます。

Remote – TunnelsではSSHサーバーを構築する必要がないため、SSHを利用しないリモート開発の選択肢になります。

ただし、企業や組織のネットワークで利用する場合は、Dev Tunnelsの利用が許可されているか確認する必要があります。

GitHub Codespacesを利用する方法

自前のリモートサーバーを管理したくない場合は、GitHub Codespacesを利用する方法もあります。

GitHub Codespacesは、GitHubが提供しているクラウド型の開発環境です。

GitHub上に開発環境を作成し、ブラウザ版VSCodeやデスクトップ版VSCodeから接続できます。

なお、GitHub CodespacesはRemote – SSHやWSLなどと同様にリモート開発で利用できますが、「Remote Development」拡張機能パックに含まれる4つの拡張機能とは別のサービスとして考えると分かりやすいでしょう。

リモート環境でデバッグする方法

Remote – SSHなどでリモート環境へ接続している場合でも、通常のVSCodeと同じようにデバッグ機能を利用できます。

必要に応じて、次のファイルへデバッグ設定を記述します。

.vscode/launch.json

デバッグ設定ができていれば、次のキーからデバッグを開始できます。

F5

アプリケーション自体はリモート側で実行しながら、ローカルPCのVSCodeからブレークポイントや変数、ステップ実行などを操作できます。

対象言語によっては、デバッガー用のVSCode拡張機能などが必要です。

リモート開発でGitを利用する場合の注意点

Remote – SSHで開発している場合、Gitコマンドも基本的にはリモートサーバー側で実行されます。

たとえば次のコマンドを実行すると、リモート側のGit環境が使用されます。

git status
git add .
git commit -m "Update feature"
git push

そのため、ローカルPCではGitHubへpushできても、リモート環境では認証エラーが発生する場合があります。

Git認証方法を確認する

リモート環境からGitHubなどへ接続する場合は、認証方法を確認します。

主な方法としては、次のようなものがあります。

リモート側にSSH鍵を設定する
SSH Agent Forwardingを利用する
HTTPS認証を利用する
Git Credential Managerなどを利用する

必ずしもリモートサーバーへ秘密鍵を保存する必要があるわけではありません。

セキュリティポリシーや運用方法に合わせて認証方式を選択します。

VS Code Serverのインストールで注意するポイント

Remote – SSHなどでは、初回接続時にリモート側へVSCodeと連携するためのサーバーコンポーネントがセットアップされます。

通常は必要なファイルをリモート側から取得します。

ただし、リモートホストから直接ダウンロードできない環境では、設定や状況によってローカル側で必要なファイルを取得し、SSH経由でリモート側へ転送する仕組みも利用されます。

そのため、リモートサーバーからインターネットへ直接接続できないからといって、必ずRemote – SSHが利用できないとは限りません。

ただし、プロキシやファイアウォールの設定によっては接続や拡張機能の取得に問題が発生することがあります。

Remote – SSHで接続できないときの確認ポイント

Remote – SSHで問題が発生した場合は、いくつかのポイントを順番に確認します。

通常のSSHで接続できるか確認する

まず次のコマンドを実行します。

ssh user@hostname

通常のSSHで接続できない場合は、Remote – SSHでも接続できません。

SSHポートを確認する

SSHでは通常22番ポートが使用されます。

別のポートを利用している場合は、次のように指定します。

ssh -p 2222 user@example.com

SSH設定ファイルでは、次のように指定できます。

Host development-server
    HostName example.com
    User user
    Port 2222

ファイアウォールを確認する

クラウドVMやサーバーでは、ファイアウォールによってSSH通信が遮断されている場合があります。

たとえば、次のような設定を確認します。

AWS Security Group
Azure Network Security Group
Google Cloud Firewall
ufw
firewalld

Remote – SSHのログを確認する

VSCodeの「Output」を開き、「Remote – SSH」の出力を確認すると、接続エラーの原因を調査しやすくなります。

ホスト名の解決、認証、VS Code Serverのセットアップなど、どの段階で問題が発生しているか確認できます。

Remote – SSHを使う場合の注意点

Remote – SSHには、いくつかの制限があります。

PuTTYはRemote – SSHのSSHクライアントとして利用できない

WindowsではOpenSSH互換のSSHクライアントを利用する必要があります。

PuTTYはRemote – SSHのSSHクライアントとしてサポートされていません。

Windowsでは標準のOpenSSHクライアントを利用すると分かりやすいでしょう。

Alpine Linuxなどは接続先として注意が必要

Remote – SSHのリモートホストでは、glibcを利用するLinux環境が基本です。

Alpine Linuxのような非glibc環境はRemote – SSHのホストとしてサポート上の制限があります。

一方、Dev ContainersではAlpine Linuxベースのコンテナを利用できる場合があります。

Remote – SSHの接続先とDev Containerのベースイメージは分けて考えることが重要です。

VSCodeのリモート開発はどれを選べばよいのか

どの方法を選ぶべきかは、開発環境によって異なります。

LinuxサーバーやクラウドVMで開発したい場合

Remote – SSHが適しています。

AWS EC2、Azure VM、Google Cloud VM、VPS、社内サーバーなどで利用できます。

Windows上でLinux環境を使いたい場合

WSLが適しています。

Windowsを利用しながらLinux向けの開発環境を構築したい場合に便利です。

Dockerで開発環境を統一したい場合

Dev Containersが適しています。

チーム全員で同じランタイムやツールを使用したい場合に向いています。

SSHを使わず別のPCへ接続したい場合

Remote – Tunnelsが選択肢になります。

ただし、組織のセキュリティポリシーやネットワーク設定を確認する必要があります。

自前の開発サーバーを管理したくない場合

GitHub Codespacesのようなクラウド開発環境も選択肢になります。

VSCodeのリモート開発を始める基本的な流れ

Linuxサーバーへ接続してリモート開発を始める場合は、Remote – SSHから試すと仕組みを理解しやすいでしょう。

基本的な流れは次のとおりです。

SSHサーバーを用意する
↓
通常のsshコマンドで接続を確認する
↓
Remote - SSHをインストールする
↓
Remote-SSH: Connect to Host...を実行する
↓
リモート側のフォルダを開く
↓
必要なVSCode拡張機能を利用する
↓
統合ターミナルからプログラムを実行する
↓
必要に応じてポートフォワーディングを設定する
↓
VSCodeからデバッグする

Remote – SSHの基本を理解すれば、その後はRemote – SSHとDev Containersを組み合わせるなど、より高度な開発環境へ発展させることもできます。

まとめ

VSCodeのリモート開発を利用すると、ローカルPCのVSCodeから、サーバー、WSL、Dockerコンテナ、別のPCなどを開発環境として利用できます。

代表的な方法には、Remote – SSH、WSL、Dev Containers、Remote – Tunnelsがあります。

Linuxサーバー上で開発する場合はRemote – SSH、Windows上でLinux開発を行う場合はWSL、Dockerで環境を統一したい場合はDev Containersが適しています。

また、Remote – SSHとDev Containersを組み合わせれば、リモートサーバー上のDockerコンテナを開発環境として利用することもできます。

VSCodeのリモート開発では、ソースコードをローカルPCへコピーせず、リモート側に置いたまま編集、ターミナル操作、デバッグなどを行える点が大きなメリットです。

サーバーサイド開発、クラウド開発、Docker開発、AI・機械学習など、ローカルPCとは異なる環境を必要とする開発では特に役立つ機能です。

以上、VSCodeでリモート開発する方法についてでした。

最後までお読みいただき、ありがとうございました。