Python dotenv使用指南之轻松管理项目环境变量

目录

• 一、为什么要使用环境变量管理？
• 二、Python dotenv 核心功能速览
• 三、5 分钟快速上手
• 1. 安装与初始化
• 2. 创建配置文件
• 3. 加载与使用
• 四、生产级实践方案
• 1. 多环境配置管理
• 2. 类型安全与验证
• 3. 安全增强方案
• ① 加密敏感信息
• ② 云原生存储
• 五、常见问题与解决方案
• 1. 变量未生效？
• 2. Flask 项目无法启动？
• 3. Docker 部署问题
• 六、框架集成实战
• 1. Flask 自动加载
• 2. Django 配置优化
• 3. FastAPI 类型验证
• 七、性能优化技巧
• 1. Serverless 预加载
• 2. 缓存加速
• 八、扩展应用场景
• 1. Jupyter Notebook 魔法指令
• 2. 命令行工具
• 3. 自动化测试
• 参考
• 总结 

很多开发者容易把自己开发的项目上传到Github上，但偶尔会忘记把数据库密码、支付接口密钥等敏感信息和谐掉，当代码提交上去时，这些信息就像裸奔一样暴露在所有人面前。更糟糕的是，不同环境（开发 / 测试 / 生产）的配置频繁切换，每次都要修改代码，效率低下且容易出错。

环境变量管理的核心价值在于：

• 安全隔离：敏感信息不进代码库，通过.env 文件独立存储
• 环境统一：开发 / 测试 / 生产环境配置一键切换
• 协作友好：团队成员共享配置模板（.env.example），各自维护敏感信息
• 12-Factor 合规：符合现代云原生应用的最佳实践

python-dotenv 是 Python 生态中管理环境变量的瑞士军刀，它能：

• 自动加载：从.env 文件读取配置并注入环境变量
• 类型安全：支持布尔值、数字等类型自动转换
• 多环境管理：通过不同的.env 文件适配开发 / 生产环境
• 框架集成：与 Flask、Django、FastAPI 等主流框架无缝协作

# 基础安装
pip install python-dotenv
# 推荐安装带CLI工具的版本
pip install "python-dotenv[cli]"

在项目根目录创建.env 文件：

# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASS=s3cr3t!   # 包含特殊字符无需引号

# 功能开关
FEATURE_NEW_LOGIN=true
API_RATE_LIMIT=100

# 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}")

# 目录结构
config/
├── .env.local      # 本地开发环境
├── .env.staging    # 预发布环境
├── .env.production # 生产环境
└── .env.example    # 配置模板（需提交到代码库）

# 根据环境变量加载不同配置
import os
from dotenv import load_dotenv

env = os.getenv('ENV', 'local')
load_dotenv(f'config/.env.{env}')

from pydantic import BaseSettings

class Settings(BaseSettings):
    api_key: str
    debug: bool = False
    rate_limit: int = 100

    class Config:
        env_file = ".env"

settings = Settings()

# 使用ansible-vault加密.env文件
ansible-vault encrypt .env.production

# 结合AWS Parameter Store
import boto3
from dotenv import dotenv_values

def 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()
}

# 强制覆盖现有环境变量
load_dotenv(override=True)

# 检查文件路径
load_dotenv('/custom/path/.env')

# 避免在项目根目录创建.env文件
project/
├── app/
│   ├── __init__.py
│   └── .env       # 正确位置
└── .env           # 错误位置

# 最佳实践：使用构建参数传递敏感信息
FROM python:3.9

ARG DB_PASS
ENV DB_PASS=${DB_PASS}

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "app.py"]

# 构建时传递参数
docker build --build-arg DB_PASS=my_secret -t myapp .

# 创建.flaskenv文件
FLASK_DEBUG=1
FLASK_ENV=development

# 自动生效，无需额外代码
from flask import Flask
app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = os.getenv('DATABASE_URL')

# 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'),
    }
}

from fastapi import FastAPI
from pydantic import BaseSettings

class Settings(BaseSettings):
    api_key: str
    debug: bool = False

    class Config:
        env_file = ".env"

settings = Settings()
app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World", "debug": settings.debug}

# AWS Lambda 冷启动优化
import os
from dotenv import load_dotenv

# 初始化阶段加载
load_dotenv()

def lambda_handler(event, context):
    return {"db_pass": os.getenv('DB_PASS')}

from redis import Redis
from dotenv import load_dotenv

load_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

%load_ext dotenv
%dotenv  # 自动加载.env文件

# 直接执行命令
dotenv -f .env.prod run python manage.py migrate

# conftest.py
import pytest

@pytest.fixture(scope='session', autouse=True)
def load_test_env():
    from dotenv import load_dotenv
    load_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 配置管理进阶

到此这篇关于Python dotenv使用指南之轻松管理项目环境变量的文章就介绍到这了,更多相关Python dotenv管理项目环境变量内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

您可能感兴趣的文章:

• 如何使用Python Dotenv库管理环境变量
• 浅析如何使用python dotenv模块管理环境变量