VSCodeでSSH接続する方法｜リモート開発の始め方を解説

AWS（EC2）やさくらのVPS、ConoHa VPSといったクラウドサーバー、あるいは社内のLinuxサーバーを使って開発を行う際、「本番環境のファイルを書き換えるのが面倒」「ターミナルとエディタを何往復もして疲れる」と感じたことはありませんか？

これまでは、Tera TermやMacのターミナルでCUI（文字だけ）操作をしたり、FTPソフトでファイルをいちいちダウンロード・アップロードしたりするのが一般的でした。

しかし、VSCode（Visual Studio Code）の標準的な拡張機能を使えば、リモートサーバー上のファイルをローカルPCにあるファイルと全く同じ感覚で、GUI（画面操作）で直接編集・開発できるようになります。

本記事では、VSCodeを使ってリモートサーバーに安全にSSH接続し、爆速で快適な「リモート開発環境」を構築する手順を、初心者にも分かりやすく徹底解説します！

VSCodeでSSH接続すると何ができる？

まずは、VSCodeを使ったリモート開発の概要と、導入するメリットについて知っておきましょう。

SSH接続とは

SSH（Secure Shell）接続とは、ネットワークを介して離れた場所にあるサーバー（リモートサーバー）に安全にログインし、遠隔操作するための仕組みです。通信内容がすべて暗号化されるため、パスワードや機密情報が第三者に盗まれる心配がありません。

VSCodeでSSH接続するメリット

VSCodeにSSH接続の機能を組み込むと、以下のような絶大なメリットが得られます。

サーバー上のファイルを直接編集できる：
サーバー内にあるソースコードをVSCodeで開き、使い慣れたショートカットキーやコード補完をそのまま使って書き換えることができます（FTPでのアップロード作業が不要になります）。
ターミナルもVSCode内で使える：
パネル内にサーバーのLinuxターミナルがそのまま起動するため、コマンド実行とコード編集を一画面で完結させられます。
ローカルと同じ操作感で開発できる：
サーバー側で行われている処理を意識することなく、自分のPCの中にあるファイルを触っているかのような錯覚に陥るほどスムーズに動きます。

SSH接続に必要なもの

　スムーズに設定を進めるために、以下の準備物が揃っているか確認してください。

VSCode（ローカルPCにインストール済みであること）
SSH接続先（VPS、AWS EC2、オンプレミスのLinuxサーバーなど）
SSHアカウント情報（接続先のIPアドレス、ユーザー名、パスワードなど）
SSH鍵（秘密鍵）（※鍵認証を設定している場合。一般的には id_rsa などのファイル）

Remote – SSH拡張機能をインストールする

VSCodeでリモート開発を行うには、Microsoft公式が提供している拡張機能を導入します。

拡張機能を検索する

VSCodeを開き、画面左側にあるブロックのような形をした「拡張機能」アイコンをクリックします。（またはCmd + Shift + X / Ctrl + Shift + X）。
上部の検索バーにRemote – SSHと入力します。

インストールする

検索結果の一番上に表示される、Microsoft公式のRemote – SSHという拡張機能の「インストール」ボタンをクリックします。

数秒でインストールが完了すると、VSCodeの左下の隅に ><（緑色、または青色のインジケーター）のような「リモートウィンドウを開く」アイコンが表示されます。

VSCodeでSSH接続する方法

準備が整ったら、実際に接続設定を行いましょう。もっとも管理が楽な「SSH Configファイル」を利用した方法を解説します。

SSH接続先を登録する

VSCodeの左下にある >< アイコンをクリックします。
画面上部に出てくるメニューから「ホストに接続する… (Connect to Host…)」 を選択し、次に 「新規SSHホストを追加する… (Add New SSH Host…)」 を選択します。
接続コマンドを入力する欄が出てくるので、以下のように入力してEnterを押します。

ssh ユーザー名@サーバーのIPアドレス -i 秘密鍵のパス
（例：ssh root@192.168.11.10 -i ~/.ssh/my-key.pem）

※パスワード認証の場合は -i 秘密鍵のパス は不要です。

SSH Configを設定する

コマンドを入力すると、「保存先の構成ファイル（Config）を選択してください」と聞かれます。通常は一番上にあるユーザーディレクトリの設定ファイル（例：/Users/ユーザー名/.ssh/confing）を選択します。

自動生成された config ファイルの中身は、手動で以下のように書き換えて管理することも可能です。一度設定しておけば、次回からサーバー名を選択するだけで接続できます。

Host my-vps-server
    HostName 192.168.11.10
    User root
    IdentityFile ~/.ssh/my-key.pem

サーバーへ接続する

再び左下の><アイコンを押し、「ホストに接続する…」を選択します。
先ほど登録したホスト名（例：my-vps-server）がリストに表示されているので、クリックします。
新しいVSCodeのウィンドウが立ち上がります。初回接続時は「プラットフォームの選択（Linux / Windows / macOS）」や「続行しますか？（Continue）」というセキュリティの確認が出るので、接続先サーバーに合わせて選択し、進めてください（パスワード入力を求められた場合は、サーバーのパスワードを入力します）。

左下のアイコンの表示がSSH：ホスト名に変われば、接続完了です！

接続後にできること

無事に接続できたら、VSCodeのパワーをフルに活かして開発を進めましょう。

ファイルを編集する

メニューの「エクスプローラー」から「フォルダーを開く」をクリックすると、サーバー内のフォルダ階層（/var/wwwなど）がそのまま表示されます。
ファイルを選択してコードを書き換え、Cmd + S / Ctrl + Sで保存すれば、リアルタイムにサーバー上のファイルが更新されます。

ターミナルを利用する

メニューの「ターミナル」＞「新しいターミナル」を開くと、画面下部にサーバーのシェル（Bashなど）が直接立ち上がります。
そのままnpm run devやdocker-compose upなどのコマンドを実行し、アプリを起動したりログを確認したりできます。

拡張機能を利用する

拡張機能タブを開くと、サーバー側（SSH: ホスト名）にインストールする拡張機能を選べます。Gitの履歴を見やすくするGitLensや、各種言語の保管プラグインをサーバー側にも入れることで、ローカルと全く同じ快適さを維持できます。

SSH接続できないときの対処法

Remote – SSHのセットアップ時によくあるエラーと、そのチェックポイントをまとめました。

Permission deniedが表示される

原因：ユーザー名、パスワード、または秘密鍵（パス）のいずれかが間違っているか、鍵の権限が緩すぎます。
解決策：Configファイル内の User や IdentityFile の記述が正しいか再確認してください。また、MacやLinux環境の場合、秘密鍵のパーミッション（権限）が広すぎると接続を拒否されるため、ターミナルで chmod 600 ~/ .ssh/my-key.pem を実行して権限を絞ってください。

Hostが見つからない / Could not resolve hostname

原因：サーバーのIPアドレスやドメイン名が間違っているか、ローカルPCのネットワークが繋がっていません。
解決策：Configの HostName に記述したIPアドレスにタイポ（打ち間違い）がないか確認してください。

タイムアウトになる（Timeout）

原因：サーバー側のファイヤーウォール（セキュリティグループなど）で、22万ポート（SSH）からの接続が許可されていません・
解決策：クラウドVPSやAWSの管理画面を開き、自分の自宅のIPアドレスからの「SSH接続（22番ポート）」が許可（インバウンドルール設定）されているか確認してください。

Remote – SSHが接続できない（ループする）

原因：接続先サーバーの空き容量が不足しているか、VSCodegがサーバー側にセットアップする内部プロセス（VSCode Server）がクラッシュしています。
解決策：一度サーバーに通常のターミナルからログインし、ディスク容量（df -h）を確認してください。また、VSCode上で Cmd + Shift + P から「Remote-SSH: Kill VSCode Server on Host. . .」を実行して、サーバー側のプロセスを一度リセットするのも効果的です。

ローカル開発とリモート開発の違い

最後に、自分のPC（ローカル）で開発する場合と、今回のリモート開発（サーバー）の違いを整理しておきましょう。

項目	ローカル開発	リモート開発
実行環境（CPU・メモリ）	自分のPC	リモートサーバー
ファイルの保存場所	自分のPCの中	サーバーのストレージ上
主な用途	基礎学習・個人の軽い練習	実務の本番/ステージング環境、チーム開発、重い機械学習など
メリット	ネット環境がなくても動く	PCのスペックに依存せず、本番と全く同じ環境でテストできる