前言几乎所有 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}# 服务开关DEBUGTrueTIMEOUT30# 列表配置WHITE_LIST[admin,user01,test]使用方式fromconfigimportDB_CONFIG,DEBUGprint(DB_CONFIG[host])优点零依赖不用安装任何第三方库支持所有 Python 数据类型函数、对象、布尔、注释、运算表达式语法灵活可写逻辑判断、环境区分。缺点非开发人员看不懂运维改配置容易语法报错纯文本编辑无法校验格式写错缩进直接程序崩溃配置与代码耦合无法单独分发配置文件。适用场景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]}读取代码importjsonwithopen(config.json,r,encodingutf-8)asf:cfgjson.load(f)print(cfg[db][host])写入时间戳命名txt存储importjsonimporttime data{code:200,msg:配置备份}filenamef{int(time.time())}.txtwithopen(filename,w,encodingutf-8)asf:json.dump(data,f,ensure_asciiFalse,indent4)优点跨语言通用前端、Java、Go 都能读取Python 内置库无需额外安装结构清晰嵌套层级友好。缺点不支持注释无法备注参数含义不能尾随逗号语法严格少一个符号直接解析失败不支持日期、特殊数值只能基础类型。适用场景前后端交互配置、接口返回数据存储、简单静态配置备份。3. INI 配置文件.ini原理传统分段配置格式Python 内置configparser解析结构简单适合扁平配置。示例 config.ini[database] host 127.0.0.1 port 3306 user root [server] debug true timeout 30读取代码importconfigparser cfgconfigparser.ConfigParser()cfg.read(config.ini,encodingutf-8)hostcfg.get(database,host)portcfg.getint(database,port)优点极简轻量可读性高运维人员极易上手内置库无第三方依赖支持分段分组逻辑清晰。缺点不支持多层嵌套只能一级分组所有值默认字符串数字、布尔需要手动转换不支持列表、数组结构。适用场景小型脚本、工具类程序、数据库连接简易配置。4. YAML 配置文件.yaml / .yml原理缩进式配置语言可读性极强需要安装pyyaml目前爬虫、AI、容器项目大量使用。安装pipinstallpyyaml示例 config.yamldatabase:host:127.0.0.1port:3306password:123456server:debug:truetimeout:30white_list:-admin-test# 这里是注释方便说明参数读取代码importyamlwithopen(config.yaml,r,encodingutf-8)asf:cfgyaml.safe_load(f)print(cfg[database][host])优点支持注释、多层嵌套、列表、布尔、日期语法极简无多余括号阅读体验最好生态完善Docker、K8s、LLM 项目标配。缺点依赖第三方库对缩进极其敏感空格错位直接解析失败复杂大文件解析性能略低于 JSON。适用场景AI 大模型项目、爬虫、容器服务、复杂多层级业务配置。5. TOML 配置文件.toml原理现代化配置标准Python 官方推荐Pip、Poetry、Pydantic 全部使用兼顾 ini 简洁与 json 嵌套。安装pipinstalltomli示例 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读取代码importtomliwithopen(config.toml,rb)asf:cfgtomli.load(f)print(cfg[database][host])优点语法严谨不易写错同时支持注释原生支持数字、布尔、数组、多层表格Python 官方工具链标准项目规范度高。缺点需要第三方库小众部分运维人员不熟悉语法。适用场景包管理工具、规范化开源 Python 项目、Pydantic 类型校验配置。二、核心维度对比表配置格式内置库支持注释多层嵌套数组列表上手难度跨语言推荐场景.py✅✅✅✅高❌Web框架、动态配置.json✅❌✅✅低✅数据备份、前后端交互.ini✅✅❌❌极低✅小型工具、扁平配置.yaml❌✅✅✅中✅AI、爬虫、容器项目.toml❌✅✅✅中✅规范开源项目、工具链三、分场景选型建议场景1小型单机脚本、工具不想装第三方库优先选.ini或.py简单参数用 ini运维可直接修改需要简单逻辑计算用 config.py。场景2配置需要前后端互通、数据备份存储时间戳txt保存优先选.json无额外依赖序列化便捷适合前文字典持久化需求。场景3AI大模型、爬虫、多服务复杂多层配置优先选.yaml注释清晰嵌套直观行业通用标准。场景4开源项目、包管理、规范化工程Poetry/Pydantic优先选.tomlPython 官方生态标准格式统一规范。场景5Django/Flask 大型Web后台需要动态判断配置优先选.py原生支持逻辑分支、环境区分、函数变量。四、避坑总结不要硬编码配置在业务代码统一抽离配置文件密码、密钥等敏感配置禁止提交代码仓库搭配环境变量使用JSON 无注释业务参数多、需要备注时不要选用INI 无法嵌套多层复杂业务配置直接放弃生产环境推荐 YAML / TOML兼顾可读性与扩展性。结尾配置文件是项目工程化的基础选对格式能大幅降低后期维护成本。简单存储备份用 JSON复杂业务配置用 YAML规范开源项目用 TOML轻量小脚本用 INIWeb 服务动态配置直接使用 py 文件。根据自身项目规模、使用人群、部署场景匹配对应方案才能写出易维护、易扩展的 Python 工程。
