VSCode ワークスペースで複数プロジェクトを効率管理する

Visual Studio Code（VSCode）のワークスペース機能を活用していますか。多くの開発者が単一フォルダを開いて作業していますが、マルチルートワークスペースを使いこなすことで、複数プロジェクトの同時管理や、プロジェクト固有の設定管理が劇的に効率化します。

本記事では、VSCode ワークスペースの基本概念から.code-workspaceファイルの作成、ワークスペース固有の設定、拡張機能の管理、実践的な活用テクニックまでを網羅的に解説します。フロントエンドとバックエンドを同時に扱うフルスタック開発や、ライブラリとサンプルプロジェクトを並行管理するOSS開発など、複数プロジェクトを扱う開発者には必須の知識です。

この記事で得られること

  • VSCode ワークスペースの種類と使い分け
  • マルチルートワークスペース（.code-workspace）の作成と管理方法
  • ワークスペース固有の設定、タスク、デバッグ構成の活用
  • 拡張機能のワークスペース単位での管理テクニック
  • 複数プロジェクト管理を効率化する実践的なワークフロー

前提条件と実行環境

VSCode ワークスペースを活用するための前提条件を確認します。

項目 要件
VSCode バージョン1.80以上（マルチルートワークスペースは1.18以降で対応）
OS Windows 10/11、macOS 10.15以上、Linux
推奨メモリ 8GB以上（複数プロジェクト同時管理時）

VSCode ワークスペースとは

VSCode ワークスペースとは、1つ以上のフォルダをVSCodeウィンドウで開いた状態のことを指します。ワークスペースを使用することで、以下のことが可能になります。

  • 特定のフォルダにのみ適用される設定の構成
  • ワークスペース固有のタスクやデバッグ構成の保存
  • UIの状態（開いているファイルなど）の保持
  • 特定のワークスペースでのみ拡張機能を有効化または無効化

ワークスペースの種類

VSCode ワークスペースには大きく分けて3つの種類があります。

flowchart TD
    A[VSCode ワークスペースの種類] --> B[シングルフォルダ<br/>ワークスペース]
    A --> C[マルチルート<br/>ワークスペース]
    A --> D[ワークスペースなし<br/>単一ファイル編集]
    
    B --> B1[最も一般的]
    B --> B2[1つのフォルダを開く]
    B --> B3[.vscode/に設定保存]
    
    C --> C1[複数フォルダを管理]
    C --> C2[.code-workspaceファイル]
    C --> C3[プロジェクト横断設定]
    
    D --> D1[一時的な編集]
    D --> D2[機能制限あり]
    
    style A fill:#e3f2fd
    style C fill:#e8f5e9
種類 説明 設定ファイルの場所
シングルフォルダワークスペース 1つのフォルダを開いた状態 .vscode/settings.json
マルチルートワークスペース 複数フォルダを1つのウィンドウで管理 *.code-workspaceファイル
ワークスペースなし ファイル単体を開いた状態 ユーザー設定のみ適用

シングルフォルダワークスペースの基本

最も一般的なワークスペース形態は、1つのフォルダを開くシングルフォルダワークスペースです。フォルダを開くと自動的にワークスペースとして認識されます。

シングルフォルダワークスペースの開き方

1
2
3
4
5

# コマンドラインから開く
code /path/to/project

# カレントディレクトリを開く
code .

メニューからは「ファイル」→「フォルダーを開く」で任意のフォルダをワークスペースとして開けます。

.vscodeフォルダの構造

シングルフォルダワークスペースでは、プロジェクトルートの.vscodeフォルダに設定ファイルを配置します。

project-root/
├── .vscode/
│   ├── settings.json      # ワークスペース設定
│   ├── tasks.json         # タスク定義
│   ├── launch.json        # デバッグ構成
│   ├── extensions.json    # 推奨拡張機能
│   └── *.code-snippets    # プロジェクト固有スニペット
├── src/
└── package.json

マルチルートワークスペースの作成と管理

マルチルートワークスペースは、複数のプロジェクトフォルダを1つのVSCodeウィンドウで管理する高度な機能です。

マルチルートワークスペースの作成方法

マルチルートワークスペースを作成するには、以下のいずれかの方法を使用します。

方法1: メニューからフォルダを追加

  1. 最初のフォルダを開く
  2. 「ファイル」→「フォルダーをワークスペースに追加」を選択
  3. 追加したいフォルダを選択
  4. 「ファイル」→「名前を付けてワークスペースを保存」で.code-workspaceファイルを保存

方法2: ドラッグ&ドロップ

エクスプローラーから複数のフォルダをVSCodeのファイルエクスプローラーにドラッグ&ドロップすることでも追加できます。

方法3: コマンドラインから

1
2

# 既存のVSCodeインスタンスにフォルダを追加
code --add /path/to/folder1 /path/to/folder2

.code-workspaceファイルの構造

マルチルートワークスペースは.code-workspaceファイルで管理されます。このファイルはJSON形式で、以下の構造を持ちます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

{
  "folders": [
    {
      "name": "フロントエンド",
      "path": "./frontend"
    },
    {
      "name": "バックエンド",
      "path": "./backend"
    },
    {
      "name": "共通ライブラリ",
      "path": "../shared-lib"
    }
  ],
  "settings": {
    // ワークスペース全体に適用される設定
  },
  "extensions": {
    "recommendations": []
  },
  "launch": {
    "configurations": [],
    "compounds": []
  },
  "tasks": {
    "version": "2.0.0",
    "tasks": []
  }
}
プロパティ 説明
folders ワークスペースに含めるフォルダの配列
folders[].name エクスプローラーに表示される名前（任意）
folders[].path フォルダへのパス（相対パスまたは絶対パス）
settings ワークスペース全体に適用される設定
extensions 推奨拡張機能と不要な拡張機能
launch デバッグ構成
tasks タスク定義

ワークスペースファイルの開き方

作成した.code-workspaceファイルは以下の方法で開けます。

  1. .code-workspaceファイルをダブルクリック
  2. 「ファイル」→「ワークスペースを開く」から選択
  3. 「ファイル」→「最近使用した項目を開く」（Ctrl+R）から選択
  4. コマンドラインからcode myproject.code-workspaceを実行

ワークスペース設定の階層と優先順位

VSCodeの設定には複数のスコープがあり、下位のスコープが上位を上書きします。

flowchart TD
    A[デフォルト設定] --> B[ユーザー設定]
    B --> C[リモート設定]
    C --> D[ワークスペース設定]
    D --> E[フォルダ設定]
    E --> F[言語固有設定]
    
    style A fill:#f3e5f5
    style B fill:#e8eaf6
    style D fill:#e3f2fd
    style E fill:#e8f5e9
    style F fill:#fff3e0
スコープ 適用範囲 設定ファイルの場所
ユーザー設定 全プロジェクト共通 %APPDATA%\Code\User\settings.json（Windows）
ワークスペース設定 ワークスペース全体 .code-workspaceファイル内のsettings
フォルダ設定 特定のフォルダのみ 各フォルダの.vscode/settings.json

マルチルートワークスペースでの設定の使い分け

マルチルートワークスペースでは、設定を適切なスコープに配置することが重要です。

ワークスペース設定に適した項目

  • エディタのUI設定（ズームレベル、サイドバー位置など）
  • 全フォルダ共通のフォーマッタ設定
  • 共通の除外パターン
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "folders": [...],
  "settings": {
    "window.zoomLevel": 0,
    "files.autoSave": "afterDelay",
    "editor.formatOnSave": true,
    "search.exclude": {
      "**/node_modules": true,
      "**/dist": true
    }
  }
}

フォルダ設定に適した項目

  • 言語固有のフォーマッタ設定
  • プロジェクト固有のLint設定
  • 環境変数パス
1
2
3
4
5
6

// frontend/.vscode/settings.json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "eslint.workingDirectories": [{ "mode": "auto" }],
  "prettier.configPath": ".prettierrc"
}

フォルダ設定の制限事項

マルチルートワークスペースでは、一部の設定がフォルダレベルでサポートされません。これはエディタ全体に影響する設定であり、複数のフォルダで異なる値を持つことができないためです。

サポートされないフォルダ設定の例:

  • window.zoomLevel
  • editor.fontSize
  • workbench.colorTheme

これらの設定をフォルダの.vscode/settings.jsonに記述しても無視され、設定エディタではグレーアウト表示されます。

ワークスペース固有のタスク設定

マルチルートワークスペースでは、各フォルダのtasks.jsonに加えて、.code-workspaceファイル内にワークスペース全体のタスクを定義できます。

フォルダ別タスクの自動検出

VSCodeは各フォルダからtasks.jsonを自動検出し、タスク名にフォルダ名のサフィックスを付けて表示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// frontend/.vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "npm",
      "script": "build",
      "group": "build"
    }
  ]
}

タスクを実行する際は「build (frontend)」のように表示されます。

ワークスペースタスクの定義

ワークスペース全体に適用されるタスクは.code-workspaceファイルに定義します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "folders": [...],
  "tasks": {
    "version": "2.0.0",
    "tasks": [
      {
        "label": "全体ビルド",
        "dependsOn": ["build (frontend)", "build (backend)"],
        "dependsOrder": "parallel",
        "group": {
          "kind": "build",
          "isDefault": true
        }
      },
      {
        "label": "開発サーバー起動",
        "type": "shell",
        "command": "echo Starting all servers...",
        "dependsOn": ["dev (frontend)", "dev (backend)"],
        "dependsOrder": "parallel",
        "problemMatcher": []
      }
    ]
  }
}

ワークスペース固有のデバッグ構成

マルチルートワークスペースでは、複数プロジェクトのデバッグを統合的に管理できます。

フォルダ別デバッグ構成

各フォルダの.vscode/launch.jsonに定義されたデバッグ構成は、フォルダ名付きで表示されます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// backend/.vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "サーバー起動",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/index.js"
    }
  ]
}

複合デバッグ構成（Compound）

複数のデバッグ構成を同時に起動する複合構成を定義できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "folders": [...],
  "launch": {
    "version": "0.2.0",
    "configurations": [
      {
        "name": "フルスタックデバッグ",
        "type": "node",
        "request": "launch",
        "program": "${workspaceFolder:バックエンド}/src/index.js"
      }
    ],
    "compounds": [
      {
        "name": "フロント&バックエンド同時デバッグ",
        "configurations": [
          "サーバー起動 (backend)",
          {
            "folder": "フロントエンド",
            "name": "Chrome起動"
          }
        ],
        "stopAll": true
      }
    ]
  }
}

スコープ付き変数の使用

マルチルートワークスペースでは、${workspaceFolder:フォルダ名}構文で特定のフォルダを参照できます。

変数 説明
${workspaceFolder} 現在のフォルダ（曖昧な場合はエラー）
${workspaceFolder:FolderName} 指定した名前のフォルダのパス
${fileWorkspaceFolder} 現在開いているファイルが属するフォルダ

拡張機能のワークスペース管理

VSCode ワークスペースでは、拡張機能をワークスペース単位で管理できます。

推奨拡張機能の設定

.code-workspaceファイルに推奨拡張機能を記述することで、チームメンバーに必要な拡張機能を案内できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "folders": [...],
  "extensions": {
    "recommendations": [
      "dbaeumer.vscode-eslint",
      "esbenp.prettier-vscode",
      "ms-vscode.vscode-typescript-next",
      "bradlc.vscode-tailwindcss"
    ],
    "unwantedRecommendations": [
      "hookyqr.beautify"
    ]
  }
}
プロパティ 説明
recommendations 推奨する拡張機能IDの配列
unwantedRecommendations 推奨しない拡張機能IDの配列

拡張機能のワークスペース単位での有効化/無効化

パフォーマンス最適化のため、重い拡張機能はワークスペース単位で有効化することを推奨します。

  1. 拡張機能パネル（Ctrl+Shift+X）を開く
  2. 対象の拡張機能を右クリック
  3. 「有効にする（ワークスペース）」または「無効にする（ワークスペース）」を選択

これにより、特定のワークスペースでのみ拡張機能が動作します。

プロファイル機能との連携

VSCode 1.75以降のプロファイル機能を使用すると、ワークスペースの種類に応じて拡張機能セットを切り替えられます。

プロファイル例 含める拡張機能
フロントエンド開発 ESLint、Prettier、Tailwind CSS IntelliSense、Auto Rename Tag
バックエンド開発 REST Client、Thunder Client、Database Client
Python開発 Python、Pylance、Jupyter
ドキュメント作成 Markdown All in One、markdownlint、Draw.io Integration

実践的なワークスペース構成例

フルスタック開発プロジェクト

フロントエンドとバックエンドを同時に管理するワークスペース構成例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

{
  "folders": [
    {
      "name": "React Frontend",
      "path": "./packages/frontend"
    },
    {
      "name": "Node.js API",
      "path": "./packages/api"
    },
    {
      "name": "Shared Types",
      "path": "./packages/shared"
    }
  ],
  "settings": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "typescript.tsdk": "packages/frontend/node_modules/typescript/lib",
    "search.exclude": {
      "**/node_modules": true,
      "**/dist": true,
      "**/build": true
    },
    "files.watcherExclude": {
      "**/node_modules/**": true
    }
  },
  "extensions": {
    "recommendations": [
      "dbaeumer.vscode-eslint",
      "esbenp.prettier-vscode",
      "ms-vscode.vscode-typescript-next",
      "prisma.prisma"
    ]
  },
  "launch": {
    "compounds": [
      {
        "name": "Full Stack Debug",
        "configurations": [
          "Launch API (Node.js API)",
          "Launch Chrome (React Frontend)"
        ]
      }
    ]
  },
  "tasks": {
    "version": "2.0.0",
    "tasks": [
      {
        "label": "Install All Dependencies",
        "type": "shell",
        "command": "npm install",
        "options": {
          "cwd": "${workspaceFolder:React Frontend}"
        },
        "dependsOn": ["Install API Dependencies"],
        "problemMatcher": []
      },
      {
        "label": "Install API Dependencies",
        "type": "shell",
        "command": "npm install",
        "options": {
          "cwd": "${workspaceFolder:Node.js API}"
        },
        "problemMatcher": []
      }
    ]
  }
}

モノレポ構成での活用

モノレポ（Monorepo）構成では、複数のパッケージを1つのリポジトリで管理します。ワークスペースを活用することで、必要なパッケージのみを表示できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "folders": [
    {
      "name": "Root",
      "path": "."
    },
    {
      "name": "Core Library",
      "path": "./packages/core"
    },
    {
      "name": "CLI Tool",
      "path": "./packages/cli"
    },
    {
      "name": "Documentation",
      "path": "./docs"
    }
  ],
  "settings": {
    "npm.packageManager": "pnpm",
    "eslint.workingDirectories": [
      { "mode": "auto" }
    ],
    "typescript.preferences.importModuleSpecifier": "non-relative"
  }
}

マイクロサービス開発での活用

複数のマイクロサービスを同時に開発する場合の構成例です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "folders": [
    {
      "name": "API Gateway",
      "path": "../gateway-service"
    },
    {
      "name": "User Service",
      "path": "../user-service"
    },
    {
      "name": "Order Service",
      "path": "../order-service"
    },
    {
      "name": "Shared Protos",
      "path": "../proto-definitions"
    }
  ],
  "settings": {
    "docker.enabled": true,
    "rest-client.environmentVariables": {
      "local": {
        "baseUrl": "http://localhost:3000"
      }
    }
  }
}

ワークスペースの効率化テクニック

検索範囲の限定

マルチルートワークスペースでは、特定のフォルダのみを検索対象にできます。

  • 検索ボックスの「含めるファイル」に./FolderName/**と入力
  • ./FolderName/**/*.tsで特定フォルダのTypeScriptファイルのみを検索

ファイルの除外設定

ワークスペース全体で不要なファイルを除外することで、検索やファイルエクスプローラーのパフォーマンスが向上します。

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

{
  "settings": {
    "files.exclude": {
      "**/.git": true,
      "**/.DS_Store": true,
      "**/node_modules": true,
      "**/dist": true
    },
    "search.exclude": {
      "**/node_modules": true,
      "**/bower_components": true,
      "**/*.code-search": true,
      "**/package-lock.json": true
    }
  }
}

クイックオープンでのフォルダ識別

マルチルートワークスペースでは、Ctrl+Pのクイックオープンでファイル名の後ろにフォルダ名が表示されます。同名ファイルがある場合の識別に役立ちます。

タブに常にフォルダ名を表示するには以下の設定を追加します。

1
2
3
4
5

{
  "settings": {
    "workbench.editor.labelFormat": "medium"
  }
}

ワークスペースの切り替え

複数のワークスペースを素早く切り替えるには以下の方法があります。

方法 ショートカット 説明
最近使用した項目 Ctrl+R 最近開いたフォルダ/ワークスペースの一覧
ワークスペースを開く コマンドパレット 「ワークスペースを開く」を実行
新しいウィンドウ Ctrl+Shift+N 新規ウィンドウで別のワークスペースを開く

トラブルシューティング

よくある問題と解決策

問題: 拡張機能がマルチルートワークスペースで正しく動作しない

原因: 一部の古い拡張機能はマルチルートワークスペースに対応していません。

解決策:

  • 拡張機能を最新バージョンに更新
  • 対応していない場合は代替の拡張機能を検討
  • マルチルート非対応の拡張機能は最初のフォルダでのみ動作

問題: 設定が反映されない

原因: 設定のスコープが適切でない可能性があります。

解決策:

  1. コマンドパレットで「Preferences: Open Workspace Settings」を実行
  2. 設定がどのスコープで定義されているか確認
  3. フォルダ設定でサポートされない項目はワークスペース設定に移動

問題: ワークスペースファイルが見つからない

原因: 未保存の「無題のワークスペース」を使用している可能性があります。

解決策:

  • 「ファイル」→「名前を付けてワークスペースを保存」で保存
  • 保存せずに閉じると、次回起動時に復元を促すダイアログが表示される

パフォーマンス最適化

マルチルートワークスペースでパフォーマンスを維持するための設定です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "settings": {
    "files.watcherExclude": {
      "**/.git/objects/**": true,
      "**/.git/subtree-cache/**": true,
      "**/node_modules/**": true,
      "**/dist/**": true,
      "**/build/**": true
    },
    "typescript.disableAutomaticTypeAcquisition": true,
    "search.followSymlinks": false
  }
}

まとめ

本記事では、VSCode ワークスペースの活用方法について解説しました。

学んだ内容

トピック 内容
ワークスペースの種類 シングルフォルダとマルチルートの違いと使い分け
.code-workspaceファイル 複数フォルダを管理するワークスペースファイルの構造
設定の階層 ユーザー設定、ワークスペース設定、フォルダ設定の優先順位
タスクとデバッグ ワークスペース全体と個別フォルダでの設定方法
拡張機能管理 推奨拡張機能の設定とワークスペース単位の有効化
効率化テクニック 検索範囲の限定、除外設定、クイック切り替え

次のステップ

VSCode ワークスペースを最大限に活用するために、以下を試してみてください。

  1. 現在のプロジェクトで.code-workspaceファイルを作成
  2. チーム向けに推奨拡張機能を設定
  3. ワークスペースタスクで複数プロジェクトのビルドを自動化
  4. 複合デバッグ構成でフルスタックデバッグを設定

マルチルートワークスペースを活用することで、複数プロジェクトの管理効率が大幅に向上し、開発体験が改善されます。

参考リンク