在VS Code launch.json中配置Python运行环境变量

在本地运行与调试 Python 程序时，数据库连接串、API 密钥或运行模式（如 DEBUG=True）通常依赖环境变量注入。在 VS Code 中，最稳妥且与调试会话直接绑定的配置方式，是在工作区目录下的 .vscode/launch.json 文件中声明 env 或 envFile 字段。这种方式仅在启动调试会话时将指定键值注入到 Python 子进程中，既不污染操作系统的全局环境，也不会随代码提交泄露敏感凭证。

一、创建并定位 launch.json 调试配置文件

VS Code 的运行与调试体系通过工作区根目录下的 .vscode/launch.json 进行管理。若当前项目尚未创建该文件，可以通过界面引导快速生成：

1. 使用 VS Code 打开项目根文件夹。
2. 点击左侧活动栏的运行和调试图标（或按下快捷键 Ctrl+Shift+D / Cmd+Shift+D）。
3. 在调试面板顶部点击“创建 launch.json 文件”，并在弹出的调试器列表中选择 Python Debugger，随后选择 Python File（针对当前打开文件的调试模板）。
4. VS Code 将自动在工作区下生成 .vscode/launch.json，并附带一组默认的启动配置项。

图 1：在 VS Code 中配置并验证 Python 调试环境变量的四步标准流程

二、使用 env 属性直接定义环境变量

当需要配置的环境变量数量较少、内容不涉及敏感机密，或者只是临时调试特定分支逻辑时，可以直接在 launch.json 的特定配置项中添加 env 对象。该对象接受键值对形式，键与值均必须为字符串类型。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File (with Env)",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "env": {
                "APP_ENV": "development",
                "SERVICE_PORT": "8080",
                "ENABLE_FEATURE_X": "true"
            }
        }
    ]
}

三、使用 envFile 属性加载外部 .env 文件

在工程化项目中，环境变量通常包含敏感密码、Token 或庞杂的连接参数，更适宜存放于独立于版本控制的 .env 文件中。通过配置 envFile 属性，调试器会在拉起进程前自动解析指定的 .env 文件。

在项目根目录下创建 .env 文件：

# 项目基础运行配置
DATABASE_URL=postgresql://postgres:secret@localhost:5432/test_db
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
SECRET_KEY=k9x2m1q8-dev-token

随后在 launch.json 中引入该文件。为了保证跨操作系统以及协作成员打开项目时的路径一致性，推荐使用内置路径变量 ${workspaceFolder}：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Debug with .env",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "envFile": "${workspaceFolder}/.env"
        }
    ]
}

四、环境变量加载与合并优先级机制

在实际调试过程中，环境变量可能同时来源于三个渠道：操作系统宿主环境（System Environment）、envFile 指定的文件，以及 launch.json 中的 env 块。调试器在初始化子进程时会按照严格的优先级进行合并：

图 2：launch.json 中多来源环境变量的注入合并机制与优先级层级

这意味着：如果你在 .env 中设定了 PORT=5000，但临时在 launch.json 的 env 中写了 "PORT": "8888"，最终 Python 进程读取到的 PORT 将是 8888。这一机制非常适合在不修改 .env 文件的前提下快速重写特定测试变量。

五、编写 Python 代码验证环境变量

在 Python 代码中，通过标准库 os 模块中的 os.environ 即可直接获取注入的变量。为了确保代码在变量未配置时具备良好的防御性，建议优先使用 os.environ.get("KEY", default) 而非直接用下标 os.environ["KEY"] 取值：

import os

def check_runtime_config():
    # 方式一：使用 .get() 提供缺省回退值
    app_env = os.environ.get("APP_ENV", "local_default")
    service_port = os.environ.get("SERVICE_PORT", "3000")
    db_url = os.environ.get("DATABASE_URL", "sqlite:///:memory:")

    print("===== Python 运行环境变量检查 =====")
    print(f"当前运行环境 (APP_ENV): {app_env}")
    print(f"服务监听端口 (SERVICE_PORT): {service_port}")
    print(f"数据库连接串 (DATABASE_URL): {db_url}")

    # 方式二：对于核心关键变量，检查是否存在
    if "SECRET_KEY" not in os.environ:
        print("[警告] 未检测到 SECRET_KEY 环境变量！")
    else:
        print("[成功] SECRET_KEY 已就绪。")

if __name__ == "__main__":
    check_runtime_config()

按下 F5 键（或在“运行和调试”视图中点击绿色三角按钮），观察 VS Code 底部的集成终端（Integrated Terminal）。终端会输出对应的配置值，证明 launch.json 中的环境变量已经精准注入到调试进程中。

六、高频困惑：为什么终端直接运行取不到环境变量？

初学者最常遇到的问题是：在 launch.json 中配置了 env，按下 F5 调试时一切正常；但如果在右上角点击“运行 Python 文件”按钮，或者在下方终端中手动输入 python main.py 时，程序却报变量缺失或取到了系统默认值。

图 3：调试会话（F5）与终端直接命令行运行在环境变量加载链路上的本质差异

原因在于：launch.json 是专门提供给 VS Code 调试器（Debug Adapter）的执行协议，操作系统的终端 Shell（如 Bash、Zsh、PowerShell）根本不会去读取该 JSON 文件。如果你希望在终端直接运行 Python 时也能自动加载 .env 文件，可以配合使用以下两种补充方案：

• 使用 python-dotenv 库（代码级加载）：在 Python 入口文件顶部调用 load_dotenv()，使代码无论在何种启动方式下都能自动读取本地 .env 文件。
• 配置 settings.json 中的 python.envFile：在 .vscode/settings.json 中添加 "python.envFile": "${workspaceFolder}/.env"。这样 VS Code 在为该工作区打开新的集成终端时，会自动将 .env 注入终端环境。

七、配置选型与关键排查清单

为了在实际项目开发中建立清晰规范的配置流程，下表对比了 env 与 envFile 的典型应用场景与特点：

图 4：launch.json 环境变量配置规则、路径规范与排查核对总结全景图

通过遵循上述操作步骤与规范，开发者可以在 VS Code 中高效管理 Python 运行期的各类环境变量，既能保证本地调试的灵活性，又能切实保障凭据安全与跨环境部署的一致性。