PHP Composer 平台要求怎样提前发现 PHP 版本不兼容

要提前发现 PHP 版本或扩展不兼容，可以在接近生产的目标环境执行 composer check-platform-reqs --lock --no-dev，按锁文件检查真实平台；依赖安装完成后再用不带 --lock 的命令检查已安装包。它会忽略 config.platform 的模拟值，所以更适合确认实际环境是否满足要求。

Composer 官方地址：https://getcomposer.org/

我会把依赖解析和部署平台确认分开：前者决定选哪些包，后者确认这些包能否在当前 PHP 与扩展配置下使用。只看“开发机安装成功”，很容易遗漏线上解释器不同或少启用了一个扩展的情况。这里不涉及新的 PHP 语义变更，而是澄清几个容易混淆的 Composer 规则。

声明要求和模拟平台各管一件事

在 composer.json 的 require 中声明项目实际需要的 PHP 范围和扩展，Composer 才能把它们纳入约束。下面是独立的示例配置，实际项目应按自己的兼容范围填写。

{
  "require": {
    "php": ">=8.2 

require.php 声明这个示例支持的 PHP 范围，扩展字段表示必须存在；config.platform.php 则让依赖解析按指定版本选择兼容包。严格 JSON 不支持注释，因此字段解释放在代码旁。示例中的版本仅用于解释配置，不是对生产版本支持期限的推荐。

平台依赖是环境的虚拟包，声明 ext-intl 不会自动安装系统扩展。设置 platform.php 也不会切换当前 PHP 二进制。我的选择是让模拟值表达受支持的部署基线，同时把真实环境检查保留下来；不能因为模拟了一项环境能力，就当它真的存在。

旧习惯的问题：依赖能装，不等于线上能跑

假设开发机运行较新的 PHP，而目标镜像较旧，未控制解析条件时可能选中目标环境不接受的依赖。反过来，若配置模拟为较新的 PHP，却在更旧的真实解释器上安装，解析过程看到的条件也不代表真实执行能力。

因此我不会用修改 platform 值来“修复”目标 PHP 不兼容，更不会把忽略平台要求当成常规发布办法。正确方向是调整目标环境，或者在开发阶段选择真正支持目标环境的依赖组合，并提交对应锁文件。不要在生产节点随意 update 来临时改变依赖解法。

把检查放进目标环境

在含有 composer.lock 的项目目录，使用目标 PHP 启动 Composer。若使用 PHAR，可以明确由哪个解释器执行，避免 composer 包装脚本意外调用另一套 PHP。

# 用目标环境的PHP检查锁文件中的生产依赖平台要求
php composer.phar check-platform-reqs --lock --no-dev

# 已安装依赖后，检查实际安装包的要求；这里不再读取锁文件模式
php composer.phar check-platform-reqs --no-dev

--lock 检查锁文件要求，不要求先把 vendor 中的包当作检查依据；默认模式面向已安装包。--no-dev 跳过开发依赖要求，适合不部署开发依赖的场景；如果生产任务确实要使用相关工具，就不应机械排除它们。

这里给出的是读者可采用的命令，不是本文执行回执。调用完成后要保留退出状态：非成功退出应阻止后续步骤继续，不能只保存一份输出就忽略错误。若需要机器读取，可以使用命令支持的 JSON 格式，但仍要分别处理执行状态和数据内容。

# Bash示例：检查失败就结束当前部署脚本
if ! php composer.phar check-platform-reqs --lock --no-dev; then
  printf '%s\n' 'PHP或扩展平台要求未满足，停止后续部署' >&2
  exit 1
fi

CLI 通过后，仍要留意 FPM 配置

检查器看到的是执行 Composer 的 PHP。CLI 和 FPM 可能使用不同的解释器、php.ini 或扩展加载目录，所以 CLI 通过不能直接推导 Web 请求环境也一致。我的做法是把它作为目标环境确认的一部分，再核对实际服务进程配置。

# 查看当前CLI解释器版本、配置文件来源与扩展列表
php -v
php --ini
php -m

这些命令只反映 CLI。应通过运行平台的进程配置、容器定义和受控诊断方式确认 FPM，不要为方便把包含环境详情的诊断页面长期公开。若同一容器里放了多套 PHP，更要记录实际启动路径和服务配置。

平台要求检查能说明什么

它检查的是包声明的平台要求，不能替代业务功能测试，也无法发现未声明的隐含依赖。若应用实际调用了扩展功能却没有正确声明，配置与代码本身也需要修正。

我更愿意保留简单而明确的三份信息：依赖锁文件、目标 PHP 与扩展配置、检查结果。模拟平台负责让解析贴近目标，真实检查负责暴露环境差异，服务配置负责确认实际运行方式。这比反复尝试忽略某条要求更容易追溯。

改 platform.php 后需要升级 PHP 吗

该配置不会执行升级。是否要调整真实环境，要看项目和锁定依赖要求。

没有 vendor 能先检查吗

已有锁文件时可使用 --lock；没有锁文件则应先完成受控依赖解析，不能假装已经确认一组尚未确定的依赖。

全部通过是否意味着应用兼容

只意味着本次检查覆盖的已声明平台条件满足。应用行为、服务配置和未声明需求仍有各自边界。

参考：Composer 平台要求检查；platform 配置；平台虚拟包说明。