先验证包是否真实存在：访问https://packagist.org/packages/vendor/name确认页面可打开，检查大小写、版本是否存在及是否被废弃；再排查镜像配置是否生效、缓存是否残留、私有仓库配置是否完整。
确认包是否真实存在且可安装
报 404 Not Found，第一反应不该是换镜像或清缓存，而是验证这个包是不是真的能被 Composer 找到。访问 https://packagist.org/packages/vendor/name（把 vendor/name 换成你 require 的完整包名），看页面是否返回 404。注意大小写必须完全一致：monolog/monolog ✅，Monolog/monolog ❌；spatie/laravel-backup ✅，spatie/backup ❌。
如果页面能打开，点 “Versions” 标签页，确认你要的版本是否存在——比如写 "dev-main"，但远程仓库只有 master 分支，就会静默失败；写 "1.2.3"，但 Git 里没打对应 tag（只有 v1.2.3 或 release-1.2.3），同样 404。
别信 IDE 补全或旧文档：有些包已废弃（如 guzzle/guzzle），补全出来也装不了；composer search vendor/name 只查 Packagist 全局索引，不校验稳定性、PHP 版本或你本地的 repositories 配置，搜得到 ≠ 能装。
检查镜像源是否真正生效
运行 composer config -g repo.packagist，输出必须是类似这样的完整 JSON 对象：{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}。如果返回 null、空行、https://packagist.org 或报错，说明配置根本没写进去——漏了 -g、键名写成 repos.packagist、URL 少了末尾 /，都会导致静默 fallback 到官方源。
用 curl -I https://mirrors.aliyun.com/composer/packages.json 实测响应：必须是 HTTP/2 200。返回 404、301、超时，或内容是 HTML 页面（比如“Not Found”），基本就是用了已停服镜像（如 https://packagist.phpcomposer.com）或地址拼错（/composerpackages.json 这种路径错误）。
临时切回官方源验证：composer config -g repo.packagist composer https://repo.packagist.org，再跑一次 composer install。如果不报 404 了，问题就锁定在镜像上。
私有包或自定义仓库 404 的真实原因
私有包报 404，90% 不是网络不通，而是 repositories 配置没生效或字段缺失。Composer 默认根本不查你公司 GitLab 或本地路径，除非配置完全正确。
repositories 必须包含完整 type 和 url：
- VCS 类型（Git/GitLab）要写
"type": "vcs"，不是"git"或漏掉； - URL 必须是可
git clone的地址，结尾只能是.git，不能带#main或路径； - 目标仓库根目录要有合法
composer.json，且其中name字段与require中写的**完全一致**； - GitHub 私有库需
auth.json配 token，URL 里不能含@username，否则认证被跳过。
更重要的是：必须显式禁用默认兜底源。在 repositories 数组末尾加一个独立对象：{"packagist.org": false}。写成 "packagist": false 或嵌套进其他仓库配置里，会被静默忽略。
清缓存和重装的必要步骤
缓存不是可选项，是前置硬性动作。Composer 缓存会固化 provider 文件路径（比如 p/provider-2025-10%24json），一旦镜像切换或包下架，缓存里的旧地址就会持续触发 404，哪怕你已经改了配置。
必须按顺序执行：
-
composer clear-cache—— 清掉所有 provider 和 dist 缓存； - 手动删掉
vendor/目录和composer.lock——composer.lock可能锁死一个已失效的 provider 地址； - 再运行
composer install—— 别用update替代，它可能复用 lock 里过期的元数据。
CI 环境更需警惕：每次都是干净容器，DNS 不稳、内存紧张，必须配缓存（如 GitHub Actions 的 cache: $HOME/.composer/cache），并加 --prefer-dist 和超时参数，否则 404 复现率极高。
