如何优雅地在 VS Code 中为 Python 项目设置环境变量

在 python 项目开发中，环境变量是管理配置信息（如数据库凭证、api 密钥或路径设置）的常用方式。它们允许我们隔离敏感数据，并根据不同的部署环境调整应用行为，而无需修改核心代码。vs code 作为流行的 python 开发环境，提供了多种设置和管理环境变量的机制。然而，其行为在不同的运行和调试模式下可能存在细微差异，这常常导致开发者感到困惑。

理解 .env 文件与环境变量加载

.env 文件是一种常见的约定，用于存储项目的本地环境变量。它通常位于项目根目录，并包含键值对形式的环境变量定义。Python 程序可以通过 os 模块访问这些变量。

示例：项目结构与代码

假设我们的项目结构如下：

your_project/
├── venv/
├── .env
└── test_load_env.py

.env 文件内容：

立即学习“Python免费学习笔记（深入）”；

PYTHONPATH=.
MY_USERNAME=myusername
MY_PASSWORD=mypass

test_load_env.py 用于读取这些环境变量：

import os

# 尝试从环境变量中获取值
username = os.environ.get("MY_USERNAME")
password = os.environ.get("MY_PASSWORD")
python_path = os.environ.get("PYTHONPATH")

print(f"Username: {username}, Password: {password}")
print(f"PYTHONPATH: {python_path}")

# 检查环境变量是否成功加载
if username and password and python_path:
    print("环境变量已成功加载。")
else:
    print("部分或全部环境变量未加载。")

在理想情况下，我们期望运行 test_load_env.py 时，上述变量能够被正确读取。然而，在 VS Code 中，这并非总是自动发生。

VS Code 中环境变量加载机制解析

VS Code 在不同的执行上下文（运行模式）下，对 .env 文件的处理方式有所不同。理解这些差异是有效管理环境变量的关键。

1. 在终端中运行 Python 文件

当您通过 VS Code 的终端（例如，右键点击文件选择 "Run Python File in Terminal" 或直接在集成终端中执行 python test_load_env.py）运行 Python 文件时，VS Code 默认不会自动加载项目根目录下的 .env 文件。这意味着 os.environ.get() 将返回 None。

2. 在交互式窗口中运行

在 VS Code 的 Python 交互式窗口中执行代码时，VS Code 会自动识别并加载项目根目录下的 .env 文件。因此，在这种模式下，test_load_env.py 中的环境变量会正常读取。

3. 通过 F5 调试

使用 F5 键启动调试会话时，VS Code 默认会加载 .env 文件。此外，launch.json 文件中的配置也可以用于定义或覆盖环境变量。这是一个强大的调试工具，允许为不同的调试场景设置特定的环境变量。

示例：launch.json 配置

在 .vscode/launch.json 中，您可以添加 env 字段来设置环境变量：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "env": {
                "MY_USERNAME": "debug_user",
                "DEBUG_MODE": "True"
            },
            "envFile": "${workspaceFolder}/.env" // 也可以指定 .env 文件
        }
    ]
}

envFile 属性可以指定要加载的 .env 文件路径。如果同时存在 env 和 envFile，env 中的变量会覆盖 envFile 中同名的变量。

笔目鱼英文论文写作器

写高质量英文论文，就用笔目鱼

87

查看详情

4. 使用 "Debug Python File" 选项

当您右键点击 Python 文件并选择 "Debug Python File" 时，VS Code 也会自动加载 .env 文件。这与 F5 调试的行为类似，因为它本质上是启动了一个调试会话。

5. settings.json 中的 python.envFile 配置

VS Code 的 settings.json 中有一个 python.envFile 设置，可以指定全局或工作区级别的 .env 文件路径。例如：

// .vscode/settings.json
{
    "python.envFile": "${workspaceFolder}/.env"
}

然而，需要注意的是，这个设置主要影响的是调试器和某些语言服务，对于“在终端中运行 Python 文件”的场景，它通常不起作用。这解释了为什么在某些情况下添加此设置后，环境变量仍然无法加载。

总结：VS Code 运行与调试选项对 .env 的支持情况

下表总结了不同运行选项对 .env 文件和 launch.json 配置的加载行为：

从上表可以看出，VS Code 的调试模式（F5 调试、"Debug Python File"、交互式窗口）通常会加载 .env 文件，而直接在终端中运行则不会。

推荐实践：使用 python-dotenv 确保一致性

鉴于 VS Code 在不同运行模式下对 .env 文件的加载行为不一致，为了确保项目在任何执行场景下（无论是直接运行、调试还是部署到生产环境）都能一致地加载环境变量，推荐使用 python-dotenv 库。

python-dotenv 是一个轻量级库，它允许 Python 应用程序从 .env 文件中读取键值对并将其设置为环境变量。

1. 安装 python-dotenv

pip install python-dotenv

2. 在代码中加载环境变量

修改 test_load_env.py，在程序启动时显式加载 .env 文件：

import os
from dotenv import load_dotenv

# 在程序开始时加载 .env 文件
load_dotenv()

# 尝试从环境变量中获取值
username = os.environ.get("MY_USERNAME")
password = os.environ.get("MY_PASSWORD")
python_path = os.environ.get("PYTHONPATH")

print(f"Username: {username}, Password: {password}")
print(f"PYTHONPATH: {python_path}")

# 检查环境变量是否成功加载
if username and password and python_path:
    print("环境变量已成功加载。")
else:
    print("部分或全部环境变量未加载。")

通过在代码顶部调用 load_dotenv()，无论您选择哪种方式在 VS Code 中运行或调试，甚至在 VS Code 外部直接运行 Python 脚本，test_load_env.py 都能可靠地加载 .env 文件中的环境变量。这提供了一种最灵活且一致的解决方案。

注意事项与最佳实践

1. VS Code 版本差异： 提问者提到 VS Code Insiders 版本（1.85.0）自动加载 .env，而稳定版（1.84.2）不加载。这表明 VS Code 团队可能正在改进或调整 .env 文件的处理逻辑。在不同版本之间，行为可能存在差异，但使用 python-dotenv 能够有效规避这些不确定性。
2. 敏感信息管理： .env 文件通常包含敏感信息。确保 .env 文件被添加到 .gitignore 中，避免将其提交到版本控制系统。
3. 与其他配置方式的优先级：
   • 通过 os.environ 预先设置的环境变量（例如，在运行脚本前通过 shell 命令设置）具有最高优先级。
   • launch.json 中的 env 字段会覆盖 .env 文件中同名的变量。
   • python-dotenv 加载的变量通常会覆盖当前环境中已存在的同名变量（除非 override=False）。 理解这些优先级有助于避免意外的配置冲突。
4. 生产环境部署： 在生产环境中，通常不建议依赖 .env 文件。更推荐使用部署平台的内置环境变量管理机制（如 Docker secrets, Kubernetes secrets, CI/CD 管道变量等）来注入配置。python-dotenv 主要用于本地开发环境。

总结

在 VS Code 中为 Python 项目设置环境变量，尤其是使用 .env 文件时，其行为会因运行模式而异。调试模式通常会自动加载 .env，而直接在终端中运行则不会。为了实现最可靠和一致的环境变量管理，推荐在 Python 代码中显式使用 python-dotenv 库来加载 .env 文件。结合 launch.json 进行调试特定配置，可以构建一个健壮且灵活的环境变量管理策略，确保项目在任何场景下都能正确运行。

以上就是如何优雅地在 VS Code 中为 Python 项目设置环境变量的详细内容，更多请关注php中文网其它相关文章！