必须显式配置repositories为vcs类型并指定带.git后缀的URL，同时加-s dev参数或设minimum-stability为dev，否则Composer无法解析私有库或新分支的元数据。
直接写 composer require vendor/name:dev-branch-name 是最常用方式，但**90% 的失败不是语法错，而是 Composer 没法解析到那个分支的元数据**——尤其当你面对私有库、新 fork、或分支刚推上去还没被 Packagist 索引时。
为什么 composer require vendor/name:dev-main 报 “Could not find package”
这个错误几乎从不因为拼写错误，而是 Composer 默认只查 Packagist 上已注册的稳定版本。哪怕 GitHub 仓库真实存在 main 分支，只要它没在 Packagist 公开注册，或者你用的是私有地址，Composer 就会直接放弃查找。
- 确认该包是否在 Packagist 注册：如果没注册，必须手动加
repositories声明源 - 检查分支名大小写和拼写：GitHub 默认分支是
main，不是master；Dev-main或dev-Main都无效 - 私有仓库必须用 HTTPS 或 SSH 地址，并确保能本地
git clone通（比如git clone https://github.com/your-org/private-repo.git） - 如果用了
git@地址，确认 SSH key 已加载：ssh -T git@github.com应返回成功
私有 GitHub 仓库必须配 repositories 且 type 必须是 vcs
光写 "myorg/private": "dev-main" 没用。Composer 不知道去哪找这个包，必须显式告诉它：“这是一个 Git 仓库，地址在这里”。
在 composer.json 的根级加：
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/myorg/private-repo.git"
}
]
}
关键点：
-
type必须是vcs（不是package或path），否则分支解析完全失效 -
url必须带.git后缀，https://github.com/myorg/private-repo（缺后缀）会导致克隆失败 - 若仓库需要认证（如私有 repo），HTTPS 地址需带 token：
https://token:x-oauth-basic@github.com/myorg/private-repo.git
dev-branch#commit-hash 才真正锁定代码，dev-branch 是浮动的
写 "monolog/monolog": "dev-main" 看似装了 main 分支，其实每次 composer install 都可能拉到不同 commit —— 因为它是“最新 HEAD”，不是固定点。CI 构建失败、本地与线上行为不一致，基本都源于此。
真正可控的做法是带上 commit hash：
-
"myorg/tool": "dev-main#abc123456789"：锁定main分支的某次提交 -
"myorg/tool": "dev-feature/login#def7890"：锁定带斜杠的分支，hash 必须是完整 40 位 SHA1（可用git rev-parse HEAD获取） - 分支名含斜杠时，
dev-前缀后直接跟原始路径，不用 URL 编码（dev-feature/login✅，不是dev-feature%2Flogin）
验证是否生效：运行 composer show myorg/tool，看 source 行是否显示你指定的 commit 和 branch；或进 vendor/myorg/tool/.git/HEAD 查当前检出状态。
命令行安装必须加 -s dev，否则默认不认 dev- 前缀
composer require myorg/tool:dev-main 单独执行会失败，除非项目 composer.json 中已设 "minimum-stability": "dev"。更安全的做法是临时启用开发版解析：
-
composer require myorg/tool:dev-main -s dev：只对本次安装生效，不改composer.json - 加了
-s dev后，Composer 才会去查repositories里声明的 VCS 源，并尝试解析dev-main对应的分支信息 - 如果项目已有
"minimum-stability": "stable"，不加-s dev就无法安装任何dev-版本，无论是否配了repositories
装完后，composer.json 里会自动写入 "myorg/tool": "dev-main"（或带 hash 的版本），但 minimum-stability 不变——下次 composer update 仍需 -s dev 才能升级该依赖。
最容易被忽略的是缓存：即使你改了 dev-main#newhash，Composer 可能仍用旧 commit。强制刷新用 composer clear-cache && composer update myorg/tool --no-cache，而不是反复 require。
