Complete Guide to Environment Variable Configuration in Visual Studio Code's launch.json

Environment Variable Configuration Fundamentals

In Visual Studio Code, the debug configuration file launch.json is the core file for managing project debugging environments. Proper configuration of environment variables is crucial for application debugging, especially in scenarios requiring access to database connection strings, API keys, or other sensitive information.

Problem Analysis and Solutions

Based on user-reported problem cases, when adding environment variables to the launch.json file results in "OpenDebug process has terminated unexpectedly" errors, this typically relates to environment variable format or platform compatibility issues. Historical versions did have environment variable handling problems on Windows and Linux platforms, which were resolved in Visual Studio Code version 0.3.0.

The correct format for environment variable configuration is as follows:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "pwa-node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": [
        "<node_internals>/**"
      ],
      "program": "${workspaceFolder}/index.js",
      "env": {
        "CONNECTION_STRING": "Data Source=server;Initial Catalog=catalog;User ID=uid;Password=pwd;MultipleActiveResultSets=true",
        "NODE_ENV": "development"
      }
    }
  ]
}

Variable Substitution Mechanism Details

Visual Studio Code supports variable substitution in debugging and task configuration files. Variable substitution uses the ${variableName} syntax and takes effect in specific key-value strings within launch.json and tasks.json files.

The variable substitution process occurs in two phases: first, all variables are evaluated to string results, with each variable evaluated only once; second, all variables are substituted with the results from the first phase. This design ensures independence between variables and avoids evaluation order dependencies.

Predefined Variable Types

The system provides a rich set of predefined variables, including:

• ${workspaceFolder}: Workspace folder path
• ${file}: Currently opened file path
• ${fileBasename}: Current file's basename
• ${lineNumber}: Current cursor line number
• ${selectedText}: Currently selected text content

Environment Variable References

System environment variables can be referenced using the ${env:Name} syntax. For example, referencing the username environment variable in a debug configuration:

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",
  "cwd": "${workspaceFolder}",
  "args": ["${env:USERNAME}"]
}

Configuration and Command Variables

Using the ${config:Name} syntax allows referencing VS Code settings, such as ${config:editor.fontSize} referencing the editor font size setting. Command variables execute arbitrary VS Code commands through the ${command:commandID} syntax, where commands must return string results to complete variable substitution.

Input Variable System

Input variables provide more flexible configuration options through the ${input:variableID} syntax. Three input types are supported:

• promptString: Displays an input box to get user string input
• pickString: Displays a quick pick dropdown menu
• command: Runs arbitrary commands

Multi-Platform Compatibility Considerations

To address environment variable handling differences across operating systems, it's recommended to ensure the use of the latest Visual Studio Code version. For path-related variables, note the different behavior of the ${pathSeparator} variable on Windows versus Unix systems: Windows uses backslashes \, while macOS and Linux use forward slashes /.

Debug Configuration Best Practices

When configuring Node.js project debugging environments, it's recommended to:

1. Always use the latest version of Visual Studio Code
2. Properly escape special characters in environment variable values
3. Utilize IntelliSense to get complete predefined variable lists
4. Verify variable actual values by creating simple echo tasks
5. Consider using input variables instead of hardcoding for sensitive information

Troubleshooting and Verification

When environment variable configuration issues arise, create verification tasks to check variable values:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "echo",
      "type": "shell",
      "command": "echo ${workspaceFolder}"
    }
  ]
}

Running this task outputs the actual parsed value of variables in the terminal, helping diagnose configuration problems.