根本原因是源配置错误或未生效，需用 composer config repo.packagist 和 composer config -g repo.packagist 确认实际源地址，再通过 composer clear-cache && composer update -vvv 查看真实请求 URL 定位问题。
composer install 报错 “Package not found” 怎么快速定位源问题
根本原因往往不是包真不存在，而是当前配置的源（repository）没同步最新数据、被墙、或指向了错误地址。先别急着换镜像，用 composer show --platform 和 composer config repo.packagist 确认你实际在用哪个源。
-
composer config -g repo.packagist查全局配置，很多人本地改了但没加-g，误以为生效了 - 如果输出是
{"type": "composer", "url": "https://packagist.org"}，说明没走国内镜像——哪怕你装了阿里云/腾讯云镜像插件，也得确认是否真正启用 - 执行
composer clear-cache后再composer update -vvv，看 verbose 日志里请求的是哪个 URL，这是最真实的源行为
阿里云 / 腾讯云镜像为什么突然不生效
镜像服务本身不维护 Composer 的元数据索引（packages.json），只代理上游。一旦 packagist.org 临时不可达或返回 503，镜像会缓存失败状态，导致后续请求直接报 404，而不是穿透重试。
- 阿里云镜像的默认缓存过期时间是 30 分钟，期间即使上游恢复，你仍可能拿到旧错误
- 腾讯云镜像不支持
composer self-update自动切换，必须手动运行composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/ - 用
curl -I https://mirrors.aliyun.com/composer/packages.json直接测镜像连通性，比composer install更快暴露网络或证书问题
私有包 404 但 git 地址能 clone，怎么回事
Composer 不是直接 clone 仓库，而是先向源发起 HTTP 请求获取 composer.json 元信息。私有 GitLab/GitHub 仓库若没配好 composer.json 或权限策略，就会卡在这步。
- 确保仓库根目录有有效的
composer.json，且"name"字段格式为vendor/name，和require中写的完全一致（大小写敏感） - GitLab 私有项目需开启
api访问权限，并在auth.json中提供 personal access token；GitHub 则必须用 token 替代密码，且勾选read:packages - 如果用了
path类型仓库，路径必须是绝对路径或相对于composer.json的相对路径，../my-package在子目录下会失效
require 某个版本却总是装错，怎么看实际解析逻辑
Composer 的版本解析发生在 lock 文件生成阶段，不是安装时才决定。如果你改了 require 但 composer.lock 还在，它会优先按 lock 文件装，导致“明明写了 ^2.0 却装了 1.9.5”。
- 删掉
composer.lock再composer install，强制重新解析依赖树（仅调试用，上线前务必保留 lock） - 用
composer depends vendor/package查谁在间接依赖该包，避免因传递依赖锁死版本 -
composer why-not vendor/package:2.0.0会列出所有阻止升级的约束条件，比如某个依赖硬绑定了"vendor/other": "
最常被忽略的一点：公司内网环境可能部署了私有 Packagist 镜像代理，但它没开启对 dist 包的重定向支持，结果 metadata 能取到，下载 ZIP 时却 404。这时候看 composer update -vvv 最后几行的 Downloading http://... 请求地址，比查文档更快发现问题所在。
