很多人在用 Composer 安装开发分支时，第一反应就是敲一句 composer require vendor/name:dev-branch-name。但真正执行下去，十有八九会撞上“Could not find package”的错误。问题往往不是命令写错了，而是 Composer 在背后有一套默认的稳定性策略、仓库解析逻辑和分支命名规则。
先记住一个核心判断：直接用 composer require vendor/name:dev-branch-name 是能装的，但 90% 的失败不是命令写错，而是没处理好稳定性策略、仓库源或分支命名规则。
为什么 composer require vendor/name:dev-main 报 “Could not find package”
Composer 默认只允许安装 stable 版本，dev- 开头的版本被当作开发版，必须显式允许。常见错误包括：
- 没加
--stability=dev（或简写-s dev），导致 Composer 直接跳过匹配 - 包不在 Packagist 上注册，但又没在
composer.json的repositories里声明vcs源 - 分支名大小写不一致 ——
dev-Main和dev-main是两个不同分支，Git 区分大小写 - 远程仓库根本没有
main分支，或者拼错了（比如写成master但对方已切到main）
dev-feature/login 这种带斜杠的分支怎么写
Composer 强制要求斜杠分支必须写成 dev-feature/login，不能省略 dev-，也不能把斜杠替换成短横线或下划线。
- 正确：
composer require myorg/sdk:dev-feature/auth - 错误：
composer require myorg/sdk:feature/auth（会被当作文本版本号解析失败） - 错误：
composer require myorg/sdk:dev-feature-auth（找不到对应 Git 分支） - 如果分支名含特殊字符（如空格、中文），基本不可用 —— Git 本身就不鼓励这类命名，Composer 更不会支持
怎么确保拉到的是最新 commit，而不是缓存旧版本
Composer 对 dev- 分支默认走 dist 缓存，install 不会重新 fetch，哪怕远程分支已经 force-push 过。
- 执行
composer update vendor/name，比require更可靠，update 会强制重解析分支 HEAD - 加
--prefer-source参数，让 Composer 克隆完整 Git 仓库而非下载 zip，后续可手动git pull - 加
--no-cache或先运行composer clear-cache，清除可能污染的 dist 包缓存 - 最稳的方式是锁定提交哈希：
"vendor/name": "dev-main#abc1234"，这样无论远程怎么变，本地都固定在那一版
私有仓库或 fork 怎么指定分支安装
光写 vendor/name:dev-branch 不够，Composer 不知道从哪拉代码，必须提前声明 repositories。
- 在
composer.json中添加：{"type": "vcs", "url": "https://github.com/your-fork/repo.git"} url必须是可访问的 Git 地址（HTTPS 或 SSH），且该仓库根目录必须有合法的composer.json，其中name字段要和require里的完全一致（包括大小写）- 如果用
path类型 repository（比如指向本地目录），dev-分支完全无效 —— 它只是硬链接，切换分支需删掉vendor/name再update - 别指望
git@地址自动识别：虽然支持，但若 SSH key 配置不对或网络不通，会静默 fallback 到 Packagist，导致装错包
真正麻烦的不是语法，而是 Composer 在 stability、cache、vcs 解析、lock 文件更新之间做的隐式决策。一个 dev-main 表面简单，背后可能触发四层策略判断 —— 所以出问题时，先看 composer show vendor/name 输出的 actual source 和 commit，再查 vendor/name/.git/HEAD，比反复重试更省时间。
