composer require 报“package not found”却能在 packagist 搜到，主因是国内镜像源同步延迟；临时可加 --repository=https://packagist.org 验证，或切换更快镜像并清缓存。
为什么 composer require 报 “Package not found” 却能搜到包？
这是 Composer 镜像源同步延迟的典型表现：Packagist.org 上已发布新包或新版本，但国内镜像（如阿里云、腾讯云、华为云）尚未同步。Composer 默认走镜像源，查不到就直接报错，不会 fallback 到官方源。
常见现象包括：
- 在 packagist.org 能搜到
monolog/monolog的v3.5.0，但composer require monolog/monolog:^3.5提示Could not find package monolog/monolog -
composer show列不出刚发布的包，但curl https://www.php.cn/link/5d2e892c81e5fafc51ab0973879563a0packages/xxx/yyy.json返回 200 - 公司私有 GitLab 包已打 tag 并配置了 composer repository，但本地
composer update仍拉不到
临时绕过镜像：用 --repository 指定官方源
不改全局配置，只对当前命令生效，适合验证是否为镜像延迟导致的问题：
composer require monolog/monolog:^3.5 --repository=https://packagist.org
这个参数会临时覆盖 repositories 配置，强制走官方源。如果此时成功，基本可锁定是镜像同步滞后。
注意：
-
--repository后必须是完整 URL，不能是别名（如packagist） - 若项目中定义了私有仓库（
type: vcs或type: composer），该参数不影响它们 - 不推荐长期使用——官方源慢且无 CDN，可能触发 rate limit
检查并切换镜像源：确认当前源 + 手动刷新
先看 Composer 正在用哪个源：
composer config --list | grep repos.packagist
输出类似 repos.packagist = {'url': 'https://mirrors.aliyun.com/composer/', 'type': 'composer'}，说明已切镜像。
若想立刻获取最新包，可手动切回官方源（仅限调试）：
composer config repo.packagist composer https://packagist.org
或者换一个同步更及时的镜像（例如华为云通常比某些小众镜像快 1–2 小时）：
composer config repo.packagist composer https://repo.huaweicloud.com/php-composer/
执行后建议运行 composer clear-cache，避免本地缓存干扰判断。
私有包 / Git 仓库同步失败？重点检查 composer.json 的 packages 字段
如果是自建 Git 仓库（GitHub/GitLab）发布的包，Package not found 很可能不是源同步问题，而是 Packagist 未抓取到新 tag 或 composer.json 缺失关键字段。
确保你的 composer.json 中包含：
-
"name"：格式必须为vendor/name，且全小写（MyOrg/MyLib❌ →myorg/mylib✅） -
"type"：非空字符串（如library），否则 Packagist 忽略该包 - Git 仓库已打语义化 tag（
v1.0.0，不是1.0.0或release-1.0） - Packagist 项目已启用 auto-update（Webhook 已配置，或手动点击 “Update”）
验证方式：访问 https://www.php.cn/link/5d2e892c81e5fafc51ab0973879563a0packages/{vendor}/{name}，看页面是否显示“Last update”时间，以及是否有对应版本号。
同步延迟本身不可完全规避，但镜像源选择、缓存清理、私有包元数据校验这三步漏掉任何一环，都会让问题更难定位。
