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 输出，少信第一眼错误文字。
