前言

几乎所有 Python 程序都离不开配置：接口地址、数据库账号、超时时间、开关变量、业务参数……很多新手随手写一个全局字典硬编码在代码里，上线改参数就要重新发布，维护极其痛苦。

市面上主流 Python 配置方案有五种：.py 原生配置、.json、.ini、.yaml(yml)、.toml。每种格式语法、可读性、数据支持、使用场景完全不同，本文结合实战场景拆解优缺点，给出明确选型建议。

一、五种主流配置文件介绍与代码示例

1. 原生 .py 配置文件（settings.py / config.py）

原理

直接用 Python 脚本定义变量、字典、类，导入即可使用，无需第三方库，Python 原生支持。

示例 config.py

# 数据库配置
DB_CONFIG = {
    "host": "127.0.0.1",
    "port": 3306,
    "user": "root",
    "password": "123456",
    "pool_size": 20
}

# 服务开关
DEBUG = True
TIMEOUT = 30

# 列表配置
WHITE_LIST = ["admin", "user01", "test"]

使用方式

from config import DB_CONFIG, DEBUG

print(DB_CONFIG["host"])

优点

1. 零依赖，不用安装任何第三方库；
2. 支持所有 Python 数据类型：函数、对象、布尔、注释、运算表达式；
3. 语法灵活，可写逻辑判断、环境区分。

缺点

1. 非开发人员看不懂，运维改配置容易语法报错；
2. 纯文本编辑无法校验格式，写错缩进直接程序崩溃；
3. 配置与代码耦合，无法单独分发配置文件。

适用场景

Django/Flask Web 项目、纯 Python 后台服务、需要动态计算配置的场景。

2. JSON 配置文件（.json / .txt）

原理

JSON 是通用序列化格式，json 标准库内置解析，前文提到的时间戳命名保存字典就是该方案。

示例 config.json

{
  "db": {
    "host": "127.0.0.1",
    "port": 3306,
    "password": "123456"
  },
  "debug": true,
  "timeout": 30,
  "white_list": ["admin", "test"]
}

读取代码

import json

with open("config.json", "r", encoding="utf-8") as f:
    cfg = json.load(f)

print(cfg["db"]["host"])

写入（时间戳命名txt存储）

import json
import time

data = {"code": 200, "msg": "配置备份"}
filename = f"{int(time.time())}.txt"
with open(filename, "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=4)

优点

1. 跨语言通用，前端、Java、Go 都能读取；
2. Python 内置库，无需额外安装；
3. 结构清晰，嵌套层级友好。

缺点

1. 不支持注释，无法备注参数含义；
2. 不能尾随逗号，语法严格，少一个符号直接解析失败；
3. 不支持日期、特殊数值，只能基础类型。

适用场景

前后端交互配置、接口返回数据存储、简单静态配置备份。

3. INI 配置文件（.ini）

原理

传统分段配置格式，Python 内置 configparser 解析，结构简单，适合扁平配置。

示例 config.ini

[database]
host = 127.0.0.1
port = 3306
user = root

[server]
debug = true
timeout = 30

读取代码

import configparser

cfg = configparser.ConfigParser()
cfg.read("config.ini", encoding="utf-8")

host = cfg.get("database", "host")
port = cfg.getint("database", "port")

优点

1. 极简轻量，可读性高，运维人员极易上手；
2. 内置库，无第三方依赖；
3. 支持分段分组，逻辑清晰。

缺点

1. 不支持多层嵌套，只能一级分组；
2. 所有值默认字符串，数字、布尔需要手动转换；
3. 不支持列表、数组结构。

适用场景

小型脚本、工具类程序、数据库连接简易配置。

4. YAML 配置文件（.yaml / .yml）

原理

缩进式配置语言，可读性极强，需要安装 pyyaml，目前爬虫、AI、容器项目大量使用。

安装

pip install pyyaml

示例 config.yaml

database:
  host: 127.0.0.1
  port: 3306
  password: "123456"
server:
  debug: true
  timeout: 30
white_list:
  - admin
  - test
# 这里是注释，方便说明参数

读取代码

import yaml

with open("config.yaml", "r", encoding="utf-8") as f:
    cfg = yaml.safe_load(f)

print(cfg["database"]["host"])

优点

1. 支持注释、多层嵌套、列表、布尔、日期；
2. 语法极简，无多余括号，阅读体验最好；
3. 生态完善，Docker、K8s、LLM 项目标配。

缺点

1. 依赖第三方库；
2. 对缩进极其敏感，空格错位直接解析失败；
3. 复杂大文件解析性能略低于 JSON。

适用场景

AI 大模型项目、爬虫、容器服务、复杂多层级业务配置。

5. TOML 配置文件（.toml）

原理

现代化配置标准，Python 官方推荐（Pip、Poetry、Pydantic 全部使用），兼顾 ini 简洁与 json 嵌套。

安装

pip install tomli

示例 config.toml

[database]
host = "127.0.0.1"
port = 3306
password = "123456"

[server]
debug = true
timeout = 30

[[white_list]]
name = "admin"
[[white_list]]
name = "test"

读取代码

import tomli

with open("config.toml", "rb") as f:
    cfg = tomli.load(f)

print(cfg["database"]["host"])

优点

1. 语法严谨，不易写错，同时支持注释；
2. 原生支持数字、布尔、数组、多层表格；
3. Python 官方工具链标准，项目规范度高。

缺点

1. 需要第三方库；
2. 小众，部分运维人员不熟悉语法。

适用场景

包管理工具、规范化开源 Python 项目、Pydantic 类型校验配置。

二、核心维度对比表

配置格式	内置库	支持注释	多层嵌套	数组列表	上手难度	跨语言	推荐场景
.py	✅	✅	✅	✅	高	❌	Web框架、动态配置
.json	✅	❌	✅	✅	低	✅	数据备份、前后端交互
.ini	✅	✅	❌	❌	极低	✅	小型工具、扁平配置
.yaml	❌	✅	✅	✅	中	✅	AI、爬虫、容器项目
.toml	❌	✅	✅	✅	中	✅	规范开源项目、工具链

三、分场景选型建议

场景1：小型单机脚本、工具，不想装第三方库

优先选：.ini 或 .py

• 简单参数用 ini，运维可直接修改；
• 需要简单逻辑计算用 config.py。

场景2：配置需要前后端互通、数据备份存储（时间戳txt保存）

优先选：.json
无额外依赖，序列化便捷，适合前文字典持久化需求。

场景3：AI大模型、爬虫、多服务复杂多层配置

优先选：.yaml
注释清晰，嵌套直观，行业通用标准。

场景4：开源项目、包管理、规范化工程（Poetry/Pydantic）

优先选：.toml
Python 官方生态标准，格式统一规范。

场景5：Django/Flask 大型Web后台，需要动态判断配置

优先选：.py
原生支持逻辑分支、环境区分、函数变量。

四、避坑总结

1. 不要硬编码配置在业务代码，统一抽离配置文件；
2. 密码、密钥等敏感配置禁止提交代码仓库，搭配环境变量使用；
3. JSON 无注释，业务参数多、需要备注时不要选用；
4. INI 无法嵌套多层，复杂业务配置直接放弃；
5. 生产环境推荐 YAML / TOML，兼顾可读性与扩展性。

结尾

配置文件是项目工程化的基础，选对格式能大幅降低后期维护成本。简单存储备份用 JSON，复杂业务配置用 YAML，规范开源项目用 TOML，轻量小脚本用 INI，Web 服务动态配置直接使用 py 文件。根据自身项目规模、使用人群、部署场景匹配对应方案，才能写出易维护、易扩展的 Python 工程。