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；上云用环境变量。不要把敏感信息写在代码里！