Composer install失败主因是composer.lock中记录的PHP版本或扩展要求与服务器实际环境不匹配，须运行composer check-platform-reqs和composer why-not定位阻断包，禁用config.platform伪装，确保真实环境达标。
线上 composer install 直接失败，不是网络或权限问题，而是 composer.lock 记录的依赖版本与服务器 PHP 版本/扩展能力不匹配——必须按环境校验结果修复，不能绕过。
composer install 卡在 Resolving dependencies 或报 Your requirements could not be resolved
这说明 Composer 正在尝试从 composer.lock 还原依赖，但发现当前环境（PHP 版本、已启用扩展）无法满足 lock 文件中记录的平台约束。常见诱因：
-
composer.lock是在 PHP 8.2 开发机生成的，而服务器是 PHP 8.1，且某包在 lock 中明确要求"php": ">=8.2.0" - 服务器缺
ext-intl，但 lock 文件里某个包的require包含"ext-intl": "*"，且没配 polyfill 替代 -
config.platform里硬写了"php": "8.2.22"，但服务器实际是 8.2.21 —— 小版本差一位也会触发拒绝
解决动作：先跑 composer check-platform-reqs，它会逐条列出当前环境缺失的 PHP 版本或扩展；再比对 composer show --platform 输出，确认 lock 文件“以为”的平台能力是否真实存在。
composer why-not vendor/package:version 定位阻断链
报错里只写 Conclusion: don't install laravel/sanctum:^3.0，但没说谁拦着。这时候别改 composer.json，直接问 Composer：
composer why-not laravel/sanctum:^3.0
它会输出真实依赖阻断路径，例如：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
myapp/core dev-main requires guzzlehttp/guzzle (^6.5)laravel/sanctum ^3.0 requires guzzlehttp/guzzle (^7.2)
说明冲突根因是 guzzlehttp/guzzle 版本无交集。接着查谁在拉 6.x：composer why guzzlehttp/guzzle —— 常见答案是 require-dev 里的旧版测试工具，或某个私有 SDK。
config.platform 是伪装开关，不是兼容层
config.platform 的作用是告诉 Composer：“就当这些已存在”，但它不装扩展、不升级 PHP、也不加载 polyfill。滥用后果严重：
- 加了
"ext-intl": "8.1.0"，但服务器真没装，运行时直接抛Class 'IntlDateFormatter' not found - 设
"php": "8.2.22"后强行装上一个仅在 .22 修复了反序列化 bug 的包，结果在线上 .21 环境里崩 - CI 流水线里用了
config.platform掩盖问题，导致上线前完全没暴露
正确做法：删掉所有 config.platform.ext-xxx 行，用 sudo apt install php-intl（Ubuntu）或 docker-php-ext-install intl（Alpine）补扩展；若真不能装（如共享主机），必须确认所有依赖都声明支持 symfony/polyfill-intl-* 类包，并在 require 中显式引入。
composer install --dry-run 是上线前必跑检查项
它不改任何文件，只模拟还原过程，能提前暴露三类致命问题：
- 输出
Your lock file does not contain a compatible set of packages→composer.lock和当前composer.json不同步，需composer update --lock刷新元数据 - 卡在
Resolving dependencies超过 30 秒 → lock 里有dev-main或已下线分支，Packagist 已不可达 - 出现
ignored platform requirements→ 不是警告，是 Composer 已自动跳过校验，但你的 autoloader 很可能因缺扩展当场失败
真正容易被忽略的是：这个命令必须在**目标服务器环境**（同 PHP 版本、同扩展、同用户权限）下执行，否则等于白跑。
