VSCode リモート開発完全ガイド - SSH/WSL/Tunnelで開発環境を構築

VSCode リモート開発とは

VSCodeのリモート開発機能は、ローカルマシンのVSCodeからリモートサーバー、WSL環境、またはトンネル経由で接続したマシン上で直接開発できる機能です。ソースコードをローカルに置く必要がなく、リモート環境のリソースとツールをフル活用できます。

VSCodeは接続先に「VS Code Server」と呼ばれる軽量なサーバーコンポーネントを自動インストールし、ローカルのUIとリモートの実行環境をシームレスに連携させます。IntelliSense、コード補完、デバッグなどの機能はすべてリモート側で実行されるため、ローカル環境と同等の開発体験を得られます。

本記事では、VSCodeのリモート開発機能であるRemote - SSH、Remote - WSL、Remote Tunnelsの3つの方式について、導入から実践的な活用方法まで詳しく解説します。

3つのリモート開発方式の比較

VSCodeのリモート開発には、用途に応じた3つの方式があります。それぞれの特徴を把握して最適な方式を選択してください。

方式選択のフローチャート

flowchart TD
    A[リモート開発を始めたい] --> B{接続先の環境は?}
    B -->|クラウドVM/物理サーバー| C{SSH接続可能?}
    B -->|同一マシンのWSL| D[Remote - WSL]
    B -->|ファイアウォール内のマシン| E{SSH設定が困難?}
    C -->|はい| F[Remote - SSH]
    C -->|いいえ| G[Remote Tunnels]
    E -->|はい| G
    E -->|いいえ| F

Remote - SSH：SSHでリモートサーバーに接続

Remote - SSHは、SSH経由でリモートマシンに接続し、そのマシン上でVSCodeの開発環境を構築する方式です。クラウドVMや社内サーバーへの接続に最適です。

システム要件

Remote - SSHを使用するには、ローカルマシンとリモートホストの両方で要件を満たす必要があります。

ローカルマシン（クライアント側）

リモートホスト（サーバー側）

リモートホストには最低1GB RAM（推奨2GB以上、2コアCPU）が必要です。

インストール手順

Remote - SSHのセットアップは以下の手順で行います。

1. SSHクライアントをインストールします（Windows 10以降は標準搭載）
2. VSCodeをインストールします
3. Remote - SSH拡張機能をインストールします

コマンドパレット（Ctrl+Shift+P）から以下のコマンドでもインストールできます。

1

code --install-extension ms-vscode-remote.remote-ssh

Remote Development拡張機能パックをインストールすると、SSH、WSL、Dev Containersの3つの拡張機能をまとめて導入できます。

1

code --install-extension ms-vscode-remote.vscode-remote-extensionpack

SSHホストへの接続

基本的な接続方法

1. ターミナルからSSH接続できることを確認します

1

ssh user@hostname

2. VSCodeでコマンドパレット（F1またはCtrl+Shift+P）を開きます

3. Remote-SSH: Connect to Host...を選択します

4. user@hostname形式でホスト情報を入力します

5. リモートOSの種類を選択します（Linux、Windows、macOS）

6. 接続が完了すると、ステータスバーの左下にリモート接続アイコンが表示されます

SSH設定ファイルでホストを管理

頻繁に接続するホストは、SSH設定ファイルに登録しておくと便利です。

コマンドパレットからRemote-SSH: Add New SSH Host...を選択し、接続情報を入力します。以下のような形式で~/.ssh/configファイルに設定が保存されます。

Host myserver
    HostName 192.168.1.100
    User developer
    Port 22
    IdentityFile ~/.ssh/id_ed25519

Host aws-dev
    HostName ec2-xx-xx-xx-xx.compute.amazonaws.com
    User ec2-user
    IdentityFile ~/.ssh/aws-key.pem

Host jumphost-target
    HostName 10.0.0.50
    User admin
    ProxyJump jumphost

SSH鍵認証の設定

パスワード認証よりもSSH鍵認証を推奨します。以下の手順で設定します。

1. ローカルマシンで鍵ペアを生成します

1

ssh-keygen -t ed25519 -C "your_email@example.com"

2. 公開鍵をリモートホストにコピーします

1
2
3
4
5

# Linux/macOSの場合
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@hostname

# Windowsの場合（PowerShell）
type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh user@hostname "cat >> ~/.ssh/authorized_keys"

3. SSH Agentを起動し、秘密鍵を登録します

1
2
3
4
5
6
7
8

# Linux/macOS
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Windows（PowerShell、管理者権限）
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519

ポートフォワーディング

リモートマシンで実行中のWebアプリケーションにローカルからアクセスするには、ポートフォワーディングを使用します。

一時的なポート転送

1. コマンドパレットからForward a Portを選択します
2. 転送したいポート番号を入力します
3. ローカルのlocalhost:ポート番号でリモートのサービスにアクセスできます

SSH設定ファイルでの永続的な設定

Host myserver
    HostName 192.168.1.100
    User developer
    LocalForward 127.0.0.1:3000 127.0.0.1:3000
    LocalForward 127.0.0.1:5432 127.0.0.1:5432

Remote - SSHの設定オプション

VSCodeの設定（settings.json）で、Remote - SSHの動作をカスタマイズできます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  // 接続先のOSを明示的に指定
  "remote.SSH.remotePlatform": {
    "myserver": "linux",
    "winserver": "windows"
  },
  // 常にインストールする拡張機能
  "remote.SSH.defaultExtensions": [
    "eamodio.gitlens",
    "esbenp.prettier-vscode"
  ],
  // 転送したポートを記憶
  "remote.restoreForwardedPorts": true,
  // マルチユーザーサーバーでのセキュリティ向上
  "remote.SSH.remoteServerListenOnSocket": true,
  // VS Code Serverのダウンロード方式
  "remote.SSH.localServerDownload": "auto"
}

Remote - WSL：Windows上でLinux開発

Remote - WSLは、Windows Subsystem for Linux（WSL）をフル機能の開発環境として活用するための拡張機能です。Windows上でLinuxネイティブのツールチェーンを使用した開発が可能になります。

システム要件

WSL 2はWSL 1と比較して、ファイルシステムのパフォーマンスが向上し、完全なLinuxカーネルを使用できます。

インストール手順

1. WSLと任意のLinuxディストリビューションをインストールします

1
2
3
4
5

# PowerShell（管理者権限）
wsl --install

# 特定のディストリビューションをインストール
wsl --install -d Ubuntu-24.04

2. VSCodeをWindowsにインストールします（WSL内ではなくWindows側にインストール）

3. WSL拡張機能をインストールします

1

code --install-extension ms-vscode-remote.remote-wsl

WSL環境への接続

WSLターミナルからの起動

最も簡単な方法は、WSLターミナルからcodeコマンドを実行することです。

1
2
3

# WSLターミナルで実行
cd /home/user/projects/myapp
code .

初回実行時はVS Code Serverのダウンロードとセットアップが行われます。

VSCodeからの接続

1. VSCodeを起動します
2. コマンドパレットでWSL: Connect to WSLを選択します
3. 複数のディストリビューションがある場合はWSL: Connect to WSL using Distro...で選択します

コマンドラインオプション

Windowsのコマンドプロンプトから直接WSL環境を開くこともできます。

1
2
3
4
5

# 特定のディストリビューションでフォルダを開く
code --remote wsl+Ubuntu /home/user/projects

# URIスキームを使用
code --folder-uri vscode-remote://wsl+Ubuntu/home/user/projects

WSLでのGit設定

WSLとWindowsの両方でGitを使用する場合、改行コードの設定に注意が必要です。

1
2
3
4
5

# WSL側での設定
git config --global core.autocrlf input

# Windows側での設定（必要に応じて）
git config --global core.autocrlf true

WindowsのGit認証情報をWSLで共有するには、以下の設定を行います。

1
2

# WSL側で実行
git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

WSL固有の設定

WSL接続時のみ適用される設定は、リモート設定として保存できます。

コマンドパレットでPreferences: Open Remote Settingsを選択し、WSL用の設定を追加します。

1
2
3
4
5

{
  "terminal.integrated.defaultProfile.linux": "bash",
  "editor.formatOnSave": true,
  "files.eol": "\n"
}

WSL 2でDev Containersを使用

WSL 2環境では、Dev Containersと組み合わせてコンテナ内で開発することも可能です。

1. Docker DesktopでWSL 2バックエンドを有効にします
2. Settings → Resources → WSL Integrationで対象のディストリビューションを有効にします
3. WSL環境でフォルダを開きます
4. コマンドパレットからDev Containers: Reopen in Containerを選択します

Remote Tunnels：どこからでも安全に接続

Remote Tunnelsは、SSHの設定なしにリモートマシンに安全にアクセスできる機能です。GitHubアカウントによる認証を使用し、Microsoft dev tunnelsサービスを経由して接続します。

Remote Tunnelsの特徴

• SSHサーバーの設定が不要
• ファイアウォールやNATを越えた接続が可能
• GitHubまたはMicrosoftアカウントで認証
• vscode.devからブラウザでもアクセス可能

セキュリティ

Remote Tunnelsは以下のセキュリティ機能を備えています。

• 接続の両端で同一のGitHub/Microsoftアカウントによる認証が必要
• トンネル上でSSH接続を確立し、AES 256（CTRモード）で暗号化
• ファイアウォール変更やネットワークリスナーの設定は不要

トンネルの作成方法

Remote Tunnelsを使用するには、リモートマシンでトンネルを作成する必要があります。2つの方法があります。

方法1：code CLIを使用

リモートマシンでcode CLIを使用してトンネルを作成します。

1
2
3
4
5
6
7
8

# トンネルを作成
code tunnel

# サービスとして登録（永続化）
code tunnel service install

# ライセンス同意をスキップ
code tunnel --accept-server-license-terms

VSCodeがインストールされていない環境では、スタンドアロンのCLIをダウンロードして使用できます。

1
2
3
4

# Linux x64の場合
curl -Lk 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' --output vscode_cli.tar.gz
tar -xf vscode_cli.tar.gz
./code tunnel

方法2：VSCode UIから有効化

1. リモートマシンでVSCodeを開きます
2. アカウントメニューからTurn on Remote Tunnel Accessを選択します
3. GitHubアカウントでログインします
4. トンネルが有効化されると、vscode.devのURLが表示されます

クライアントからの接続

VS Code Desktopから接続

1. Remote - Tunnels拡張機能をインストールします

1

code --install-extension ms-vscode.remote-server

2. コマンドパレットでRemote Tunnels: Connect to Tunnelを選択します
3. 接続可能なマシンの一覧から選択します

ブラウザ（vscode.dev）から接続

1. トンネル作成時に表示されたURLにアクセスします（例：https://vscode.dev/tunnel/<machine_name>）
2. GitHubアカウントで認証します
3. ブラウザ上でVSCodeが起動し、リモートマシンに接続されます

トンネルの管理

1
2
3
4
5
6
7
8

# 登録済みのトンネルを解除
code tunnel unregister

# サービスとして登録したトンネルを削除
code tunnel service uninstall

# スリープを防止して実行
code tunnel --no-sleep

Remote Explorerビューでも、登録済みのマシンの確認や削除が可能です。

使用制限

Remote Tunnelsには以下の制限があります。

• アカウントあたり最大10個のトンネルを登録可能
• 同時接続は1ユーザー/1クライアントのみ
• 帯域幅に制限あり（通常の開発作業では問題なし）

拡張機能の管理

リモート開発環境では、拡張機能はローカルとリモートのどちらかで実行されます。

拡張機能の実行場所

拡張機能をインストールすると、自動的に適切な場所にインストールされます。Extensions viewでは、Local - InstalledとSSH: hostname（またはWSL、Tunnels）のカテゴリに分けて表示されます。

常にインストールする拡張機能

特定の拡張機能を常にリモート環境にインストールするには、設定ファイルで指定します。

1
2
3
4
5
6
7

{
  "remote.SSH.defaultExtensions": [
    "eamodio.gitlens",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint"
  ]
}

拡張機能の実行場所を強制

拡張機能の実行場所を明示的に指定することもできます。

1
2
3
4
5
6

{
  "remote.extensionKind": {
    "ms-azuretools.vscode-containers": ["ui"],
    "ms-vscode-remote.remote-ssh-edit": ["workspace"]
  }
}

uiを指定するとローカルで、workspaceを指定するとリモートで実行されます。

トラブルシューティング

Remote - SSHの問題

接続がタイムアウトする

1. ターミナルから直接SSH接続できるか確認します

1

ssh -v user@hostname

2. SSH設定ファイルの構文エラーをチェックします

1

ssh -T -F ~/.ssh/config user@hostname

3. リモートホストのリソース（RAM、ディスク容量）を確認します

権限エラー（bad permissions）

SSH鍵ファイルのパーミッションを修正します。

1
2
3
4
5

# Linux/macOS
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 644 ~/.ssh/config

1
2

# Windows（PowerShell）
icacls $env:USERPROFILE\.ssh\id_ed25519 /inheritance:r /grant:r "$($env:USERNAME):(R)"

VS Code Serverのインストールに失敗

リモートホストで以下の要件を確認します。

• bash、tar、curlまたはwgetがインストールされている
• インターネット接続がある（update.code.visualstudio.comへのアクセス）
• 十分なディスク容量がある

Remote - WSLの問題

codeコマンドが見つからない

VSCodeのインストール時に「Add to PATH」オプションを有効にしていない場合、手動でパスを設定します。

1
2

# WSLの~/.bashrcに追加
export PATH="$PATH:/mnt/c/Users/<username>/AppData/Local/Programs/Microsoft VS Code/bin"

ファイル監視の問題（WSL 1）

WSL 1でファイル名の変更時にエラーが発生する場合、ポーリングベースの監視に切り替えます。

1
2
3
4

{
  "remote.WSL.fileWatcher.polling": true,
  "remote.WSL.fileWatcher.pollingInterval": 5000
}

この問題はWSL 2では発生しません。WSL 2への移行を検討してください。

1
2

# ディストリビューションをWSL 2に変換
wsl --set-version Ubuntu 2

Remote Tunnelsの問題

トンネルに接続できない

1. リモートマシンでトンネルが実行中か確認します
2. 同一のGitHubアカウントでログインしているか確認します
3. ネットワークで*.tunnels.api.visualstudio.comへのアクセスが許可されているか確認します

トンネルが切断される

サービスとして登録することで、トンネルを永続化できます。

1

code tunnel service install

共通の問題

拡張機能が動作しない

1. 拡張機能がリモート開発に対応しているか確認します
2. 必要なランタイム（Node.js、Python等）がリモート環境にインストールされているか確認します
3. 拡張機能のログを確認します（Output → 拡張機能名）

パフォーマンスが遅い

1. ネットワーク帯域幅を確認します
2. リモートホストのリソース使用状況を確認します
3. 大きなワークスペースの場合、files.watcherExcludeで監視対象を制限します

1
2
3
4
5
6
7

{
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/.git/objects/**": true,
    "**/dist/**": true
  }
}

リモート開発のベストプラクティス

セキュリティ

• SSH鍵認証を使用し、パスワード認証は避ける
• パスフレーズ付きのSSH鍵を使用する場合はSSH Agentを活用
• 複数ユーザーが接続するサーバーではremote.SSH.remoteServerListenOnSocketを有効化
• Remote Tunnelsでは組織のポリシーに従ってアクセス制御を設定

パフォーマンス

• WSLを使用する場合はWSL 2を選択
• 大規模プロジェクトではfiles.watcherExcludeを適切に設定
• Windowsファイルシステム（/mnt/c/）よりもWSLファイルシステム（/home/）を使用

開発ワークフロー

• プロジェクトごとにリモート設定を.vscode/settings.jsonで管理
• 必要な拡張機能をremote.SSH.defaultExtensionsで統一
• チーム共有する設定はリポジトリにコミット

まとめ

VSCodeのリモート開発機能を使用することで、ローカル環境と同等の開発体験をリモート環境で実現できます。

• Remote - SSH：クラウドVMや物理サーバーへのSSH接続に最適
• Remote - WSL：Windows上でのLinuxネイティブ開発に最適
• Remote Tunnels：ファイアウォール越えやSSH設定が困難な環境に最適

それぞれの方式の特性を理解し、プロジェクトや環境に合わせて使い分けることで、効率的なリモート開発環境を構築できます。

参考リンク

• Remote Development using SSH - Visual Studio Code
• Developing in WSL - Visual Studio Code
• Developing with Remote Tunnels - Visual Studio Code
• Remote Development extension pack - Visual Studio Marketplace
• WSL 2 のインストール - Microsoft Learn
• SSH Tips and Tricks - Visual Studio Code