404错误表示服务器未找到请求资源，常见于包名错误、版本不存在或Packagist未注册；需先验证包地址、检查大小写与版本列表，再排查镜像配置、缓存及依赖冲突。
404 报错不是网络问题，先查包是否存在
看到 404 Not Found 别急着换镜像或改 DNS。八成是包名写错、版本不存在，或者那个包压根没在 Packagist 注册。
实操步骤：
- 打开
https://packagist.org/packages/your-vendor/your-package（把your-vendor/your-package换成你写的完整包名），看页面是否 404；注意大小写，monolog/monolog对，Monolog/monolog就错 - 能打开就点 “Versions” 标签，确认你要的版本（比如
^7.9或dev-main）是否列在其中——很多项目已删掉dev-master - 别信 IDE 补全：它可能缓存了废弃包名，比如把
guzzlehttp/guzzle补成guzzle/guzzle
“Your requirements could not be resolved” 是依赖冲突，不是源挂了
这个错误说明 Composer 已连上镜像、也下载完全部元数据，但本地 SAT 求解器算不出满足所有约束的版本组合。跟网络、镜像、缓存都没关系。
常见诱因：
-
php版本不匹配：比如composer.json写了"php": "^8.3"，但本地是 8.2；运行composer why-not php:8.3直接定位拦路包 - 扩展缺失：如
ext-pcntl、ext-redis没启用，也会触发该报错（可临时用--ignore-platform-reqs绕过，但别上生产） - 私有包和镜像顺序错位：项目级
composer.json里如果同时配了私有源和镜像，私有源必须放在镜像前面，否则 Composer 先去镜像查——而镜像没有你的私有包，直接 404
镜像配置生效与否，必须手动验证
很多人改完镜像就以为搞定了，结果报错还是走官方源。关键得看配置是否真正写入、URL 是否合法、镜像本身是否活着。
检查三步法：
- 运行
composer config --list | grep repo.packagist，输出应为类似{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}；注意末尾必须带/，https://mirrors.aliyun.com/composer❌ - 手动测连通：
curl -I https://mirrors.aliyun.com/composer/packages.json，秒回HTTP/2 200才算活；返回 404 或超时，说明镜像不可用或被代理/DNS 阻断 - CI 环境（GitHub Actions / GitLab CI）默认不继承本地配置，必须在 workflow 文件里显式执行
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
缓存不清理，换源也白搭
Composer 缓存会固化 provider 文件路径（比如 p/provider-2025-10%24json）。一旦镜像切换或包下架，缓存里的旧地址就会持续触发 404，哪怕你已经改了配置。
必须前置动作：
- 第一步永远是
composer clear-cache，不要跳过 - 接着删掉
vendor/和composer.lock（尤其composer.lock可能锁死一个已失效的 provider 地址） - 再执行
composer install；别用update替代，它可能复用旧 lock 里的错误元数据 - CI 环境还要加缓存防护：GitHub Actions 中配
cache: $HOME/.composer/cache，GitLab CI 配key: $CI_JOB_NAME-composer-cache
最常被忽略的是 repositories 数组顺序和 trailing slash —— 这两个点错一个，404 就稳稳蹲你项目里，而且不会报任何提示。
