Composer安装包404错误根本原因是包名拼写错误、版本/分支不存在或Packagist上包被移除/重命名，而非网络或Composer自身故障；需依次检查composer.json字段、运行composer show验证、确认仓库配置与分支存在性、使用--dry-run预检、配置国内镜像、检查auth认证及清理vendor/lock残留。
Composer 安装包时返回 404 错误
根本原因通常是包名拼写错误、版本不存在，或 Packagist 上该包已被移除/重命名。不是网络问题，也不是 Composer 本身坏了。
- 检查
composer.json中的"name"和"version"字段是否准确，比如把"laravel/framework"写成"laravel/laravel"就会 404 - 运行
composer show vendor/package-name（替换为实际包名）验证包是否存在；若提示 “Package not found”，说明名字错了或已下架 - 某些私有包需配置仓库源，但没在
composer.json或全局 config 里加repositories，也会 404 —— 此时错误信息里通常带https://packagist.org/packages/xxx，而你本该走内网地址
composer update 报 404 Not Found（含 dev-main / dev-develop）
这类错误多发生在依赖指定了开发分支（如 "dev-main"），但对应 Git 仓库里没有该分支，或分支名已改（GitHub 默认分支从 master 改为 main 后，很多旧 composer.json 没同步更新）。
- 进包的 GitHub/GitLab 页面，确认目标分支是否存在；不存在就换用稳定标签，比如把
"dev-main"改成"^3.2" - 如果必须用开发版，且分支名已变，手动在
composer.json中改成新分支名，例如"dev-main"→"dev-mainline"（以实际为准） -
composer update --dry-run可提前暴露哪些包会 404，避免全量失败后还得翻日志
国内访问 packagist.org 超时却显示 404
这不是真 404，是 DNS 或连接中断导致 Composer 误判为“包不存在”。典型表现：同一行命令在公司网络失败，在手机热点下成功。
- 执行
composer config -g repo.packagist composer https://packagist.phpcomposer.com（已停用）或更推荐的：composer config -g repo.packagist composer https://packagist.laravel-china.com（注意这是镜像，仅限 Laravel 相关生态；通用镜像用https://packagist.proxyu.cn） - 验证镜像是否生效：运行
composer config -g repo.packagist，输出应为对象而非字符串 - 如果用了阿里云/腾讯云等私有 Composer 仓库，确保
auth.json的 token 未过期，否则也返回 404（实际是 401 被伪装了）
vendor 目录残留导致 update 时 404
当之前安装过某个包的特定分支，后来删了 composer.json 里的依赖但没清 vendor/，Composer 可能尝试复用旧路径，结果找不到对应元数据而报 404。
- 最稳妥做法：
rm -rf vendor composer.lock，再composer install - 不想重装全部？先
composer remove vendor/package-name，再composer require新版本 - 留意
composer.lock里是否有已失效的 commit hash 或分支引用 —— 手动删掉对应段再重试，比硬删 lock 文件更轻量
404 最容易被当成网络问题去折腾代理，其实九成以上是包名、分支、镜像配置三者之一不匹配。盯住错误信息里那一长串 URL，它暴露的是 Composer 实际请求的地址，而不是你以为它该去的地方。
