404报错主因是包名/版本写错或包未注册，需先查packagist页面及版本列表；再确认镜像源是否生效且连通；必须清缓存、删vendor与lock后重装；ci环境须配缓存、--prefer-dist及超时设置。
确认是不是真包不存在，而不是源或缓存的问题
404 报错最常被误判为“网络不行”或“镜像挂了”，其实八成是 composer.json 里写错了包名、版本号，或者那个包压根没在 Packagist 上注册。
- 打开 https://www.php.cn/link/3183fc21acb07e30098c42484e12d697（把
your-vendor/your-package换成你写的完整包名），看页面是否 404；注意大小写，monolog/monolog对，Monolog/monolog就错 - 如果页面能打开，点 “Versions” 标签，确认你要的版本（比如
^7.9或dev-main）是否列在其中——dev-master很多项目已删，换成dev-main再试 - 别信 IDE 自动补全：它可能缓存了旧包名，比如把
guzzlehttp/guzzle补成guzzle/guzzle（后者早已废弃）
验证当前镜像源是否真的生效且可用
很多人改了源却没生效，或者用的是已停服的镜像（比如 packagist.laravel-china.org 自 2023 年底就彻底下线），结果所有请求都 404。
- 运行
composer config --list | grep repo.packagist，看输出是不是你预期的地址，例如https://mirrors.aliyun.com/composer/ - 手动测镜像连通性：
curl -I https://mirrors.aliyun.com/composer/packages.json，秒回HTTP/2 200才算活；返回404或超时，说明镜像本身不可用或本地 DNS/代理阻断 - 临时切回官方源验证：
composer config -g repo.packagist composer https://repo.packagist.org，再跑一次composer install—— 如果不报 404 了，问题就出在镜像上
清缓存不是可选项，而是必须前置动作
Composer 缓存会固化 provider 文件路径（比如 p/provider-2025-10%24json），一旦镜像切换或包被下架，缓存里的旧地址就会持续触发 404，哪怕你已经改了配置。
- 第一步永远是
composer clear-cache，不要跳过 - 接着删掉
vendor/和composer.lock（尤其composer.lock可能锁死一个已失效的 provider 地址） - 再执行
composer install；别用update替代，它可能复用旧 lock 里的错误元数据
CI 环境下 404 更容易反复出现，得加防护配置
GitHub Actions、GitLab CI 这类环境每次都是干净容器，没缓存、DNS 不稳、内存紧张，而 Composer 默认行为完全没适配这种场景，导致下载失败率远高于本地。
- 必须开启缓存：GitHub Actions 中加
cache: $HOME/.composer/cache；GitLab CI 则在cache:下配key: $CI_JOB_NAME-composer-cache和路径 - 强制走 dist 包，避免触发 GitHub API 限流：
composer install --prefer-dist（尤其没配github-oauth时，--prefer-source很可能直接 403） - 加超时兜底：CI 脚本中设
COMPOSER_PROCESS_TIMEOUT=600和COMPOSER_HOME=/tmp/composer，防默认 300 秒中断和家目录权限问题
--prefer-dist，结果每次构建都卡在同一个包上。 
