本文详解如何在 UV 管理的 Python 虚拟环境中正确设置和加载环境变量——不依赖手动修改激活脚本，而是采用官方推荐的 --env-file 和 UV_ENV_FILE 机制，确保跨平台一致性、CI/CD 可靠性及团队协作可复现性。
本文详解如何在 uv 管理的 python 虚拟环境中正确设置和加载环境变量——不依赖手动修改激活脚本，而是采用官方推荐的 `--env-file` 和 `uv_env_file` 机制，确保跨平台一致性、ci/cd 可靠性及团队协作可复现性。
UV 并不鼓励也不支持通过直接编辑 .venv/scripts/activate（Windows）或 .venv/bin/activate（Linux/macOS）等激活脚本来注入环境变量——这类方式不仅破坏虚拟环境的纯净性与可移植性，更会在 uv run 无激活模式下完全失效，且无法被 Git 跟踪或 CI 流水线复现。
✅ 正确做法是：将环境变量声明分离至独立配置文件，并由 UV 在运行时按需加载。UV 原生支持 .env 文件格式（兼容 Docker Compose / python-dotenv 语法），并通过两种标准化方式注入：
✅ 方式一：命令行显式指定（推荐用于调试与单次执行）
# 创建 .env 文件（明文，切勿提交敏感密钥！） echo "DEBUG=True" > .env echo "DATABASE_URL=sqlite:///dev.db" >> .env echo "API_TIMEOUT=30" >> .env # 运行脚本时自动加载 .env 中的变量 uv run --env-file=.env python app.py
? 提示：
uv run会自动激活对应虚拟环境（无需source .venv/bin/activate），并在子进程中注入.env变量，Python 代码中可通过os.getenv("DEBUG")直接读取。
✅ 方式二：全局/项目级环境变量预设（推荐用于开发与 CI）
# 设置 UV 全局默认 env 文件路径（例如在 ~/.zshrc 或 ~/.bashrc 中） export UV_ENV_FILE=./.env # 或在项目根目录设置项目级配置（优先级更高） echo '[run]' > uv.toml echo 'env-file = ".env"' >> uv.toml
此后所有 uv run 命令（包括 uv run pytest、uv run flask run）均自动加载该文件，无需重复指定 --env-file。
⚠️ 重要注意事项
-
安全性：
.env文件默认不被 Git 跟踪（请在.gitignore中添加.env），生产环境应使用 secrets manager 或 CI 变量注入，切勿提交 API keys、DB passwords 等敏感信息。 -
作用域隔离：通过
--env-file加载的变量仅作用于当前uv run进程及其子进程，不会污染系统 Shell 或其他虚拟环境，符合最小权限原则。 -
格式规范：
.env文件须为 UTF-8 编码，每行KEY=VALUE，支持# 注释、引号包裹（PATH="/usr/local/bin:$PATH"）、变量展开（$HOME）——但不支持跨行或复杂 shell 表达式。 -
与
uv venv的关系：环境变量配置与虚拟环境创建（uv venv）解耦。你可先用uv venv --python=3.12 .venv创建环境，再通过uv run --env-file=.env启动应用——二者职责清晰，互不干扰。
? 验证是否生效（快速诊断）
# 查看当前运行环境中的实际变量
uv run --env-file=.env python -c "import os; print('DEBUG=', os.getenv('DEBUG'))"
# 输出示例：
# DEBUG= True
? 进阶提示：结合
uv lock与uv sync，你还能将.env的结构约束写入pyproject.toml的[tool.uv.run]段，实现“环境变量 schema + 依赖版本 + Python 版本”三位一体的项目环境声明，真正达成「一次配置，处处可运行」的现代 Python 工程实践。
总之，UV 将环境变量管理从“手工打补丁”升级为“声明式配置”，既保持了极简命令体验，又兼顾了企业级工程严谨性。放弃修改 activate 脚本，拥抱 --env-file，是你迈向可复现、可审计、可协作 Python 开发的关键一步。
