Composer指定依赖分支与开发版本中文引用配置

先说几个开发者常碰到的问题：用 Composer 拉取开发分支，看似简单，实际上一不注意就会报错。最直接的方式——composer require vendor/name:dev-main——看起来简单，但说实话，第一次几乎都会踩坑。要么是分支名写错，要么是稳定性没放开，要么是私有库的源没配好，总之，Composer 就是不给面子。

composer require 怎么写才能装对 dev 分支

最简洁的方式是 composer require vendor/name:dev-main，但几乎每次失败都是因为三个条件没同时满足：分支名必须和远端 Git 仓库一字不差（大小写、斜杠都不能错），加 --stability=dev 或 @dev 后缀，私有库还得在 repositories 里声明 vcs 类型。

最常见的报错是 Could not find package vendor/name at version dev-main。这通常意味着：远端根本没有 main 分支（可能是 develop 或 master），或者你写成了 dev-Main（大小写不一致），又或者没加 --stability=dev，Composer 压根不进入解析流程。

• 分支名带斜杠（比如 feature/login）必须用双引号包裹：composer require "vendor/name:dev-feature/login" --stability=dev
• 别省略 dev- 前缀，composer require vendor/name:feature/login 会被当成版本号解析，大概率报错
• 现在 GitHub 新仓库默认分支是 main，如果你还写 dev-master，那肯定失败

私有 Git 仓库怎么指定分支

包没在 Packagist 上注册，Composer 当然不知道从哪拉代码，repositories 配置就必不可少。type 必须是 vcs，URL 必须带 .git 后缀，否则解析失败。

直接看配置示例（写在项目根目录 composer.json 的顶层）：

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://gitlab.example.com/acme/utils.git"
    }
  ]
}

配好之后，再执行 composer require acme/utils:dev-main --stability=dev。如果 URL 是 SSH 地址（比如 git@gitlab.example.com:acme/utils.git），确认运行命令的机器已经配好对应的 SSH key。

• 没配 repositories 就执行 require，必然报错 Could not find a version of package
• url 字段漏掉 .git 后缀，Composer 会尝试走 HTTP 协议探测，多数情况超时或返回 404
• 多个私有源要并列写在 repositories 数组里，不能嵌套

怎么让分支依赖锁定到具体 commit

默认 dev-main 是浮动的，composer update 会拉该分支最新提交。生产环境必须锁定，否则上游 force push 会导致下次 install 失败——composer.lock 里存的旧 hash 找不到，直接崩。

可靠写法是显式带上 # 和 commit hash："acme/utils": "dev-main#abc1234"。注意 hash 至少 7 位小写，不能写成 HEAD 或 main。

• 加 --prefer-source 参数确保走 Git 克隆（而非 zip 包），否则 #hash 可能被忽略
• 验证是否真锁住：检查 composer.lock 中该包的 source.reference 字段，值必须是 40 位或至少 7 位小写哈希
• 手动改完 composer.json 后，必须运行 composer update acme/utils，仅 install 不会更新 lock 文件

branch-alias 是什么，什么时候要用

branch-alias 是被依赖方（即你要引用的那个包）自己声明的映射规则，目的是让其他项目能用语义化版本（如 ^2.0）来依赖它的开发分支。它只在被依赖方的 composer.json 里生效，且只对 dev- 开头的分支起作用。

正确写法（放在被依赖包的 composer.json 的 extra 下）：

{
  "extra": {
    "branch-alias": {
      "dev-main": "2.0.x-dev"
    }
  }
}

依赖方写 "acme/utils": "^2.0" 才会命中这个别名。如果依赖方直接写 "acme/utils": "dev-main"，别名完全不参与解析。

• 别名末尾必须带 -dev，写成 "2.0.x" 会被忽略
• 本地用 path 类型仓库时，branch-alias 不生效——这是设计限制，只用于 VCS 场景
• 别名配了但没效果？先确认目标分支已 git push 到远程，且 Packagist 或私仓已完成索引

实际落地时，最容易被忽略的是三件事：分支名和远程仓库必须一字不差（包括大小写）、私有源的 repositories 配置必须带 .git 后缀、以及 composer.lock 里 source.reference 的值必须是 commit hash 而不是分支名。这三个细节搞定了，Composer 基本就不会给你惹麻烦。