Composer 的 platform 配置必须设对，因为其默认按本地环境解析依赖，而部署目标环境（如 PHP 版本、扩展）可能不同，需通过 config.platform 显式声明目标能力，确保 vendor/ 兼容生产环境。
Composer 的 platform 配置为什么必须设对
Composer 默认按当前运行环境（PHP 版本、扩展）解析依赖，但部署目标环境可能不同——比如本地开发用 PHP 8.2，生产服务器是 PHP 8.1，或 CI 环境没装 ext-gd。若不干预，composer install 可能装错版本，甚至失败。
关键不是“能不能装”，而是“装出来的 vendor/ 是否能在目标环境跑”。解决方式是在 composer.json 中显式声明目标平台能力：
{
"config": {
"platform": {
"php": "8.1.25",
"ext-gd": "1.0.0",
"ext-mbstring": "1.0.0"
}
}
}
这样 Composer 就会忽略本地实际环境，只按这个配置选包版本。注意：platform 不会自动安装扩展，它只是“告诉 Composer：请假装这些扩展已存在”。
用 composer install --ignore-platform-req 是临时补救，不是方案
当遇到类似 Your requirements could not be resolved to an installable set of packages，有人直接加 --ignore-platform-req 强行跳过检查。这会导致：
-
vendor/里装了依赖要求 PHP 8.2 的包，但 PHP 8.1 运行时直接Fatal error: Uncaught Error: Undefined constant ... - CI 构建成功，线上启动报错，问题延迟暴露
- 下次本地执行
composer update又因环境差异拉取不同版本，团队协作混乱
真正该做的是：明确目标平台 → 写进 platform → 提交到仓库。CI 脚本里反而要加 --no-dev 和 --optimize-autoloader，而不是绕过平台检查。
platform-check 命令帮你验证是否真匹配
写了 platform 不代表万事大吉。Composer 8.2+ 提供 composer platform-check，它会对比 composer.json 中的 platform 配置和当前环境真实能力，输出缺失项：
$ composer platform-check PHP version (8.1.25) matches platform config ✓ ext-gd (missing) ✗ ext-mbstring (8.1.25) ✓
这个命令应该纳入部署前检查流程。常见遗漏点：
-
ext-redis或ext-pdo_pgsql这类非默认扩展，容易只写在require里却忘了进platform - PHP 微版本号写太死（如
"php": "8.1.0"），导致小版本升级后platform-check报警，其实兼容 —— 改用"php": "^8.1"更稳妥 -
platform里写了ext-xdebug，但生产环境严禁启用，属于误配
Docker 场景下别让 composer install 在宿主机跑
很多人在 Docker 项目里仍习惯先在 Mac/Windows 上跑 composer install，再把整个 vendor/ 拷进镜像。这极危险：宿主机 PHP 版本、扩展、架构（Intel vs Apple Silicon）都和容器内不同。
正确做法是把 composer.json 和 composer.lock COPY 进镜像，在容器内执行 composer install，并确保 Dockerfile 中的 PHP 基础镜像与 platform 配置一致：
FROM php:8.1-cli COPY composer.json composer.lock ./ RUN composer install --no-dev --optimize-autoloader
如果镜像里确实缺扩展（如没装 gd），就在 RUN 步骤中补上，而不是靠 platform 掩盖问题。否则构建通过，运行时报 Class 'GDImage' not found 才发现晚了。
最常被忽略的其实是 composer.lock 文件本身：它记录了每个包在特定平台下的解析结果。一旦 platform 改了，必须重新 composer update 并提交新 lock 文件，否则别人 composer install 时还是按旧平台逻辑还原依赖。
