如何为不同环境（开发、测试、生产）灵活加载 .env 配置文件

本文介绍如何利用 python-dotenv，根据命令行指定的环境名称（例如 qa、staging、prod）自动加载对应的 .env.{env} 文件，从而实现多环境配置管理，过程中无需硬编码路径或额外设置模块。

在实际项目中，不同部署环境（如开发、测试、预发布、生产）往往需要隔离配置。python-dotenv 本身并未内置多环境切换机制，但这并不意味着要引入复杂的工具。通过组合系统环境变量与命令行参数，完全可以实现一套简洁、可扩展的多环境加载方案。

✅ 推荐实践：通过 ENVIRONMENT 环境变量动态加载

最轻量且符合 Unix 哲学的做法，是利用操作系统环境变量来控制加载逻辑。无需修改 python-dotenv 源码，也不必单独编写一个 settings 模块，只需在启动脚本时传入一个环境标识即可：

# 加载 .env.qa
ENVIRONMENT=qa python test.py

# 加载 .env.staging
ENVIRONMENT=staging python test.py

# 加载 .env.prod
ENVIRONMENT=prod python test.py

对应的 Python 脚本（test.py）如下：

import os
from dotenv import load_dotenv
from pathlib import Path

# 1. 获取环境名，默认为 'development'
env_name = os.getenv('ENVIRONMENT', 'development')

# 2. 构建对应 .env 文件路径（支持当前目录或自定义目录）
dotenv_path = Path(f'.env.{env_name}')

# ✅ 关键：仅当文件存在时才加载，避免静默失败
if dotenv_path.exists():
    load_dotenv(dotenv_path)
    print(f"✅ Loaded environment variables from {dotenv_path}")
else:
    print(f"⚠️  Warning: {dotenv_path} not found. Using default environment or system variables.")

# 3. 读取配置（支持 fallback 或报错提示）
host = os.getenv('HOST')
if not host:
    raise ValueError("Missing required environment variable: HOST")

print(f"HOST = {host}")

? 目录结构建议（清晰可维护）

project/
├── .env.development     # 默认开发配置
├── .env.qa              # 测试环境
├── .env.staging         # 预发布环境
├── .env.prod            # 生产环境
├── test.py              # 主程序
└── README.md

? 提示：.env.* 文件应加入 .gitignore，防止敏感配置泄露；推荐使用 .env.example 作为模板提交至仓库。

⚠️ 注意事项与最佳实践

• 不要依赖 load_dotenv() 的默认行为：它只加载 .env，不会识别 .env.* —— 必须显式传入 dotenv_path。这一点很容易被忽略。
• 路径安全校验很重要：使用 Path.exists() 判断文件是否存在，可以避免因路径错误导致配置未加载，却能毫无提示地继续运行。
• 环境变量优先级：os.getenv() 总是优先返回已存在的系统环境变量（比如在 shell 中 export HOST=xxx），.env 文件仅作为 fallback。如果需要强制覆盖现有变量，可以在 load_dotenv() 中设置 override=True：

  load_dotenv(dotenv_path, override=True)  # 覆盖已存在的同名变量

• 命令行参数替代方案（进阶）：如果希望有更明确的 CLI 控制（比如 python test.py --env prod），可以结合 argparse 来实现：

  import argparse
  
  parser = argparse.ArgumentParser()
  parser.add_argument('--env', default='development')
  args = parser.parse_args()
  
  dotenv_path = Path(f'.env.{args.env}')
  load_dotenv(dotenv_path)

通过以上方式，既保持了代码的简洁性，又实现了生产就绪的多环境配置管理——没有依赖第三方扩展，仅靠 python-dotenv 的原生能力，就能稳健支撑起 CI/CD 流程。