python-dotenv 使用文档

1. 文档概述

python-dotenv 是 Python 生态中用于管理环境变量 的标准工具库，核心函数 load_dotenv() 可从项目根目录的 .env 文件中读取键值对，并自动注入到系统环境变量中，实现敏感配置与业务代码分离，是现代 Python 项目的必备工具。

2. 核心作用

隔离敏感信息（API Key、数据库密码、密钥等），避免泄露至代码仓库
支持开发/测试/生产多环境配置无缝切换
统一管理项目配置，提升团队协作效率
符合 12-Factor App 配置分离规范

3. 快速开始

3.1 安装依赖

bash 复制代码

pip install python-dotenv

3.2 创建环境变量文件

在项目根目录 创建 .env 文件，按 KEY=VALUE 格式编写配置：

env 复制代码

# .env 文件示例
# 注释以 # 开头
DEBUG=True
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
API_KEY=sk-xxxxxx-secret-key
SECRET_KEY=your-django-secret-key
PORT=8000
# 值含空格/特殊字符需用引号包裹
MSG="Hello World"

3.3 基础使用

python 复制代码

# 导入核心函数与系统环境变量模块
from dotenv import load_dotenv
import os

# 加载 .env 文件（默认读取当前目录下的 .env）
load_dotenv()

# 通过 os.getenv() 获取环境变量
# 推荐用法：可设置默认值，避免变量不存在报错
debug_mode = os.getenv("DEBUG", "False") == "True"
api_key = os.getenv("API_KEY")
port = int(os.getenv("PORT", 5000))

print(f"调试模式: {debug_mode}")
print(f"服务端口: {port}")

4. load_dotenv() 进阶参数

4.1 指定自定义配置文件

支持加载不同环境的配置文件（如生产环境、测试环境）：

python 复制代码

# 加载生产环境配置
load_dotenv(dotenv_path=".env.production")

4.2 强制覆盖系统已有变量

python 复制代码

# override=True：若系统已存在同名环境变量，强制覆盖
load_dotenv(override=True)

4.3 自动向上级目录查找

python 复制代码

# verbose=True：自动向上级目录查找 .env 文件，未找到时输出提示
load_dotenv(verbose=True)

5. 主流框架集成示例

5.1 Flask 集成

在应用创建前加载环境变量：

python 复制代码

from dotenv import load_dotenv
# 先加载配置
load_dotenv()
from flask import Flask

app = Flask(__name__)

@app.route("/")
def index():
    return "Hello Flask"

5.2 Django 集成

在 settings.py 顶部加载配置：

python 复制代码

import os
from dotenv import load_dotenv

# 定位项目根目录并加载 .env
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
load_dotenv(os.path.join(BASE_DIR, '.env'))

# 后续使用配置
SECRET_KEY = os.getenv("SECRET_KEY")
DEBUG = os.getenv("DEBUG", "False") == "True"

6. 安全与最佳实践

实践项	说明
.gitignore 必须包含 .env	防止敏感配置被提交到 Git 仓库
提供 .env.example 模板	供团队参考，不包含真实密钥
禁止提交真实 .env 文件	尤其避免上传至 GitHub/GitLab
生产环境慎用	云平台（AWS/Heroku）通过控制台设置环境变量
校验必填变量	项目启动时检查关键配置是否存在

6.1 .gitignore 配置示例

复制代码

# 忽略所有环境变量文件
.env
.env.local
.env.production
.env.test

6.2 .env.example 模板示例

env 复制代码

# 复制此文件为 .env 并填写真实配置
DATABASE_URL=your_database_url
API_KEY=your_api_key
DEBUG=False
PORT=8000

7. 常见问题排查

问题现象	解决方案
加载后获取不到变量	1. 检查 .env 路径是否正确 2. 变量名区分大小写 3. 确保在 load_dotenv() 之后调用 os.getenv()
中文/特殊字符乱码	将 .env 文件编码保存为 UTF-8
变量含空格解析异常	用双引号包裹变量值
Docker 环境不生效	1. 将 .env 复制到镜像内 2. 使用 docker run --env-file .env 参数

8. 总结

python-dotenv 是 Python 项目安全管理配置的标准方案，仅需三步即可完成接入：

安装 python-dotenv
创建 .env 配置文件
调用 load_dotenv() 加载配置

配合 .gitignore 与配置模板，可大幅提升项目安全性、可维护性与协作效率，是现代 Python 开发的最佳实践之一。