Composer如何调试安装失败的问题？（常见错误排查）

composer安装失败首要排查-vvv日志和网络连通性，再检查ca证书、php版本、lock文件source字段、私有仓库Token、autoload配置及ci环境差异。

看 composer install 卡住或报错时，先查日志和网络

Composer 安装失败多数不是代码问题，而是环境或网络干扰。默认不输出详细日志，所以第一步必须加 -v（verbose）或 -vvv（最详细）运行，否则你看到的只是模糊提示，比如 Failed to download vendor/package，但根本不知道是 DNS 解析失败、TLS 握手超时，还是 gitHub 限流。

• composer install -vvv 是必跑命令，错误源头基本藏在最后 10 行里
• 国内用户常卡在 github.com 或 packagist.org，用 curl -I https://packagist.org/packages.json 手动测连通性
• 如果出现 cURL Error 60: ssl certificate problem，说明 CA 证书过期或系统 OpenSSL 版本太老，别急着关 verify-peer，先试 composer config -g cafile /path/to/cacert.pem
• PHP 版本不匹配也会静默失败——比如 composer install 没报错但最终 vendor/autoload.php 不存在，很可能是当前 PHP 版本低于 composer.json 中 config.platform.php 声明的最低版本

依赖冲突报错：为什么 composer update 能过，composer install 却失败？

这是最反直觉的一类问题。composer install 严格按 composer.lock 还原依赖树，而 composer update 会重新解析并写入新 lock。所以当 lock 文件里记录了某个包的特定 commit（比如 "source": {"type": "git", "url": "...", "reference": "abc123..."}），但该 commit 已被 force push 覆盖或仓库私有化，install 就会失败，而 update 因为跳过了 source 直接走 dist 包，反而成功。

• 检查 composer.lock 里出问题的包是否含 "source" 字段，尤其是 "reference" 是短哈希或已失效分支名
• 私有 gitlab/GitHub 仓库未配置 token 时，install 可能因无法 clone source 而退回到 dist，但若 dist URL 本身不可达（如 S3 权限过期），就会报 Could not fetch ...
• 运行 composer install --no-suggest --ignore-platform-reqs 只是绕过问题，不是解决——它可能掩盖 PHP 扩展缺失（如 ext-intl）导致的 autoloader 加载失败

autoload 生效失败：明明 vendor/autoload.php 存在，却提示类找不到

Composer 安装完成后，自动加载机制是否生效，不只取决于文件是否存在，更取决于 composer.json 的 autoload 配置是否被正确解析、是否与实际目录结构一致，以及是否被其他 autoloader 干扰。

• 确认 composer dump-autoload -o 是否执行过——开发中改了 psr-4 映射后，不重生成优化 autoloader，新增类永远找不到
• 检查 composer.json 中 "autoload" 和 "autoload-dev" 是否混用：测试类写在 autoload-dev 里，但生产环境跑了 composer install --no-dev，就会漏加载
• 多个 Composer 项目嵌套（如 wordpress 插件自带 vendor）时，主项目的 vendor/autoload.php 不会自动加载子项目的 autoload，得手动 require 或用 classmap 显式包含
• windows 下路径大小写不敏感，但 linux 会严格区分 src/Helper.php 和 src/helper.php——类名匹配文件路径失败时，composer dump-autoload -v 会打印出“skipped”警告

CI 环境下安装失败：缓存、权限和 PHP 配置的隐性差异

本地好好的，CI（如 GitHub Actions、GitLab CI）里 composer install 失败，大概率不是 Composer 本身的问题，而是环境预设和本地不同。

• CI 默认启用 --no-interaction，遇到需要用户确认的场景（如 license 交互、平台配置冲突）会直接退出，加 --no-interaction --prefer-dist 强制跳过
• docker 镜像若用 alpine，缺 libzip 或 openssl 扩展会导致 zip 包解压失败，报 Unable to extract ...，而非明显扩展缺失提示
• GitHub Actions 的 cache 步骤若缓存了 vendor 但没校验 composer.lock 变更，旧缓存 + 新 lock 可能引发 autoloader 错乱——建议只缓存 ~/.composer/cache，而非整个 vendor
• 某些 CI 使用非 root 用户运行，而 composer install 试图写入全局 config（如 composer config -g github-oauth...），会因权限拒绝失败，应改用项目级配置：composer config github-oauth.github.com xxx

真正麻烦的从来不是报什么错，而是错误信息没指向真实原因——比如 Class not found 往往是 autoloader 没生效，而不是类文件丢了；Could not parse version constraint 其实是某行 JSON 多了个逗号，但 Composer 报错位置总在最后一行。多看 -vvv 输出，少信第一眼错误文字。