答案是先验证包是否真实存在：访问https://packagist.org/packages/vendor/name确认页面可打开，再用composer search vendor/name和检查包名大小写、不可见字符；若存在则排查镜像失效、同步延迟、缓存残留或repositories配置错误。
确认包名是否真实存在且拼写正确
Composer 报 “Could not find package” 时，第一反应不该是换镜像或清缓存，而是验证这个包到底有没有、名字对不对。访问 https://packagist.org/packages/vendor/name（把 vendor/name 换成你实际写的包名），如果页面返回 404，说明 Packagist 上压根没收录它。
用命令行交叉验证：composer search vendor/name。没输出结果？那基本可以排除网络或配置问题，就是包不存在或名字错了。
- 大小写敏感：
monolog/monolog对，Monolog/monolog错 - vendor 名不能少或错：
spatie/laravel-backup对，spatie/backup错 - 复制包名时容易带入零宽字符或全角空格——建议手动重打一遍，别粘贴
检查当前生效的仓库源和优先级
composer config repositories 输出的是当前项目级生效的源列表，但要注意：它可能被全局配置覆盖，也可能因 {"packagist.org": false} 缺失而失效。
运行 composer config -g repo.packagist 查全局镜像地址，确认不是已停用的旧地址（如 https://packagist.phpcomposer.com）。Laravel China 镜像早在 2023 年底就停了，还在用必报 404。
- 私有源要生效，必须显式关闭官方源：
{"packagist.org": false}必须是repositories数组里的一个独立对象 - 它必须放在数组末尾，不能嵌套在其他仓库配置里
- 顺序决定查找路径：Composer 从上到下匹配，命中即停——但前提是
packagist.org已被禁用
区分 composer search 和 composer require 的行为差异
composer search 只查 Packagist 全局索引，不校验 PHP 版本、扩展、稳定性或你本地的 repositories 配置；而 composer require 是真安装，会严格按 repositories 顺序 + minimum-stability + 实际元数据匹配执行。
常见假阳性：composer search myorg/utils 成功，不代表你能装——可能只是 Packagist 上有个同名空包，你的私有源根本没被访问。
- 包只有
dev-main版本，但项目设了"minimum-stability": "stable"→ 直接跳过，报 “not found”，不是 “版本不匹配” - 加了
-w（--with-dependencies）反而找不到？那是依赖冲突被误报为 “not found”，先去掉重试 -
composer update --dry-run -v能看到真实解析过程，比报错信息更准
验证镜像同步状态与本地元数据缓存
包在 Packagist 官网能打开，但 composer require 还是 404，大概率是镜像没同步或本地缓存没刷新。
直接浏览器访问镜像的包元数据地址：https://mirrors.aliyun.com/composer/p/vendor/package-name.json。如果返回 404 或内容里没有你要的版本，就是镜像延迟（通常 5–30 分钟）。
-
composer clear-cache不会强制重新拉取packages.json，它只清 ZIP 和部分过期缓存 - 真正要删的是缓存目录下的镜像子路径，比如：
rm -rf ~/.composer/cache/repo/https---mirrors-aliyun-com-composer - 临时切回官方源验证最可靠：
composer config -g repo.packagist composer https://packagist.org，再跑composer require vendor/name -vvv
最容易被忽略的一点：项目根目录下的 composer.json 里如果写了 repositories 字段，它会覆盖全局配置，但很多人没意识到这个字段本身可能语法错误、type 写成 vcs 却漏了 url，或者 URL 格式非法——这种情况下 Composer 会静默忽略整个块，继续查默认源。
