根本原因是显式声明repositories会完全忽略packagist.org，必须在数组首项设"packagist": false并手动添加"type": "composer"的官方源条目，否则连monolog等公共包都无法解析。
composer.json里写了repositories但还是找不到包
根本原因不是“没配”，而是配置覆盖了默认源——只要你在repositories里显式声明了任何源（哪怕只加了一个私有 Git 地址），Composer 就会**完全忽略 packagist.org**，除非你手动把它加回来。
常见错误写法：
"repositories": [
{
"type": "vcs",
"url": "https://github.com/myorg/internal-tool"
}
]
这段代码会让 Composer 只查你的 GitHub 仓库，连 monolog/monolog 都搜不到。
- 修复方式：显式补上 packagist 官方源，且必须设
"packagist": false关闭自动注入，再手动加一条"packagist.org"条目 - 正确配置示例：
"repositories": [
{
"packagist": false
},
{
"type": "composer",
"url": "https://packagist.org"
},
{
"type": "vcs",
"url": "https://github.com/myorg/internal-tool"
}
]
注意："packagist": false 必须是第一条，否则无效；"type": "composer" 是唯一能正确加载 Packagist 元数据的方式，不能用 "type": "package" 或 "type": "artifact" 替代。
用了国内镜像却提示包不存在
国内镜像（如阿里云、腾讯云）不是实时同步的，尤其新发布的包或刚打 tag 的版本，可能延迟数小时甚至一天。你看到 Packagist 页面上已有 v3.2.0，但在镜像里 composer show vendor/package 仍返回空，就是这个原因。
验证方法：
- 临时切回官方源：
composer config --unset repos.packagist（清空项目级镜像） - 或直接指定：
composer config repo.packagist composer https://packagist.org - 再运行
composer clear-cache && composer show vendor/package
如果这时能查到，说明就是镜像延迟；如果还查不到，问题不在镜像，得继续往下排查。
私有 Git 包 require 后报 “Could not find package”
不是地址写错，而是 Composer 默认不扫描 Git 仓库的分支/Tag，除非它在 composer.json 里明确声明了 "name" 和 "version"，或者你启用了 "dist" 模式且镜像已缓存。
典型失败场景：
- 你 fork 了一个开源包，改了
composer.json里的"name"，但没 push tag，只推了main分支 → Composer 不认dev-main，除非你加@dev - Git 仓库根目录下没有
composer.json，或文件里缺"name"字段 → Composer 直接跳过该仓库 - 用了 SSH 地址（
git@github.com:xxx/yyy）但本地没配 SSH key 或~/.ssh/config主机别名 → 报错看起来像“找不到包”，实际是 clone 失败
调试命令：composer -v require vendor/package，看输出里有没有 Skipped branch main 或 Failed to download 这类线索。
为什么 composer search 能搜到，require 却报错
composer search 只查 Packagist 的元数据索引，不校验你的环境；而 composer require 会走完整依赖解析流程——包括 PHP 版本、扩展、conflict 声明、platform 配置，最后才匹配版本。
也就是说：搜得到 ≠ 装得上。
- 最常被忽略的一点：
config.platform.php锁死了 PHP 版本（比如设成"8.0.0"），而你要装的包只支持^8.1→ Composer 直接过滤掉所有可用版本，报错伪装成“找不到” - 另一个隐形坑：
conflict字段。比如你已装symfony/consolev5.4，而新包声明"conflict": {"symfony/console": "^6.0"}，它其实没冲突，但 Composer 解析器会误判为“无解”，最终报“no matching package” - 验证手段：
composer prohibits vendor/package比why-not更直给，它列出所有拦路的现有依赖及其约束链
真正卡住安装的，往往不是仓库地址，而是你项目里已经存在的某行配置、某个已装包、甚至 php.ini 里没开的一个扩展——这些都不会出现在错误信息第一行，得往日志深处翻。
