常用配置文件总览与选型指南

配置文件把“程序怎样运行”从代码中分离出来：端口、功能开关、连接参数和工具选项可以独立调整，而不必为了每次环境变化重新修改代码。真正困难的往往不是把键和值写进文件，而是选择一种与数据结构、维护者和运行环境相匹配的格式。

本系列使用同一组应用配置，对比 JSON、INI、YAML、XML、TOML、.env 和 Properties。重点不是评出唯一的“最佳格式”，而是理解每种格式的边界，并在可读性、类型能力、兼容性和工具生态之间做出合适取舍。

一、先分清配置、数据与环境变量

JSON、YAML 和 XML 同时也是数据交换格式；TOML 更明确地面向配置；INI、.env 与 Properties 则偏向简单键值设置。文件扩展名只说明语法，真正的行为仍由读取它的程序决定，例如默认值、覆盖顺序、变量插值、重复键处理和类型转换。

配置文件也不等于秘密仓库。密码、令牌和私钥应由环境变量或专门的秘密管理系统注入；即使必须落盘，也应限制权限、避免提交到版本库，并制定轮换方法。

二、七种常见格式对比

格式及专题链接	常见扩展名	注释	类型与层级	主要优势	主要限制	推荐场景
JSON	`.json`	标准 JSON 不支持	对象、数组及基础类型，层级清晰	语法严格、跨语言支持广、适合机器生成	人工维护时缺少注释，尾逗号无效	API、工具配置、需要与程序数据结构直接映射的场景
INI	`.ini`、`.cfg`、`.conf`	常见 `;` 或 `#`，以解析器为准	section 加字符串键值，层级较浅	简单直观、手工编辑成本低	没有统一方言，复杂结构表达弱	桌面程序、传统软件、少量分组设置
YAML	`.yaml`、`.yml`	`#`	映射、序列、标量，可深层嵌套	可读性强、注释友好、适合大型声明式配置	缩进敏感，版本和类型解析差异容易踩坑	CI/CD、容器编排、基础设施与运维配置
XML	`.xml`	`<!-- -->`	元素、属性和文本组成树	命名空间、Schema、验证和成熟工具链完善	冗长，简单配置也需要较多标记	企业系统、标准协议、强验证或既有 XML 生态
TOML	`.toml`	`#`	键值、表、数组和明确类型	面向配置设计，语义清楚，人工编辑友好	深层或高度重复数据不如 YAML 灵活	项目元数据、开发工具、应用程序配置
`.env`	`.env`、`.env.local` 等	常见 `#`，以工具为准	扁平字符串键值	与环境变量衔接直接，部署时覆盖方便	没有统一规范，不擅长层级和复杂类型	本地开发、容器启动、按部署变化的少量参数
Properties	`.properties`	`#` 或 `!`	扁平字符串键值，常用点号模拟分组	Java 生态原生、格式稳定、工具支持成熟	类型和层级需应用自行解释，编码 API 有差异	Java 应用、框架配置、资源与兼容性要求较高的项目

表中的“支持注释”只表示语法通常能保存说明文字，并不保证解析后再次写回时仍保留原注释和排版。

三、贯穿系列的配置模型

每篇专题都表达下面这组逻辑设置：

app.name = "config-demo"
app.debug = false
server.host = "127.0.0.1"
server.port = 8080
app.features = ["search", "cache"]
database.pool_size = 10

它包含字符串、布尔值、整数、列表和分组。JSON、YAML、XML 与 TOML 可以直接表达树形结构；INI 通常用 section 分组；.env 和 Properties 则把层级压平为命名约定，并把列表编码为普通字符串。正是这些差异，决定了格式是否适合长期维护。

四、按需求快速选择

配置主要由程序生成或通过 API 交换：优先考虑 JSON。它严格、通用，但不要期待在标准 JSON 中写注释。
配置由人频繁维护，而且层级较深：优先比较 YAML 与 TOML。YAML 表达力更强；TOML 的类型和边界更明确。
只有少量分组键值，并要兼容传统工具：INI 通常已经足够，前提是先确认具体解析器规则。
需要命名空间、Schema 或与既有企业标准互通：XML 的冗长往往换来了更强的验证与工具能力。
参数主要随部署环境变化：使用真实环境变量；.env 更适合在本地或受控启动流程中把文件内容加载为环境变量。
项目位于 Java 生态：如果框架已经约定 Properties，就没有必要仅为“现代感”更换格式；复杂新配置再评估 YAML 或 TOML。

如果一个项目需要同时使用多种来源，应把优先级写进文档，例如“内置默认值 < 配置文件 < 环境变量 < 命令行参数”。这只是常见设计，不是所有工具的通用规则；实际顺序必须由应用明确实现和测试。

五、比较时不要只看语法长短

选型时至少检查以下问题：

谁来维护：开发者、运维人员、最终用户，还是自动化程序？
结构有多复杂：只有十几个键，还是包含深层对象和重复列表？
是否需要注释：注释是临时提示，还是配置契约的一部分？
是否需要明确类型：字符串 "false" 与布尔值 false 混淆会不会造成故障？
是否需要校验：能否在启动前发现未知字段、拼写错误和越界值？
生态是否已有约定：优先遵循工具原生格式，通常比自行转换更可靠。
变更是否容易审查：稳定排序、清晰分组和较小的差异比追求最短文本更重要。

格式本身不能替代配置模型。无论选哪一种，都应定义必填项、默认值、允许范围、弃用策略和失败行为，并在程序启动时给出清楚的错误信息。

六、共同的可靠性与安全原则

对不受信任的配置设置文件大小、嵌套深度和解析时间限制。
不依赖重复键；不同解析器可能报错、保留第一个值或让最后一个值覆盖前面的值。
固定字符编码，现代项目通常统一使用 UTF-8，并明确换行与大小写规则。
加载 YAML 时使用安全模式；解析 XML 时默认禁用外部实体和不必要的 DTD。
不把生产密码、访问令牌或私钥直接写进示例和版本库；提交无秘密的 .env.example 或配置模板即可。
在升级解析库、格式版本或工具链后，用真实配置样本做回归测试，而不是只检查文件能否打开。

七、推荐阅读顺序

第一次系统了解时，可以依次阅读 JSON、INI、YAML、XML、TOML，再看 .env 与 Properties。前五篇建立结构化配置的比较框架，后两篇帮助理解“扁平字符串设置”为什么简单，却更依赖应用约定。

如果已经面临具体选型，也可以直接跳到相应专题，再回到本页核对相近格式。

八、主要规范与资料

下一篇：JSON 配置文件：严格、通用的结构化格式