composer无法直接为分支授予权限，权限控制仅到仓库或包级别；需确保repositories配置正确、auth.json严格匹配host:port、私有库name与require完全一致、url含.git后缀且禁用packagist.org。
不能直接为“分支”授予权限，Composer 的权限控制粒度只到仓库（repository）或包（package）级别，分支本身不构成独立访问单元。真正要做的，是让 Composer 能安全拉取那个分支所在的私有仓库。
为什么 dev-branch-name 会失败：认证和源配置被跳过
当你在 require 中写 "acme/utils": "dev-main" 却提示 Could not find package 或静默回退到 Packagist，大概率不是分支名错了，而是以下任一环节失效：
-
repositories没放在composer.json顶层，而是塞进了config或scripts里 - 漏写了
"type": "vcs"—— Composer 不识别"url": "https://gitlab.example.com/acme/utils.git"这种裸 URL - 没禁用默认源：
"packagist.org": false缺失，导致同名公开包优先命中 - URL 缺
.git后缀，git clone直接失败，但 Composer 不报错
auth.json 必须严格匹配 host + 端口，否则静默忽略
哪怕你用的是 GitLab 自托管实例 gitlab.example.com:8080，auth.json 里的域名 key 就必须带端口，少一个字符都不行：
{
"http-basic": {
"gitlab.example.com:8080": {
"username": "token",
"password": "glpat-xxxxxx"
}
}
}
常见错误：
- 把
auth.json放在项目根目录（应放~/.composer/auth.json） - Linux/macOS 下没执行
chmod 600 ~/.composer/auth.json，文件权限 >600 就被跳过 - 用了
gitlab-token或oauth字段名 —— Composer 只认http-basic
require 中的包名必须和私有库 composer.json 的 name 完全一致
Composer 查包不看 Git 地址，只比对私有仓库根目录下 composer.json 里的 name 字段。比如私有库中写的是：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{ "name": "acme/utils", "version": "dev-main" }
那么你的主项目 composer.json 中就必须写：
- ✅
"acme/utils": "dev-main" - ❌
"Acme/utils": "dev-main"（大小写敏感） - ❌
"acme-utils": "dev-main"（连字符 ≠ 斜杠） - ❌
"utils": "dev-main"（vendor 段不可省略）
分支名前的 dev- 前缀也不能省；写成 "main" 或 "*" 会被当作模糊约束，触发 Packagist 回退。
更新指定分支时别误用 composer require
想把已安装的 acme/utils 从 dev-main 切到 dev-feature/x，正确做法是：
- 改
composer.json的require行为"acme/utils": "dev-feature/x" - 运行
composer update acme/utils（不是require）
composer require acme/utils:dev-feature/x 会重写版本约束，但不会强制重新解析 VCS 源 —— 如果锁文件里还存着旧 commit，它可能直接复用，根本不会拉新分支。
最易被忽略的点：所有配置项（repositories.url、auth.json 的域名 key、私有库 composer.json 的 name）必须字面完全一致，包括大小写、端口、斜杠、.git 后缀。Composer 不报错，只沉默跳过 —— 你以为它在拉分支，其实它连 Git 服务器都没连上。
