Python环境变量管理用python-dotenv吗

wen python案例 2026-07-06 4

本文目录导读：

为什么推荐 python-dotenv？
基本用法
python-dotenv 的最佳实践
何时不推荐 python-dotenv？
更现代化的替代方案：pydantic-settings
总结建议

是的，python-dotenv 是 Python 中管理环境变量最流行、最推荐的第三方库之一，尤其适合开发环境和小型项目使用。

下面详细介绍它的使用场景、优缺点以及更好的替代方案,帮助你更好地做选择。

为什么推荐 `python-dotenv`？

它的核心思想是：将配置信息（如 API 密钥、数据库密码）放在项目根目录的 .env 文件中，然后在代码运行时自动加载到 os.environ（环境变量）里。

分离配置与代码：避免敏感信息（如密码）硬编码在 settings.py 或代码仓库中。
简单易用：只需几行代码即可使用。
与 .gitignore 配合：将 .env 文件加入 .gitignore，防止敏感信息被提交到 Git 仓库。

基本用法

1 安装

pip install python-dotenv

2 创建 `.env` 文件（项目根目录）

# 注释：这是你的秘密配置
DATABASE_HOST=localhost
DATABASE_PORT=5432
SECRET_KEY=your-secret-key-here
API_KEY=sk-xxxxxx

3 在代码中加载并使用

最推荐的写法（在程序入口处一次性加载）

# main.py 或 config.py
from dotenv import load_dotenv
import os
# 加载 .env 文件（默认在当前目录查找）
load_dotenv()
# 现在可以通过 os.getenv() 读取了
host = os.getenv("DATABASE_HOST")
port = os.getenv("DATABASE_PORT")
secret = os.getenv("SECRET_KEY")
print(f"连接数据库：{host}:{port}")

用于管理类的场景

from dotenv import load_dotenv
import os
class Config:
    def __init__(self):
        load_dotenv()
        self.DB_HOST = os.getenv("DATABASE_HOST", "localhost")
        self.DB_PORT = int(os.getenv("DATABASE_PORT", 5432))
        self.SECRET_KEY = os.getenv("SECRET_KEY", "default_secret")

`python-dotenv` 的最佳实践

只在 settings.py 或 main.py 顶部调用一次 load_dotenv()，不要在每个模块都调用,避免重复加载。
配合 .env.example 文件：在项目中提交一个 .env.example 文件（不包含真实值），让其他开发者知道需要哪些环境变量。
```
# .env.example
DATABASE_HOST=localhost
DATABASE_PORT=5432
SECRET_KEY=your_secret_key_here
```

指定 .env 文件路径：.env 不在当前工作目录，可以指定路径：

from pathlib import Path
env_path = Path('.') / '.env'
load_dotenv(dotenv_path=env_path)

何时不推荐 `python-dotenv`？

尽管 python-dotenv 很好用，但在以下场景中,有更好的替代方案：

场景	不推荐使用 `python-dotenv` 的原因	更推荐的方案
生产环境（Docker/K8S）	生产环境（特别是容器化部署）往往会直接设置系统环境变量，无需 `.env` 文件，使用 `python-dotenv` 会增加文件依赖和潜在的安全风险（`.env` 文件可能意外泄露）。	直接使用 `os.environ.get()` 读取系统环境变量，或将配置注入容器。
大型框架（Django/Flask）	Django 和 Flask 本身就有完善的配置管理机制（如 Django 的 `settings.py` 或 Flask 的 `app.config.from_envvar`）。	- Django：`os.environ.get()` 在 `settings.py` 中读取。 - Flask：`app.config.from_prefixed_env()`。
需要强类型验证	`python-dotenv` 只负责加载字符串，不提供类型转换或校验。	`pydantic-settings`（目前最推荐的方案）。

更现代化的替代方案：`pydantic-settings`

如果你正在用 FastAPI、Pydantic V2 或者希望自动进行类型校验、.env 文件加载，pydantic-settings 是目前最优秀的方案（也是 Python 官方推荐的趋势）。

示例：

pip install pydantic-settings

# settings.py
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
    # 自动从 .env 或环境变量读取，并自动转换类型
    database_host: str = "localhost"       # 默认值
    database_port: int = 5432              # 自动转 int
    secret_key: str                        # 必须存在，否则报错
    class Config:
        env_file = ".env"                  # 自动加载 .env 文件
settings = Settings()
# 使用
print(settings.database_host)  # 类型已经是 str
print(settings.database_port)  # 类型已经是 int

优点：

自动类型转换：port=5432 会被自动转为 int，无需手动 int()。
自动校验：secret_key 缺失,启动即报错。
自动兼容系统环境变量：即使没有 .env 文件,也能读取系统环境变量。
嵌套配置：支持更复杂的配置结构。

总结建议

简单项目 / 快速原型 / 学习：✅ 直接使用 python-dotenv，它够用、简单、教程多。
生产环境 / Docker 部署：❌ 不要依赖 .env 文件，使用系统环境变量 + os.getenv() 或 pydantic-settings。
现代项目 / FastAPI / 需要类型安全：👍 强烈推荐 pydantic-settings，它实际上内部已经集成了 python-dotenv，但你不需要直接写 load_dotenv(),一切都是自动的。