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

2026-07-10 09:13:22 作者：梦想不只是梦与想

本指南对比了Python项目中配置文件管理方式的6种主流方法,从硬编码到云原生环境变量,帮你快速掌握.env、YAML、TOML等核心配置方式的优缺点,点击了解如何根据项目规模选择最佳策略,彻底告别敏感信息泄露风险

一、配置方式

方式	格式	适用场景	特点
硬编码	Python 代码	极简/临时脚本	最不灵活
`.env` 文件	`KEY=VALUE`	环境变量、敏感信息	轻量，适合敏感信息
`config.py` 模块	Python 代码	中小型项目	灵活，可用Python逻辑
JSON / YAML	`.json` / `.yaml`	复杂配置结构	结构清晰，通用
TOML	`.toml`	项目元数据	Python 官方推荐（`pyproject.toml`）
系统环境变量	OS 级别	容器/云原生	标准化，适合云部署

二、各方式介绍

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

到此这篇关于Python项目中六大常见的配置文件管理方式详解的文章就介绍到这了,更多相关Python配置文件管理内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！