INI 配置文件格式化实战：分节、等号对齐与校验

我接手过一个跑了三年的 PHP 服务，第一次打开它的 php.ini，两百多行，key 缩进有的两个空格有的四个，注释东一句西一句，等号两边的空格毫无章法。想找 memory_limit 到底设成多少，得用编辑器搜半天。INI 这种格式的麻烦不在于难，而在于太宽松：怎么写它都认，于是每个人都按自己的习惯写，时间一长就成了一锅粥。把它重新格式化一遍，是让老配置重新可读的第一步。

INI 到底由哪几块组成

一个 INI 文件其实只有三种东西：section 头、key=value 对、注释。section 头就是方括号里的名字，比如 [mysqld]、[server]，它把下面的若干 key 归成一组。在第一个 section 头出现之前的那些 key，属于隐式的根 section。每个 key=value 就是一条配置，等号左边是 key，右边是值。注释用 ; 或 # 开头，可以独占一行，也可以跟在某条 key 的行尾。

举个最小的例子：

[database]
host = localhost
port = 5432  ; 默认端口

这里 [database] 是 section，host 和 port 是两个 key，行尾那句 ; 默认端口 是跟随注释。理解了这个三段式结构，格式化要做的事情就清楚了：把同一个 section 内的等号对齐成一列，可选地按字典序重排 section 头，同时把注释一个不漏地留在原来的位置。

等号对齐：让配置读起来像一张表

格式化最直观的收益是等号对齐。它的规则是在每个 section 内部，找出最长的那个 key，然后把所有等号推到同一列。section 之间各自对齐，不会因为另一个 section 里有个超长的 key 就把整个文件撑歪。

下面是一段对齐前的 INI：

[server]
host=0.0.0.0
port = 8080
max_connections=200
read_timeout = 30  ; 秒

打开等号对齐后，它变成：

[server]
host            = 0.0.0.0
port            = 8080
max_connections = 200
read_timeout    = 30  ; 秒

四个 key 的等号落在同一列，行尾那句注释也被推到对齐后的值之后，注释那一列照样整齐。审查这段配置的人扫一眼列就能读完，而不用在长短不一的行里来回找等号。需要注意的是，对齐只管外观，它不会帮你合并两个同名 key，也不会提醒重复，那是校验该做的事。

校验：把重复 key 和未闭合 section 揪出来

INI 的另一个坑是同名 key。MySQL 的 my.cnf 允许 max_connections 写两遍，服务器只认最后一个，前面那个被悄悄丢掉。这种问题肉眼很难发现，尤其文件长的时候。校验模式会在同一个 section 内扫出重复 key，并报出精确行号，比如告诉你第 47 行的 max_connections 和前面那个冲突，你直接删掉过期的那条，而不是靠猜服务器加载了哪个值。未闭合的 [section 缺右方括号这类语法错，也会被一并标出行号。

Windows 配置、php.ini 与 git config

INI 的生命力在于它无处不在。Windows 的 .ini、PHP 的 php.ini、MySQL 的 my.cnf、Python 的 setup.cfg、systemd 的 unit 文件，绝大多数都是 INI 或类 INI 的写法。它们之间有个小差异值得留意：; 是 INI 最早的注释符，多见于 Windows 配置和 my.cnf；# 是 Unix 风格配置带进来的，systemd unit 和 configparser 常用。混着用很常见，格式化时该保留哪个就保留哪个，免得下游只认一种风格的解析器被打乱。

git config 是个特例。它长得像 INI，但用了 [remote "origin"] 这种 subsection 语法。格式化时可以把整串当作一个字面叫 remote "origin" 的 section 头原样保留，Format 和压缩都不会破坏 .gitconfig。但要小心：别给 git config 开 section 排序，因为它是按整串头字符串排的，[remote "origin"] 可能被排到离 [remote "fork"] 很远的地方，subsection 的父子归属会乱。复杂的 .gitconfig 还是用 git config --file=... 最稳。

和 TOML 的区别：别拿这个当 TOML 用

很多人会问，既然有 TOML，为什么还碰 INI。对全新的、自己掌控的项目，TOML 确实更好，类型更丰富，数组、嵌套表、整数布尔都有明确规范。INI 的价值不在于先进，而在于你躲不开它：你接手的那个老服务的配置就是 INI，你没得选。所以这类格式化工具是为"读懂手里这个文件"准备的，不是劝你新项目改写 INI。

也正因如此，不要把 TOML 文件粘进 INI 格式化器指望按类型对齐。INI 工具把 port = 5432 当成纯字符串对，不会理解它是整数，[table.sub] 这种嵌套表和数组它也不认。真要处理 TOML，请用 TOML 专用工具。

顺手的姊妹工具

把 INI 整理干净之后，配置链路上的其他文件往往也想顺手过一遍。如果你的项目里还有一堆 JSON 配置或接口返回需要格式化，JSON 格式化工具同样在浏览器本地跑，缩进和键值一目了然。需要专门处理 INI 的分节、等号对齐和重复 key 校验，直接用 INI 格式化与校验工具，粘贴、点格式化、复制，全程不上传，配置里的连接串和密钥都不会离开标签页。

整理老配置这件事没什么技术含量，但回报很实在：一个能读的 php.ini 或 my.cnf，往往就是少一次凌晨两点被坑的前提。

Made by Toolora · Updated 2026-06-13