Python dotenv 使用指南：轻松管理项目环境变量
一、为什么要使用环境变量管理？
很多开发者容易把自己开发的项目上传到Github上，但偶尔会忘记把数据库密码、支付接口密钥等敏感信息和谐掉，当代码提交上去时，这些信息就像裸奔一样暴露在所有人面前。更糟糕的是，不同环境（开发 / 测试 / 生产）的配置频繁切换，每次都要修改代码，效率低下且容易出错。
环境变量管理的核心价值在于：
- 安全隔离：敏感信息不进代码库，通过
.env文件独立存储 - 环境统一：开发 / 测试 / 生产环境配置一键切换
- 协作友好：团队成员共享配置模板（
.env.example），各自维护敏感信息 - 12-Factor 合规：符合现代云原生应用的最佳实践
二、Python dotenv 核心功能速览
python-dotenv 是 Python 生态中管理环境变量的瑞士军刀，它能：
- 自动加载：从.env 文件读取配置并注入环境变量
- 类型安全：支持布尔值、数字等类型自动转换
- 多环境管理：通过不同的.env 文件适配开发 / 生产环境
- 框架集成：与 Flask、Django、FastAPI 等主流框架无缝协作
三、5 分钟快速上手
1. 安装与初始化
# 基础安装
pip install python-dotenv
# 推荐安装带CLI工具的版本
pip install "python-dotenv[cli]"
2. 创建配置文件
在项目根目录创建.env 文件：
# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASS=s3cr3t! # 包含特殊字符无需引号# 功能开关
FEATURE_NEW_LOGIN=true
API_RATE_LIMIT=100
3. 加载与使用
# app.py
from dotenv import load_dotenv
import os# 自动搜索并加载.env文件
load_dotenv(verbose=True, override=True)# 读取配置的三种方式
db_host = os.getenv('DB_HOST') # 带默认值
db_port = os.getenv('DB_PORT', 5432) # 带默认值
db_user = os.environ['DB_USER'] # 直接访问，不存在会抛异常print(f"Connecting to {db_user}@{db_host}:{db_port}")
四、生产级实践方案
1. 多环境配置管理
# 目录结构
config/
├── .env.local # 本地开发环境
├── .env.staging # 预发布环境
├── .env.production # 生产环境
└── .env.example # 配置模板（需提交到代码库）
# 根据环境变量加载不同配置
import os
from dotenv import load_dotenvenv = os.getenv('ENV', 'local')
load_dotenv(f'config/.env.{env}')
2. 类型安全与验证
from pydantic import BaseSettingsclass Settings(BaseSettings):api_key: strdebug: bool = Falserate_limit: int = 100class Config:env_file = ".env"settings = Settings()
3. 安全增强方案
① 加密敏感信息
# 使用ansible-vault加密.env文件
ansible-vault encrypt .env.production
② 云原生存储
# 结合AWS Parameter Store
import boto3
from dotenv import dotenv_valuesdef load_aws_secrets():client = boto3.client('ssm')response = client.get_parameter(Name='/prod/database/password',WithDecryption=True)return {'DB_PASS': response['Parameter']['Value']}config = {**dotenv_values('.env.production'),**load_aws_secrets()
}
五、常见问题与解决方案
1. 变量未生效？
# 强制覆盖现有环境变量
load_dotenv(override=True)# 检查文件路径
load_dotenv('/custom/path/.env')
2. Flask 项目无法启动？
# 避免在项目根目录创建.env文件
project/
├── app/
│ ├── __init__.py
│ └── .env # 正确位置
└── .env # 错误位置
3. Docker 部署问题
# 最佳实践：使用构建参数传递敏感信息
FROM python:3.9ARG DB_PASS
ENV DB_PASS=${DB_PASS}COPY requirements.txt .
RUN pip install -r requirements.txtCOPY . .
CMD ["python", "app.py"]
# 构建时传递参数
docker build --build-arg DB_PASS=my_secret -t myapp .
六、框架集成实战
1. Flask 自动加载
# 创建.flaskenv文件
FLASK_DEBUG=1
FLASK_ENV=development
# 自动生效，无需额外代码
from flask import Flask
app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = os.getenv('DATABASE_URL')
2. Django 配置优化
# settings.py
from dotenv import load_dotenv
load_dotenv()SECRET_KEY = os.getenv('SECRET_KEY')
DATABASES = {'default': {'ENGINE': 'django.db.backends.postgresql','NAME': os.getenv('DB_NAME'),'USER': os.getenv('DB_USER'),'PASSWORD': os.getenv('DB_PASS'),}
}
3. FastAPI 类型验证
from fastapi import FastAPI
from pydantic import BaseSettingsclass Settings(BaseSettings):api_key: strdebug: bool = Falseclass Config:env_file = ".env"settings = Settings()
app = FastAPI()@app.get("/")
async def root():return {"message": "Hello World", "debug": settings.debug}
七、性能优化技巧
1. Serverless 预加载
# AWS Lambda 冷启动优化
import os
from dotenv import load_dotenv# 初始化阶段加载
load_dotenv()def lambda_handler(event, context):return {"db_pass": os.getenv('DB_PASS')}
2. 缓存加速
from redis import Redis
from dotenv import load_dotenvload_dotenv()
redis = Redis(host=os.getenv('REDIS_HOST'))# 缓存敏感信息
def get_secret(key):value = redis.get(key)if not value:value = os.getenv(key)redis.set(key, value, ex=3600)return value
八、扩展应用场景
1. Jupyter Notebook 魔法指令
%load_ext dotenv
%dotenv # 自动加载.env文件
2. 命令行工具
# 直接执行命令
dotenv -f .env.prod run python manage.py migrate
3. 自动化测试
# conftest.py
import pytest@pytest.fixture(scope='session', autouse=True)
def load_test_env():from dotenv import load_dotenvload_dotenv('.env.test')
完整代码示例
# app.py
from dotenv import load_dotenv
import os# 加载配置
load_dotenv(verbose=True, override=True)# 读取配置
config = {'db_host': os.getenv('DB_HOST'),'db_port': int(os.getenv('DB_PORT', 5432)),'db_user': os.environ['DB_USER'],'db_pass': os.getenv('DB_PASS'),'debug': os.getenv('DEBUG', 'False').lower() == 'true'
}print("Configuration loaded:")
for key, value in config.items():print(f"{key}: {value}")
参考
- 官方文档
- Github
- 12-Factor 应用规范
- Python 配置管理进阶