告别配置混乱：5分钟掌握python-dotenv环境变量管理
项目地址: https://gitcode.com/gh_mirrors/py/python-dotenv python-dotenv是一个能从.env文件读取键值对并设置为环境变量的Python库，它帮助开发者遵循12-factor原则构建应用，轻松解决开发环境中的配置管理难题。
🚀 为什么需要python-dotenv？
在开发遵循12-factor原则的应用时，配置通常存储在环境变量中。但手动设置这些变量既繁琐又容易出错，尤其在多环境切换时。python-dotenv通过读取.env文件自动加载配置，让开发环境配置变得简单高效。
核心优势：
- 环境隔离：开发/测试/生产环境配置分离
- 安全便捷：敏感信息不硬编码，轻松管理密钥
- 简化部署：与CI/CD流程无缝集成
- 12-factor兼容：完美符合现代应用开发最佳实践
💻 快速安装指南
通过pip即可完成安装，支持Python 3.8及以上版本：
pip install python-dotenv
如需使用命令行功能，安装时添加cli选项：
pip install "python-dotenv[cli]"
📝 基础使用步骤
1. 创建.env文件
在项目根目录创建.env文件，按KEY=VALUE格式定义配置：
# .env文件示例
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
API_KEY=your_secret_key
DEBUG=True
DOMAIN=example.com
ADMIN_EMAIL=admin@${DOMAIN} # 支持变量插值
⚠️ 重要提示：务必将.env文件添加到.gitignore，防止敏感信息泄露！
2. 在代码中加载配置
使用load_dotenv()函数加载.env文件到环境变量：
from dotenv import load_dotenv
import os
# 加载.env文件
load_dotenv()
# 访问环境变量
db_url = os.getenv("DATABASE_URL")
api_key = os.getenv("API_KEY")
debug_mode = os.getenv("DEBUG", "False") == "True"
默认情况下，load_dotenv()会：
- 在脚本目录及其父目录中查找.env文件
- 不会覆盖已存在的环境变量（可通过
override=True参数修改）
⚙️ 高级使用技巧
加载多个配置文件
通过dotenv_values()函数可加载多个配置文件并合并：
from dotenv import dotenv_values
import os
config = {
**dotenv_values(".env.shared"), # 共享配置
**dotenv_values(".env.secret"), # 敏感配置
**os.environ, # 环境变量优先
}
命令行操作
安装cli扩展后，可直接通过命令行管理.env文件：
# 设置变量
dotenv set API_KEY "new_secret_value"
# 列出所有变量
dotenv list
# 以JSON格式输出
dotenv list --format=json
# 使用.env变量运行程序
dotenv run -- python app.py
IPython集成
在IPython或Jupyter中快速加载.env文件：
%load_ext dotenv
%dotenv # 自动查找.env文件
# 或指定路径：%dotenv /path/to/custom.env
📚 支持的文件格式
基本语法
- 键值对：
KEY=VALUE - 注释：以
#开头 - 引号支持：单引号或双引号包裹值
- 空格忽略：键值前后的空格会被自动忽略
特殊特性
-
多行值：使用三引号或反斜杠换行
LONG_TEXT="第一行 第二行 第三行" -
变量插值：使用
${VAR}引用其他变量BASE_URL=https://example.com API_URL=${BASE_URL}/api/v1 -
空值处理：
EMPTY_VAR= # 值为空字符串 NULL_VAR # 值为None（仅dotenv_values返回）
🛠️ 常见问题解决
变量未加载？
- 检查.env文件路径是否正确
- 确认变量名称没有拼写错误
- 尝试设置
load_dotenv(override=True)强制覆盖环境变量 - 检查是否设置了
PYTHON_DOTENV_DISABLED=1环境变量（会禁用加载）
特殊字符处理
包含空格或特殊字符的值需要用引号包裹：
APP_NAME="My Awesome App"
CONNECTION_STRING='postgres://user:pass@host/db name'
📦 项目结构参考
推荐的项目结构：
your_project/
├── .env # 本地开发配置（不上传Git）
├── .env.example # 配置示例（可上传Git）
├── .gitignore # 包含.env
├── app.py # 应用代码
└── requirements.txt # 依赖管理
🔄 与其他工具集成
python-dotenv可与多种框架和工具无缝配合：
- Django/Flask：在settings.py/app.py中加载配置
- Pytest：结合pytest-dotenv插件管理测试环境
- Docker：在Dockerfile或docker-compose.yml中引用.env
- CI/CD：与GitHub Actions、GitLab CI等持续集成工具兼容
通过python-dotenv，你可以告别手动设置环境变量的繁琐工作，让配置管理变得简单而高效。无论是小型项目还是大型应用，它都能帮助你保持代码的整洁和配置的安全。现在就尝试在你的项目中使用python-dotenv，体验更流畅的开发流程吧！
要开始使用，只需克隆仓库并按照上述指南操作：
git clone https://gitcode.com/gh_mirrors/py/python-dotenv
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
