唯一可靠方式是dev-branch#commit-hash格式，因composer仅此语法触发vcs强制检出指定commit；@会被误解析为分支名，短哈希不唯一，且需40位完整哈希、真实分支名及vcs源支持。

直接写 dev-main#abc123 就能锁定特定 commit，但必须满足三个硬性条件：包源是 VCS 类型、commit 已推送到远程、composer.json 里 name 字段和 require 中的包名完全一致——缺一不可。

为什么 composer require vendor/name:dev-main#abc123 总报错？

根本原因不是命令写错了，而是 Composer 的 require 命令根本不解析 # 后面的内容。它只把 dev-main 当作版本约束，#abc123 被忽略或触发非法版本字符串错误。

• 正确做法是手动编辑 composer.json 的 require 段，写成："vendor/name": "dev-main#abc123"
• 然后运行 composer update vendor/name（不是 install）
• 如果该包已存在于 vendor/ 中，得先删掉对应目录和 composer.lock 里该包的整段记录，否则缓存会跳过拉取
• 私有仓库还要确认 auth.json 里有对应 token，否则可能静默 fallback 到旧 commit

dev-main#abc123 和 repositories + reference 选哪个？

日常开发用前者足够；CI/CD 或生产部署强烈推荐后者，因为更可控、不依赖分支头状态。

Convert Github Repository

适用于以下场景：（1）用户提供 GitHub 仓库 URL 或本地仓库路径，并请求将其转换为其他格式；（2）用户请求导出 GitHub 仓库……

下载

• dev-main#abc123：hash 可缩写（7 位起），Composer 自动补全；但要求 main 分支存在且该 commit 在其历史中可达
• repositories + reference：必须用完整 40 位 SHA-1，且要额外加 package 配置块，例如：

  "yourname/package": {
    "version": "dev-main",
    "reference": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890"
  }

• 执行 composer update yourname/package 才生效；install 只读 lock 文件，不会重新解析 reference
• 好处是绕过 Packagist 的版本别名系统，直连 Git 引用，避免 force-push 导致分支头偏移带来的不确定性

怎么验证实际装的是不是你指定的 commit？

别信 composer show 输出的 dev-main，它掩盖了真实 hash。

• 进 vendor/vendor/name/.git/ 目录，运行 git rev-parse HEAD
• 查 composer.lock 里该包的 source.reference 字段，值必须是 40 位小写 hex 字符串，而不是 main 或 dev-main
• 如果 source.type 是 git 但 reference 是分支名，说明 commit 锁定根本没生效——大概率是 composer.json 格式写错，或执行了 install 而非 update
• GitHub 返回的 hash 全小写，建议统一用小写，某些镜像服务对大小写敏感

最易被忽略的一点：即使所有配置都对，如果目标 commit 所在分支被 force-push 覆盖，下次 composer install 仍可能失败——因为 source.reference 指向的 commit 在远程已不可达，Git fetch 会直接报错。