Composer 直接 require GitHub 仓库失败，根本原因是未在 composer.json 顶层配置 type="vcs" 的 repositories 源，且包名必须严格匹配私有库内部 composer.json 的 name 字段，同时需处理 dev-main 稳定性限制与认证凭据问题。
直接用 composer require 拉 GitHub 仓库，行不通——除非你提前在 composer.json 里配好 repositories，且包名、版本、认证三者全部对齐。Composer 不会自动从 GitHub URL 推导包信息，它只认 name 字段和明确的版本约束。
为什么 composer require username/repo 总报 “Could not find package”
这不是网络或权限问题，而是 Composer 根本没去你的 GitHub 地址找——它默认只查 packagist.org。你漏了最关键的一步：声明仓库源。
-
repositories必须写在项目根目录的composer.json顶层，不能嵌套在config或其他字段下 - 类型必须是
"type": "vcs"，不是"git"、"package"，也不是空着 -
url值要是完整可git clone的地址，例如"https://github.com/your-org/your-package"（注意不带.git后缀） - 如果仓库是私有的，HTTPS 方式需提前配置 Git 凭据（
git config --global credential.helper store），SSH 方式则必须确保ssh -T git@github.com能通
dev-main 装不上？其实是稳定性策略卡住了
报错提示 “no matching package found”，大概率不是仓库地址错了，而是 Composer 默认拒绝安装开发版（dev- 开头的分支）。它需要你显式允许。
- 最稳妥的做法：在
composer.json顶层加"minimum-stability": "dev"，同时建议加"prefer-stable": true避免其他依赖也被降级 - 如果只想让某一个包走
dev-main，其他保持稳定，就别动全局配置，改用别名写法："your-org/your-package": "dev-main as 1.0.0" -
dev-main不代表“实时最新”——它只是锁定到执行composer install那一刻的main分支 HEAD 提交，后续composer update才会拉新
私有仓库的 name 字段必须和 require 里写的完全一致
这个匹配是大小写敏感、斜杠方向严格、vendor 名一字不差的字符串比对。Composer 不会从 GitHub 路径（如 github.com/your-org/your-package）推导包名，它只读取仓库内部 composer.json 的 "name" 字段。
- 假设私有库的
composer.json里写的是"name": "YourOrg/utils"，那require中就必须写"YourOrg/utils"，写成"yourorg/utils"或"your-org/utils"都会失败 - 没有
"name"字段的私有仓库，Composer 直接拒绝安装，不会报具体错误，只会卡在 “Could not find package” - GitHub Packages（
ghcr.io）场景下，包名还必须含组织名前缀，比如"your-org/your-package"，不能省略your-org/
HTTPS 还是 SSH？选错认证方式会导致静默卡住
HTTPS 地址看似简单，但在 CI 或无交互环境里极易失败；SSH 更可靠，但配置稍重。关键不是协议本身，而是凭据是否被 Composer 的 Git 子进程真正拿到。
- HTTPS 方式下，不要把 token 硬编码进
url（如https://token@...），既不安全又容易过期；推荐用git config --global credential.helper store+ 一次手动git clone缓存凭据 - SSH 方式必须用
git@github.com:your-org/your-package.git格式，且~/.ssh/id_ed25519已存在、权限为600、公钥已添加到 GitHub - CI 环境中，HTTPS 推荐用
COMPOSER_AUTH环境变量注入 JSON 凭据，SSH 则用ssh-agent注入私钥 - 无论哪种方式，先在本地跑通
git clone <url>，再试 Composer —— 如果 Git 都克隆不了，Composer 必然失败
最容易被忽略的点是：每次改完 repositories 或 require，都得清缓存再试——composer clear-cache。缓存可能记住了旧的失败状态，导致你改对了配置，却仍看到同样的报错。
