Python Web 项目配置管理：环境变量、.env 和生产配置怎么拆

一个 Web 项目刚开始时，配置经常只有几行：数据库地址、调试开关、密钥。项目一上线，问题就多了：开发环境要连本地数据库，测试环境要连临时库，生产环境不能把密钥写进仓库，Docker 里还要靠环境变量覆盖。

我的习惯是先把配置分成三类。

哪些配置应该进代码

稳定的业务默认值可以进代码，例如分页大小、上传文件大小限制、日志格式。它们不是秘密，也不依赖部署环境。

1
DEFAULT_PAGE_SIZE = 20
2
MAX_UPLOAD_MB = 20
3
LOG_FORMAT = "%(levelname)s %(name)s %(message)s"

这类配置改动后通常要经过代码评审，放进仓库反而更清楚。

哪些配置应该进环境变量

会随部署环境变化，或者不能泄露的值，应该从环境变量读取：

• 数据库连接地址
• Redis 地址
• JWT 密钥
• 第三方服务 token
• 是否开启 debug
• 允许访问的域名

1
from pydantic_settings import BaseSettings
2

3

4
class Settings(BaseSettings):
5
    database_url: str
6
    secret_key: str
7
    debug: bool = False
8
    allowed_hosts: list[str] = []
9

10
    class Config:
11
        env_file = ".env"
12

13

14
settings = Settings()

开发时 .env 可以存在本地，但不要提交真正的密钥。仓库里只放 .env.example，告诉自己和协作者需要哪些字段。

1
DATABASE_URL=postgresql://app:password@localhost:5432/app
2
SECRET_KEY=change-me
3
DEBUG=false
4
ALLOWED_HOSTS=localhost,127.0.0.1

开发、测试、生产怎么拆

不要在代码里写一堆 if env == "prod"。更稳妥的方式是让不同环境提供不同变量，应用只负责读取。

开发环境可以用 direnv 或 .env，可以参考 direnv 使用指南：按目录自动加载环境变量。Docker 环境可以在 Compose 里传入：

1
services:
2
  web:
3
    env_file:
4
      - .env
5
    environment:
6
      DEBUG: "false"

生产环境的密钥最好放在部署平台的变量管理里，不要写进镜像，也不要写进 Compose 文件。

一个简单检查清单

上线前我会检查这几项：

• .env 没有被提交
• .env.example 字段齐全，但没有真实密码
• DEBUG 默认是 false
• 缺少关键配置时应用直接启动失败
• 日志里不会打印完整连接串和密钥
• 本地、测试、生产使用同一套读取逻辑

总结

配置管理不需要一开始就做得很复杂。关键是边界清楚：代码里放默认行为，环境变量里放部署差异和秘密，文档里写清楚需要准备什么。后面部署、测试、迁移都会依赖这条边界。

配置稳定之后，可以继续补测试环境。FastAPI 项目可以看 FastAPI 项目测试指南：pytest、TestClient、依赖覆盖怎么用，Django 项目可以看 Django 测试入门：Model、View、API 测试怎么写。