PHP 8.5 的 --ini=diff 怎么用：只看偏离内置默认值的配置

同一套 PHP 应用在开发机正常、进入测试容器后报错，团队往往先怀疑代码，最后才发现是 memory_limit、display_errors、扩展配置或上传限制不同。过去用 php -i 核对配置会得到一大屏结果；PHP 8.5 新增的 --ini=diff，专门把“当前值与 PHP 内置默认值不同”的 INI 项筛出来，更适合发布前做配置审计。

--ini=diff 不是比较两个 php.ini 文件，也不会判断哪套配置更正确。它回答的是：当前 CLI 进程最终生效的配置中，哪些值偏离了这次 PHP 构建的内置默认值。

PHP 8.5 新增了什么

PHP 8.5 官方迁移指南在 CLI 变更中加入了 --ini=diff：它用于打印相对内置默认值发生改变的 INI 设置。最直接的调用方式是：

php --ini=diff

这项能力的价值不在于替代配置文件，而在于缩小排查范围。对于一个启用了多个 conf.d 文件、又可能通过命令行 -d 临时覆盖配置的容器，最终生效值可能并不等于主 php.ini 中看到的值。

PHP 8.5 已在 2025 年 11 月发布，官方发布页将它列为新的次要版本；当前升级项目可以把 --ini=diff 纳入环境验收脚本，但不应在仍运行 PHP 8.4 或更早版本的机器上假定该参数存在。

先分清三个命令各自回答什么

配置问题经常混在一起，是因为三个命令看起来都与 INI 有关：

• php --ini：查看加载了哪个主配置文件，以及扫描了哪些附加 INI 文件；
• php -i：查看大量运行信息和当前配置，信息完整但噪声也多；
• php --ini=diff：只列出最终值中偏离内置默认值的配置项，适合做差异审计。

因此，排查顺序通常不是三选一。先用 php --ini 确认配置来源，再用 php --ini=diff 缩小范围；只有需要完整上下文、模块信息或某个未出现在差异列表中的值时，再查询 php -i。

把三套环境采集成可比较快照

假设订单服务在开发、测试和生产环境使用相同代码，却只有测试环境上传失败。不要直接复制整份 php.ini，可以先在每套环境执行同样的采集：

php -v
php --ini
php --ini=diff

第一行固定 PHP 版本与构建背景，第二行固定配置文件来源，第三行记录偏离默认值的最终结果。保存时给文件名带上环境和采集时间，例如：

dev-php85-ini-diff.txt
staging-php85-ini-diff.txt
prod-php85-ini-diff.txt

随后进入归类复核，先比较与故障相关的配置族。上传问题优先看 upload_max_filesize、post_max_size、max_file_uploads 和临时目录；内存问题优先看 memory_limit；错误展示差异则关注 display_errors、log_errors 与 error_reporting。不要因为某项“不同于默认值”就立即改回默认值，它可能正是生产安全策略。

一个可回滚的配置核对流程

把输出直接交给人工肉眼比较很容易漏项。更稳妥的做法是把每个差异分为三类：

1. 故障相关：与当前症状直接有关，例如测试环境的上传上限小于请求体；
2. 预期策略：不同环境本来就需要不同，例如开发环境显示错误、生产环境只记录日志；
3. 意外漂移：没有变更记录、没有环境理由，却只在某台机器上出现的配置。

修复时只改一个配置来源，并保留原值和回滚方式。若最终值来自 conf.d/99-app.ini，就不要同时修改主 php.ini 和容器启动参数。修改后重启对应 SAPI，再做一次重新采集验证，确认目标差异发生变化，其他配置没有被顺带改动。

不要把 CLI 快照当成 PHP-FPM 事实

php --ini=diff 是 CLI 调用。线上请求通常由 PHP-FPM 或 Web 服务器模块处理，它们可能使用不同的配置文件、附加目录、启动参数和池级设置。因此，CLI 输出适合发现环境线索，但不能单独证明 Web 请求的最终配置。

排查 FPM 时，应把 CLI 结果与 FPM 的配置加载路径、池配置和受控的运行时诊断结果对应起来。诊断页若包含路径、扩展、环境变量或密钥线索，不要暴露在公网；完成核对后立即移除。生产验收标准应写成具体行为，例如“20MB 的允许文件上传成功、超过上限得到受控错误”，而不是只写“配置看起来一致”。

升级 PHP 后为什么要重建基线

--ini=diff 的参照物是当前 PHP 构建的内置默认值。更换 PHP 版本、发行版镜像、编译选项或已加载扩展后，可用 INI 项和默认值都可能变化。于是，同一份配置文件在两个构建上的差异输出不一定相同。

建议把 php -v、镜像摘要或软件包版本与差异快照一起归档。升级完成后重新生成基线，不要拿旧版本的差异列表当作新版本的完整验收标准。自动化脚本也应先检测命令是否支持 --ini=diff，再决定使用新方式还是兼容旧环境的采集逻辑。

常见问题

输出为空，是否说明没有加载 php.ini？

不能这样判断。输出关注的是最终值是否偏离内置默认值；配置文件是否加载、从哪里加载，应由 php --ini 确认。

两台机器的差异输出相同，是否说明环境完全一致？

也不能。还要核对 PHP 版本、构建、扩展、SAPI 和配置来源。相同文本只说明被打印出的差异相似，不代表二进制和运行环境完全相同。

能否把差异输出直接提交到仓库？

可以先做脱敏与审查。路径、扩展配置和第三方服务设置可能暴露内部结构；仓库里更适合保存经过审核的基线和允许差异清单，而不是未经检查的生产原始输出。

小结

PHP 8.5 的 --ini=diff 把配置排查从“浏览所有信息”变成“先看偏离默认值的项目”。正确用法是把它放进一条证据链：用 php -v 固定版本，用 php --ini 追溯来源，用 php --ini=diff 缩小差异，再按故障、策略与漂移分类处理。最后还要回到实际 SAPI 和业务行为验证，才能避免把 CLI 快照误当成线上事实。

参考：PHP 8.5 官方迁移指南：其他变更、PHP 8.5 官方发布页。