Composer install 报错通常源于镜像配置错误、缓存污染、权限问题或依赖元数据失效，应按错误关键词精准定位：如“Could not fetch packages.json”需检查镜像URL、TLS证书与DNS；“Permission denied”多因sudo污染导致属主为root，需chown修复；无composer.lock时应运行composer update而非install；404 tag需验证GitHub仓库并改用commit hash或手动注入package。
Composer install 报错，八成不是 Composer 坏了，而是镜像没配对、缓存污染、权限错乱或依赖元数据失效——先别重装 PHP 或删整个 ~/.composer，按错误关键词直接切到对应环节。
报 “Could not fetch packages.json” 或卡在 “Loading composer repositories”
这是典型的元数据拉取失败，和 vendor/ 无关，只和仓库地址、TLS、DNS 有关。
- 立刻运行
curl -I https://mirrors.aliyun.com/composer/packages.json：返回 200 才算通；若报SSL connect error，说明 CA 证书过期，需更新openssl.cafile和curl.cainfo指向最新cacert.pem - 检查镜像配置是否写对：
composer config -g repo.packagist输出必须是完整 JSON，如{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}；少斜杠、漏type、键名写成repos.packagist都会静默失效 - 项目级配置优先于全局：只要
composer.json里有"repositories"字段（哪怕空数组），全局镜像就彻底不生效；此时应进项目目录运行composer config repo.packagist composer https://mirrors.aliyun.com/composer/
报 “Permission denied” 写 vendor/ 或 composer.lock
这不是权限不够，而是目录“主人不对”——90% 是被 sudo composer install 污染过，导致 vendor/ 属主变成 root，而你当前用普通用户执行。
- 查归属：
ls -ld vendor/ composer.lock，若显示root root，立刻修复：sudo chown -R $USER:$USER vendor/ composer.lock - 别用
chmod 777硬怼——这解决不了属主错位问题，反而引入安全风险 - Windows 下报
Access is denied且错误出现在生成.bat文件时，大概率是杀软拦截；临时禁用 Windows Defender 实时防护，或改用 Git Bash 运行
报 “No composer.lock file present” 或 “Command install is not defined”
没有 composer.lock，composer install 就拒绝工作——它不是提示你“该生成”，而是明确中断。
- 新项目初始化：必须运行
composer update（不是install），才会解析composer.json并生成合法composer.lock - 误删
composer.lock后只跑composer install，新版 Composer(v2.5+) 会直接报Command "install" is not defined；旧版可能静默失败，但vendor/一定不一致 - CI 脚本中漏传
composer.lock，等于放弃环境一致性；不同构建节点可能装出guzzlehttp/guzzle的 v7.4.5 和 v7.5.0，行为差异肉眼难察
报 “Failed to download … at tag v2.1.0: HTTP/2 404”
不是网络差，是那个 tag 被作者从 GitHub 删了——Packagist 元数据还指着它，但 ZIP 归档地址已 404。
- 验证是否真删：
curl -I https://api.github.com/repos/vendor/package-name/zipball/v2.1.0，返回 404 即确认 - 不要盲目升版本：先查该仓库 Releases 页面，找等效 commit hash（如
abc1234），然后把composer.json中的"vendor/package-name": "v2.1.0"改成"v2.1.0#abc1234" - 若连 fork 都没有，只能用
"type": "package"手动注入归档："repositories": [{"type": "package", "package": {"name": "vendor/package-name", "version": "v2.1.0", "dist": {"url": "https://your-domain.com/archives/package-v2.1.0.zip", "type": "zip"}}}]，然后运行composer update vendor/package-name --with-dependencies
所有操作里最容易被跳过的，是确认 composer config -g repo.packagist 的输出是否为预期 JSON —— 它不报错，也不提示失败，只安静退回官方源。多花十秒看这一行，能省两小时排查时间。
