Composer报404主因是镜像源不可用或私有仓库配置失效，应优先切换国内镜像（如阿里云）、检查repositories和auth.json，并清理composer.lock强制刷新URL。
为什么 composer install 或 composer require 报 404？
绝大多数情况不是你写错了包名，而是 Composer 默认访问的 packagist.org 镜像不可用、被拦截，或你本地配置了失效的私有仓库地址。官方源在国内不稳定，很多公司内网又屏蔽了境外域名，直接触发 404 Not Found（实际是网络层失败后 Composer 误报为包不存在）。
- 典型错误信息：
Could not find package xxx at any version，但你在 packagist.org 网页上能搜到该包 - 执行
composer diagnose会提示curl error 28: Operation timed out或SSL certificate problem - 你没改过
composer.json，但昨天还能装，今天就 404 —— 大概率是镜像源抽风
怎么快速切到可用镜像（国内用户必做）
别碰 composer.json 的 repositories 字段，那是给私有包用的。临时切换全局镜像，用 composer config 改 packagist.org 的代理地址就行。
- 切阿里云镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 切腾讯云镜像：
composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/ - 恢复默认（慎用）：
composer config -g --unset repos.packagist - 验证是否生效：
composer config -g repo.packagist应该输出镜像 URL，不是null
注意：-g 是全局配置，影响所有项目；如果只想改当前项目，去掉 -g，并在项目根目录下执行。
composer update 还是 404？检查这三处
镜像换了还不行，说明问题不在源本身，而是请求路径或认证环节出错。
- 你的
composer.json里写了"type": "package"或自定义repositories，但其中某个 URL 返回 404 —— 逐个注释掉repositories块再试 - 用了私有 GitLab/GitHub 包，但 token 过期或权限不足，Composer 会把 403 权限错误伪装成 404；检查
auth.json里的github-oauth或gitlab-token - PHP 版本太低（如 PHP 7.2），某些新包要求 PHP >= 8.0，Composer 无法解析其
require，也可能报 404 而非清晰的版本错误
为什么删了 vendor 和 composer.lock 还是 404？
因为 composer.lock 里记录的是包的原始下载 URL（比如 https://api.github.com/...），不是镜像地址。一旦锁文件里存了已失效的 GitHub API 地址（常见于 fork 的包或旧版 lock），即使你切了镜像，Composer 仍会优先按 lock 文件里的 URL 去拉取。
- 最干净的做法：
rm -rf vendor composer.lock，再跑composer install - 如果不想丢 lock（比如 CI 环境要求锁定版本），先执行
composer update --lock强制刷新 lock 中的 URL，再重试 - 长期建议：在
composer.json顶部加"config": {"preferred-install": "dist"}，避免走 Git clone 路径（它更容易触发 404）
真正卡住的地方，往往不是命令怎么打，而是你以为在换源，其实 Composer 正从 lock 文件里读一个三年前的 GitHub API 地址 —— 它早就不返回 JSON 了。
