Python项目中六大常见的配置文件管理方式详解

在 Python 项目中，配置文件是将代码与配置分离的重要手段。常见方式有以下几种，从简单到正式分别是：

一、配置方式

二、各方式介绍

方式 1：硬编码（不推荐）

# config.py
DB_HOST = "localhost"
DB_PORT = 5432
API_KEY = "sk-123456"  # 敏感信息暴露在代码里

问题在哪？ 敏感信息直接摊在代码里，换环境就得改代码，配置和代码耦合得死死的。除非你只是写个临时脚本跑完就扔，任何正式项目都不应该用这种方式。

方式 2：.env 文件（最常用的轻量方案）

# .env 文件
DB_HOST=localhost
DB_PORT=5432
API_KEY=sk-123456
DEBUG=true

# 加载配置
from dotenv import load_dotenv
import os

load_dotenv()
db_host = os.getenv("DB_HOST", "localhost")
api_key = os.getenv("API_KEY")

优点很明显：敏感信息不进代码（把 .env 加入 .gitignore 就安全了），环境切换只需要改一个文件，配合 python-dotenv 使用非常轻量。不过它只能处理字符串，需要手动转换类型，也不支持复杂嵌套结构（比如对象、列表）。

方式 3：config.py 模块（Python 代码配置）

# config.py
import os

class Config:
    SECRET_KEY = os.environ.get('SECRET_KEY') or 'dev-secret'
    DEBUG = False
    TESTING = False

class DevelopmentConfig(Config):
    DEBUG = True
    DB_URL = 'sqlite:///dev.db'

class ProductionConfig(Config):
    DB_URL = os.environ.get('DATABASE_URL')

# 根据环境选择配置
config = {
    'development': DevelopmentConfig,
    'production': ProductionConfig,
    'default': DevelopmentConfig
}

# 使用
from config import config
cfg = config[os.getenv('ENV', 'default')]()
print(cfg.DB_URL)

这种方式很灵活，可以用 Python 逻辑做继承、条件判断，适合中小型项目。但代价是配置和代码混在一起，修改配置得改 Python 文件。

方式 4：JSON / YAML（结构化配置）

# config.yaml
database:
  host: localhost
  port: 5432
  name: mydb
api:
  key: sk-123456
  timeout: 30
logging:
  level: INFO
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

import yaml
import json

# 读取 YAML
with open('config.yaml', 'r') as f:
    config = yaml.safe_load(f)

print(config['database']['host'])  # localhost

结构清晰，支持嵌套，跨语言通用，适合复杂配置。不过需要额外库（比如 pyyaml），而且 JSON 不支持注释，YAML 支持也有限。

方式 5：TOML（Python 项目官方推荐）

# pyproject.toml
[project]
name = "myapp"
version = "0.1.0"
description = "My Python application"
[tool.myaapp.database]
host = "localhost"
port = 5432
[tool.myaapp.api]
key = "sk-123456"
timeout = 30

import tomllib  # Python 3.11+ 内置

with open('pyproject.toml', 'rb') as f:
    config = tomllib.load(f)

db_host = config['tool']['myapp']['database']['host']

Python 官方推荐（PEP 518/621），支持注释，结构清晰，3.11+ 内置支持。旧版本需要 tomli 库，另外表达力不如 YAML 那么强。

方式 6：系统环境变量（云原生/容器）

# 在 shell 中设置
export DB_HOST=localhost
export DB_PORT=5432
export API_KEY=sk-123456

# Docker 中设置
docker run -e DB_HOST=localhost -e API_KEY=sk-123456 myapp

import os

db_host = os.environ.get('DB_HOST')

标准化，遵循 12-Factor App 规范，适合容器和云部署，敏感信息不暴露在文件里。但只能处理字符串，大量配置时管理起来会比较麻烦。

说到底，小项目 .env 就够了；项目大了用 config.yaml；正式 Python 项目用 pyproject.toml；上云用环境变量。记住：不要把敏感信息写在代码里。