90%的“Package not found”源于包未在Packagist注册或Composer未正确使用配置源；需依次验证包名准确性、Packagist存在性、repositories配置（含packagist.org禁用）、镜像可用性及删除composer.lock和vendor重装。
不是镜像挂了，也不是网络问题——90% 的 “Package not found” 是因为 Composer 根本没去你配的源里找，或者那个包压根没在 Packagist 上注册。
确认包是否真在 Packagist 上存在
别信 IDE 补全、聊天记录粘贴、甚至自己记忆里的包名。直接验证：
- 打开
https://packagist.org/packages/vendor/name（把vendor/name换成你写的完整包名），看页面是否返回 404；注意大小写：monolog/monolog✅，Monolog/monolog❌ - 运行
composer search vendor/name—— 如果没结果，说明 Packagist 没收录这个包，不是你本地配置的问题 - 检查是否打错 vendor 名：
spatie/laravel-backup✅，spatie/backup❌；guzzlehttp/guzzle✅，guzzle/guzzle❌（后者已废弃） - 复制包名时小心不可见字符：从网页或微信粘贴容易带零宽空格，建议手动重打一遍
检查 repositories 配置是否生效且顺序正确
composer search 只查 Packagist 全局索引，而 composer require 会严格按 repositories 配置顺序 + minimum-stability + 元数据匹配执行。常见失效原因：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 运行
composer config repositories，输出里如果还包含https://repo.packagist.org，说明官方源没禁用，私有源再靠前也白搭 -
{"packagist.org": false}必须是repositories数组里的一个**独立对象**，且必须放在数组末尾，不能嵌套、不能写成"packagist": false - VCS 类型仓库必须写
"type": "vcs"，URL 必须是合法 git 地址（如https://github.com/user/repo.git），结尾不能带#main或其他路径 - 目标仓库根目录的
composer.json中name字段必须与require里写的**完全一致**（包括大小写和连字符）
镜像源配置错误导致静默 fallback 到 packagist.org
Composer 2.2+ 对镜像配置极其敏感，写错一点就静默回退到官方源，然后报 404：
- 运行
composer config -g repo.packagist，必须看到类似{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}的完整 JSON 输出；如果返回null、空行、或https://packagist.org，说明配置根本没生效 - 常见错误：漏掉
-g、URL 少末尾/（变成/composerpackages.json）、键名写成repos.packagist或repositories.packagist - 用
curl -I https://mirrors.aliyun.com/composer/packages.json实测响应：必须是HTTP/2 200；返回 404、301、HTML 页面或超时，说明镜像本身不可用 - 清华、腾讯、阿里等镜像地址必须完整带
/composer/，且 URL 末尾要有/
删 lock 和 vendor 比清缓存更关键
composer clear-cache 只清下载缓存，不碰元数据；而 composer.lock 里硬编码了 provider 地址（比如 https://packagist.org/p2/xxx.json）。换镜像后 Composer 仍会优先请求这个旧 URL —— 它早就不通了：
- 第一步永远是
composer clear-cache（必须做，但不够） - 第二步删掉
vendor/和composer.lock（尤其composer.lock，它锁死了过期的元数据路径） - 第三步再跑
composer install；别用update替代，它可能复用 lock 里已失效的 provider 地址 - CI 环境下必须加缓存配置（如 GitHub Actions 的
cache: $HOME/.composer/cache），否则每次都是干净容器，DNS 不稳 + 无缓存 = 高概率 404
最常被忽略的是：包名拼错、repositories 里 packagist.org 没关、composer.lock 里残留旧 provider 地址——这三者加起来占所有“Package not found”的八成以上。验证顺序错了，后面所有操作都是白忙。
