VS Codeのsettings.jsonで環境変数を使う方法｜${workspaceFolder}やシェル環境の扱いを解説

プログラミング・IT

「VS Codeの settings.json に環境変数を入れたいけど、どう書けばいいの？」

  • どんな書き方ができるのか分からない
  • ${PATH} のように書いたけど展開されない
  • プロジェクトごとに設定を変えたい

こんな悩みはありませんか？

VS Codeの settings.json では、VS Code独自のプレースホルダ（${workspaceFolder} など）とシェルの環境変数を活用できますが、それぞれ挙動が少し違います。

この記事では、VS Codeの設定ファイルで使える変数の種類から実用的な活用方法まで、初心者にもわかりやすく詳しく解説します。

スポンサーリンク

VS Codeの設定ファイルの基本

設定ファイルの種類と優先順位

VS Codeには複数の設定ファイルがあり、それぞれ異なる適用範囲を持ちます：

設定ファイル場所適用範囲優先順位
ユーザー設定~/.config/Code/User/settings.jsonすべてのプロジェクト低
ワークスペース設定.vscode/settings.json現在のプロジェクト中
フォルダ設定プロジェクト/.vscode/settings.json特定のフォルダ高

重要なポイント： 優先順位が高い設定が、低い設定を上書きします。プロジェクト固有の設定は .vscode/settings.json に記述するのが一般的です。

環境変数が使える設定ファイル

環境変数やプレースホルダが使用できるファイル：

  • settings.json：基本設定
  • tasks.json：タスク設定
  • launch.json：デバッグ設定
  • c_cpp_properties.json：C/C++設定
  • keybindings.json：キーバインド設定

VS Code独自の変数（プレースホルダ）

基本的なプレースホルダ一覧

VS Codeには多くの組み込み変数があります：

プレースホルダ説明例
${workspaceFolder}ワークスペースのルートフォルダ/home/user/project
${workspaceFolderBasename}ワークスペースフォルダ名project
${file}現在開いているファイルの絶対パス/home/user/project/src/main.py
${fileWorkspaceFolder}現在のファイルが属するワークスペース/home/user/project
${relativeFile}ワークスペースからの相対パスsrc/main.py
${relativeFileDirname}現在のファイルの相対ディレクトリsrc
${fileBasename}ファイル名（拡張子付き）main.py
${fileBasenameNoExtension}ファイル名（拡張子なし）main
${fileDirname}現在のファイルのディレクトリ絶対パス/home/user/project/src
${fileExtname}現在のファイルの拡張子.py

実用的な使用例

例1：Python仮想環境の自動設定

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "python.envFile": "${workspaceFolder}/.env"
}

この設定により、プロジェクトを開くたびに自動的にその .venv フォルダの Python インタープリターが使用されます。

例2：Node.js開発環境の設定

{
  "typescript.preferences.includePackageJsonAutoImports": "auto",
  "eslint.workingDirectories": ["${workspaceFolder}"],
  "npm.packageManager": "npm",
  "terminal.integrated.cwd": "${workspaceFolder}"
}

例3：C/C++開発環境の設定

{
  "C_Cpp.default.includePath": [
    "${workspaceFolder}/**",
    "${workspaceFolder}/include"
  ],
  "C_Cpp.default.compilerPath": "/usr/bin/gcc",
  "C_Cpp.default.cStandard": "c17",
  "C_Cpp.default.cppStandard": "c++17"
}

シェルの環境変数を使う方法

${env:VARNAME} 構文

VS Codeでシェルの環境変数を参照するには、${env:VARNAME} の形式を使用します。

基本的な使用方法

{
  "some.extension.path": "${env:MY_TOOL_HOME}/bin",
  "terminal.integrated.env.linux": {
    "CUSTOM_PATH": "${env:PATH}:${workspaceFolder}/scripts"
  }
}

環境変数の設定方法

Windows

# コマンドプロンプト（セッション限定）
set MY_TOOL_HOME=C:\tools

# 永続的な設定
setx MY_TOOL_HOME "C:\tools"

# PowerShell（セッション限定）
$env:MY_TOOL_HOME = "C:\tools"

# PowerShellプロファイル（永続的）
[Environment]::SetEnvironmentVariable("MY_TOOL_HOME", "C:\tools", "User")

Linux/macOS

# セッション限定
export MY_TOOL_HOME=/home/user/tools

# .bashrc または .zshrc に追加（永続的）
echo 'export MY_TOOL_HOME=/home/user/tools' >> ~/.bashrc

# システム全体（/etc/environment）
echo 'MY_TOOL_HOME=/usr/local/tools' | sudo tee -a /etc/environment

環境変数の実用例

例1：プロジェクト固有のツールパス

{
  "go.toolsGopath": "${env:GOPATH}",
  "go.gopath": "${env:GOPATH}",
  "go.goroot": "${env:GOROOT}",
  "terminal.integrated.env.linux": {
    "GOBIN": "${env:GOPATH}/bin"
  }
}

例2：データベース接続設定

{
  "sqltools.connections": [
    {
      "name": "Development DB",
      "driver": "PostgreSQL",
      "server": "${env:DB_HOST}",
      "port": "${env:DB_PORT}",
      "database": "${env:DB_NAME}",
      "username": "${env:DB_USER}",
      "password": "${env:DB_PASSWORD}"
    }
  ]
}

例3：API開発環境

{
  "rest-client.environmentVariables": {
    "development": {
      "baseUrl": "${env:DEV_API_URL}",
      "apiKey": "${env:DEV_API_KEY}"
    },
    "production": {
      "baseUrl": "${env:PROD_API_URL}",
      "apiKey": "${env:PROD_API_KEY}"
    }
  }
}

よくある間違いと注意点

直接的なシェル変数展開はできない

❌ 間違った書き方：

{
  "some.path": "$PATH/bin",
  "another.path": "%USERPROFILE%/tools"
}

✅ 正しい書き方：

{
  "some.path": "${env:PATH}/bin",
  "another.path": "${env:USERPROFILE}/tools"
}

プラットフォーム固有の設定

異なるOSで異なる設定を使いたい場合：

{
  "terminal.integrated.shell.windows": "${env:COMSPEC}",
  "terminal.integrated.shell.linux": "${env:SHELL}",
  "terminal.integrated.shell.osx": "${env:SHELL}",
  "python.defaultInterpreterPath": {
    "windows": "${env:USERPROFILE}/AppData/Local/Programs/Python/Python39/python.exe",
    "linux": "${env:HOME}/.pyenv/shims/python",
    "osx": "${env:HOME}/.pyenv/shims/python"
  }
}

環境変数が見つからない場合の対処

デフォルト値の設定

{
  "some.tool.path": "${env:TOOL_PATH:${workspaceFolder}/tools}"
}

この書き方により、TOOL_PATH 環境変数が設定されていない場合は ${workspaceFolder}/tools が使用されます。

tasks.jsonでの環境変数活用

基本的なタスク設定

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "shell",
      "command": "${env:BUILD_TOOL}",
      "args": [
        "--config",
        "${workspaceFolder}/build.config",
        "--output",
        "${env:OUTPUT_DIR:${workspaceFolder}/dist}"
      ],
      "group": "build",
      "options": {
        "cwd": "${workspaceFolder}",
        "env": {
          "NODE_ENV": "${env:NODE_ENV:development}",
          "API_URL": "${env:API_URL}"
        }
      }
    }
  ]
}

複雑なビルドタスクの例

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Docker Build",
      "type": "shell",
      "command": "docker",
      "args": [
        "build",
        "-t",
        "${env:DOCKER_REGISTRY}/${workspaceFolderBasename}:${env:BUILD_VERSION:latest}",
        "--build-arg",
        "NODE_ENV=${env:NODE_ENV:production}",
        "${workspaceFolder}"
      ],
      "group": "build",
      "options": {
        "env": {
          "DOCKER_BUILDKIT": "1"
        }
      }
    }
  ]
}

launch.jsonでのデバッグ設定

Python デバッグ設定

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "python": "${env:PYTHON_PATH:${workspaceFolder}/.venv/bin/python}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "DATABASE_URL": "${env:DATABASE_URL}",
        "DEBUG": "${env:DEBUG:true}"
      }
    }
  ]
}

Node.js デバッグ設定

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Node.js",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/index.js",
      "env": {
        "NODE_ENV": "${env:NODE_ENV:development}",
        "PORT": "${env:PORT:3000}",
        "API_KEY": "${env:API_KEY}"
      },
      "envFile": "${workspaceFolder}/.env"
    }
  ]
}

高度な環境変数の活用

.env ファイルとの連携

多くの拡張機能は .env ファイルから環境変数を読み込めます：

.env ファイルの例

# .env
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key-here
NODE_ENV=development
DEBUG=true

settings.json での .env ファイル指定

{
  "python.envFile": "${workspaceFolder}/.env",
  "terminal.integrated.env.linux": {
    "ENV_FILE": "${workspaceFolder}/.env"
  }
}

条件付き設定

{
  "python.defaultInterpreterPath": "${env:PYTHON_PATH}",
  "python.linting.enabled": "${env:ENABLE_LINTING:true}",
  "python.testing.autoTestDiscoverOnSaveEnabled": "${env:AUTO_DISCOVER_TESTS:false}"
}

複数環境での設定管理

開発環境用設定

{
  "terminal.integrated.env.linux": {
    "NODE_ENV": "development",
    "API_URL": "${env:DEV_API_URL:http://localhost:3000}",
    "LOG_LEVEL": "debug"
  }
}

本番環境用設定

{
  "terminal.integrated.env.linux": {
    "NODE_ENV": "production",
    "API_URL": "${env:PROD_API_URL}",
    "LOG_LEVEL": "info"
  }
}

トラブルシューティング

環境変数が認識されない場合

1. VS Codeの再起動

環境変数を新しく設定した後は、VS Codeを再起動する必要があります。

2. 環境変数の確認

# Linux/macOS
echo $MY_VARIABLE

# Windows (コマンドプロンプト)
echo %MY_VARIABLE%

# Windows (PowerShell)
echo $env:MY_VARIABLE

3. VS Code内での確認

VS Codeの統合ターミナルで環境変数を確認：

# 統合ターミナルで
env | grep MY_VARIABLE

4. 設定の検証

コマンドパレット（Ctrl+Shift+P）で「Preferences: Open Settings (JSON)」を選択し、設定を確認。

よくあるエラーと解決法

エラー1: 「Variable reference not found」

原因： 環境変数が設定されていない

解決法：

# 環境変数を設定
export MY_VARIABLE=my_value

# または、デフォルト値を使用
"${env:MY_VARIABLE:default_value}"

エラー2: パスに空白が含まれる場合

問題のある設定：

{
  "some.path": "${env:PROGRAM_FILES}/My App/bin"
}

解決法：

{
  "some.path": "\"${env:PROGRAM_FILES}/My App/bin\""
}

便利な拡張機能と連携

dotenv 拡張機能

.env ファイルのシンタックスハイライトと管理：

拡張機能： mikestead.dotenv

機能：

  • .env ファイルのシンタックスハイライト
  • 環境変数の補完
  • エラー検出

Environment Variables 拡張機能

拡張機能： EnverVars

機能：

  • 環境変数の一覧表示
  • 設定画面から環境変数の編集
  • プロジェクト固有の環境変数管理

設定例

{
  "environmentVariables.enableTelemetry": false,
  "environmentVariables.showValues": true,
  "environmentVariables.sources": [
    "${workspaceFolder}/.env",
    "${workspaceFolder}/.env.local"
  ]
}

ベストプラクティス

1. セキュリティの考慮

機密情報は環境変数に：

{
  "database.password": "${env:DB_PASSWORD}",
  "api.key": "${env:API_KEY}"
}

避けるべき書き方：

{
  "database.password": "plain-text-password",
  "api.key": "hardcoded-api-key"
}

2. ポータビリティの確保

プラットフォーム非依存の設定：

{
  "python.defaultInterpreterPath": "${env:PYTHON_PATH:python}",
  "node.path": "${env:NODE_PATH:node}"
}

3. デフォルト値の活用

{
  "build.outputDir": "${env:BUILD_OUTPUT:${workspaceFolder}/dist}",
  "test.timeout": "${env:TEST_TIMEOUT:5000}"
}

4. ドキュメント化

プロジェクトの README.md に必要な環境変数を記載：

## 必要な環境変数

- `DATABASE_URL`: データベース接続URL
- `API_KEY`: 外部API のアクセスキー
- `NODE_ENV`: 実行環境 (development/production)

まとめ

VS Codeの settings.json で環境変数を効果的に活用する方法を包括的に解説しました。

重要なポイント

VS Code変数の活用：

  • ${workspaceFolder} などの組み込み変数を積極的に使用
  • プロジェクト固有の設定で柔軟性を確保

環境変数の活用：

  • ${env:VARNAME} 形式でシェル環境変数を参照
  • デフォルト値 ${env:VARNAME:default} を活用してロバスト性を向上

セキュリティと保守性：

  • 機密情報は環境変数に分離
  • プラットフォーム非依存の設定を心がける

活用シーン別まとめ

シーン推奨アプローチ
個人開発${workspaceFolder} + 基本的な環境変数
チーム開発.env ファイル + 共通設定テンプレート
CI/CD環境環境変数を活用した動的設定
マルチプラットフォームプラットフォーム固有設定の分離

Youtube

神話・歴史・伝承の解説チャンネル

スポンサーリンク

コメント

タイトルとURLをコピーしました