Python配置文件管理：6种实用方案对比与最佳实践

脚本专家

在Python项目中，将配置从代码中分离是工程化的基本要求。本文梳理了六种主流的配置文件管理方式，从临时脚本到云原生场景，逐一分析实现、优缺点和适用场景，并给出选择建议。

2. # config.py - 不推荐的硬编码方式
3. DB_HOST = "localhost"
4. DB_PORT = 5432
5. API_KEY = "sk-123456"

复制代码

硬编码是最直接但最不可取的方式。敏感信息（如API密钥）直接暴露在代码库中，不同环境需要手动修改代码，配置与代码耦合严重。仅用于学习或一次性脚本，任何正式项目都应避免。

二、.env文件（轻量级环境变量管理）

dotenv方案是目前最流行的轻量配置方式。在项目根目录创建.env文件，内容为KEY=VALUE格式：

2. .env
3. DB_HOST=localhost
4. DB_PORT=5432
5. API_KEY=sk-123456
6. DEBUG=true

复制代码

加载时借助python-dotenv库：

2. from dotenv import load_dotenv
3. import os
4. load_dotenv()
5. db_host = os.getenv("DB_HOST", "localhost")
6. api_key = os.getenv("API_KEY")

复制代码

优点：敏感信息不进入代码库（.env加入.gitignore），切换环境只需替换文件。缺点：只能读取字符串，需手动转换类型；不支持嵌套结构。适合需要快速分离配置的中小型项目。

三、config.py模块（Python代码配置）

利用Python的类继承与条件逻辑生成配置，常见于Flask、Django等框架：

2. # config.py
3. import os
5. class Config:
6.     SECRET_KEY = os.environ.get('SECRET_KEY') or 'dev-secret'
7.     DEBUG = False
8.     TESTING = False
10. class DevelopmentConfig(Config):
11.     DEBUG = True
12.     DB_URL = 'sqlite:///dev.db'
14. class ProductionConfig(Config):
15.     DB_URL = os.environ.get('DATABASE_URL')
17. config = {
18.     'development': DevelopmentConfig,
19.     'production': ProductionConfig,
20.     'default': DevelopmentConfig
21. }

复制代码

使用：

2. from config import config
3. cfg = config[os.getenv('ENV', 'default')]()
4. print(cfg.DB_URL)

复制代码

优点：完整利用Python语法——继承、条件判断、动态计算。缺点：配置与代码混合，修改配置仍需修改Python文件。适合中小型项目，尤其是已有框架风格的项目。

四、JSON / YAML（结构化配置）

对于多层嵌套的复杂配置（如日志格式、多数据库源），JSON或YAML文件更为清晰：

2. config.yaml
3. database:
4.   host: localhost
5.   port: 5432
6.   name: mydb
7. api:
8.   key: sk-123456
9.   timeout: 30
10. logging:
11.   level: INFO
12.   format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

复制代码

读取：

2. import yaml
3. with open('config.yaml', 'r') as f:
4.     config = yaml.safe_load(f)
5. print(config['database']['host'])  # localhost

复制代码

优点：结构清晰、跨语言通用、易于人工编辑。缺点：JSON不支持注释；YAML需要额外安装pyyaml库，且语法敏感。适合配置项多、层级深的项目。

五、TOML（Python官方推荐格式）

PEP 518/621将TOML定为项目元数据标准格式（pyproject.toml）。它支持注释和表结构，Python 3.11+内置tomllib模块：

2. pyproject.toml
3. [project]
4. name = "myapp"
5. version = "0.1.0"
7. [tool.myapp.database]
8. host = "localhost"
9. port = 5432
11. [tool.myapp.api]
12. key = "sk-123456"
13. timeout = 30

复制代码

读取：

2. import tomllib  # Python 3.11+
3. with open('pyproject.toml', 'rb') as f:
4.     config = tomllib.load(f)
5. db_host = config['tool']['myapp']['database']['host']

复制代码

Python 3.10及以下版本需安装tomli库。优点：注释友好、结构规范、官方背书。缺点：表达能力不如YAML，不适合极复杂嵌套。推荐用于Python包配置及与打包工具集成的场景。

六、系统环境变量（云原生/容器标准）

遵循12-Factor App建议，将配置存储于操作系统环境变量中：

2. # Shell设置
3. export DB_HOST=localhost
4. export DB_PORT=5432
5. export API_KEY=sk-123456
7. # Docker运行时传递
8. docker run -e DB_HOST=localhost -e API_KEY=sk-123456 myapp

复制代码

代码读取：

2. import os
3. db_host = os.environ.get('DB_HOST')

复制代码

优点：与代码彻底分离，敏感信息不落盘，容器化部署最自然。缺点：无法处理结构化数据（字符串之外需自行解析），大量配置时管理困难。适合微服务、Kubernetes等云原生环境。

总结与选择建议

- 临时脚本或快速原型：直接用硬编码，但后续务必替换。
- 简单项目，需分离敏感信息：.env + python-dotenv 最轻量。
- 配置有逻辑依赖（如环境切换）：config.py模块最灵活。
- 配置复杂，多人维护：YAML（支持注释）。
- Python包或项目元数据：pyproject.toml（TOML）。
- 云部署、CI/CD：系统环境变量。

核心原则：永远不要在代码中硬编码敏感信息。根据团队规模和部署方式，选择最合适的方案即可。

热心网友4

感谢分享，总结得非常全面。我平时在小项目中习惯用`.env`加`python-dotenv`，确实轻量又安全；后来转到微服务后基本都交给环境变量和K8s ConfigMap了。不过对于TOML方案我一直有点犹豫——虽然官方推荐，但感觉社区里实际的配置文件还是YAML更多，想听听你对这个趋势的看法？另外，如果配置里包含密码或密钥，除了环境变量外，楼主有没有推荐的加密存储方案？

热心网友4

非常感谢分享！总结得非常全面，从最基础的硬编码到云原生的环境变量，覆盖了不同规模和场景的需求。 我自己在用中小型项目时，通常根据情况在 .env 和 config.py 模块之间选。看到你提到 TOML 是 Python 官方推荐格式，确实值得多关注，尤其是和 pyproject.toml 集成时很优雅。 另外想问一下，在 YAML 方案里，有没有遇到因为缩进问题导致解析出错的坑？你通常怎么避免？

热心网友4

感谢分享，这篇对比很全面，从轻量到云原生都覆盖了。我自己在项目中常用.env加config.py结合的方式，用.env存敏感变量，config.py里做类型转换和默认值——既避免了硬编码，又处理了dotenv只能读字符串的问题。另外TOML那部分提到Python 3.11内置tomllib确实方便，现在新项目直接用pyproject.toml打包配置一步到位。对于日志这类多层结构，我还是偏好yaml，可读性高。楼主对安全方面有没有额外建议？比如.env文件权限设置或者加密敏感字段？