先验证包是否真实存在：访问https://packagist.org/packages/vendor/name确认页面可打开，再用composer search vendor/name和检查包名大小写、不可见字符；若存在则排查镜像失效、同步延迟、缓存残留或repositories配置错误。
直接验证包是否存在，别信错误提示
“Package not found”不是网络故障，是 Composer 明确告诉你：它查了所有配置的源，没找到匹配项。错误信息不区分“真不存在”和“源没生效”，所以第一步永远是人工确认包是否真实发布。
打开 https://packagist.org/packages/vendor/name（把 vendor/name 换成你实际要装的），看是否返回 404 页面；如果页面能打开，说明包存在，问题出在本地配置或镜像同步上。
运行 composer search vendor/name —— 它只查 Packagist 全局索引，不走你配的 repositories，也不校验稳定性。如果搜不到，基本可断定包名拼错、大小写不对，或根本没提交到 Packagist。
- 复制包名时小心不可见字符（比如从微信/网页粘贴带零宽空格）
-
monolog/monolog对，Monolog/monolog或monolog/Monolog错 -
spatie/laravel-backup对，spatie/backup错
检查 repositories 配置是否真正生效
Composer 查源是「顺序匹配 + 命中即停」，但前提是 packagist.org 被显式禁用。否则它永远先查官方源兜底，你写的私有源或镜像再靠前也白搭。
运行 composer config repositories，输出里如果还包含 https://repo.packagist.org，说明禁用失败。正确配置必须满足两个条件：
-
{"packagist.org": false}是repositories数组里的一个独立对象 - 它必须放在所有自定义源之后、数组末尾（不能放开头，也不能嵌套进其他仓库对象里）
- 写成
"packagist": false或"packagist.com": false会被静默忽略
私有 VCS 仓库（如 Git）不参与全局索引，composer search 找不到它很正常；但 composer require 时若报 404，大概率是元数据读取失败——先用 curl -I <code>your-vcs-url/composer.json 测试 URL 是否可访问、返回 200。
排除镜像同步延迟与缓存污染
国内镜像（阿里云、腾讯云等）不是实时全量同步，尤其对刚发布的包、dev-main 分支、或含非标准 LICENSE 的包，极易返回 provider-2025-10.json 404。
临时切回官方源验证是最有效手段：
- 执行
composer config -g repo.packagist composer https://packagist.org - 紧接着运行
composer clear-cache（不清理缓存，旧地址仍会复用） - 再试
composer require vendor/name
注意：Laravel China 镜像已于 2023 年底停用，还在用必报错；运行 composer config -g repo.packagist 确认当前值不是 https://packagist.phpcomposer.com 这类已失效地址。
别让 -w 参数干扰判断
composer require vendor/name -w（即 --with-dependencies）会让 Composer 强制解析整个已安装依赖树，再尝试合并新包约束。一旦某个已有包锁定了过老的子依赖版本，而你要装的包要求更高版本，Composer 就可能放弃安装，并报 “Package not found”——它其实是“无法满足依赖”，但错误信息完全没提冲突。
日常新增包，根本不需要加 -w。遇到报错，第一反应是去掉它重试：
- 改用
composer require vendor/name（不带-w） - 若必须升级整条链，先跑
composer update --dry-run看具体哪条约束卡住 - 旧版 Composer（尤其 1.x）对
-w处理更激进，建议升级到 2.x
最常被忽略的是：minimum-stability 默认为 stable，而你想装的包只有 dev-main 或 beta 版本，它就直接跳过，不报“版本不匹配”，只报“not found”。这种时候，--stability=dev 或临时设 "minimum-stability": "dev" 才是解法。
