结论：用 dev-branch#commit-hash 格式写入 composer.json 的 require 并运行 composer update vendor/package 即可精确安装指定 commit；需确保哈希至少 7 位小写、分支名匹配、执行 update 而非 install，并通过 composer.lock 的 source.reference 和 vendor 中 git rev-parse HEAD 验证。

直接说结论：用 dev-branch#commit-hash 格式写进 composer.json 的 require，再运行 composer update vendor/package，就能装上那个确切的 commit —— 不需要插件、不用改全局配置，但必须满足几个硬性前提。

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

因为 composer require 命令不解析 # 后的内容，它只认版本约束字符串。强行输入会触发 Invalid version string 错误。

• 正确做法是手动编辑 composer.json，在 require 里写："vendor/package": "dev-main#abc123"
• 然后执行 composer update vendor/package（不是全量 update，避免连带升级其他包）
• 如果目标 commit 在 feature/login 分支上，就得写成 "dev-feature/login#abc123"，不能硬套 dev-main
• 哈希建议用至少 7 位（如 abc1234），太短可能冲突；大小写统一用小写，某些镜像服务对大小写敏感

repositories + reference 是更稳的私有/ fork 场景方案

当你 fork 了某个包、或用的是内部 GitLab 仓库，且想彻底绕过 Packagist 元数据解析时，显式声明 repositories 更可靠。

GitHub & Developer Data

面向AI代理的GitHub及开发者数据——仓库元数据（星标、语言、许可证）、仓库审计与风险评分、用户资料、最新发布和gist内容...

下载

• 在 composer.json 顶层加：

  "repositories": [
    {
      "type": "vcs",
      "url": "https://gitlab.example.com/your-team/package.git"
    }
  ]

• 同时在 require 下方同级加 package 配置块（不能用 require 直接写）：

  "your-team/package": {
    "version": "dev-main",
    "reference": "a1b2c3d4e5f67890123456789012345678901234567890"
  }

• reference 必须是完整 40 位 SHA-1，缩写会报 Reference "xxx" does not exist
• 执行 composer update your-team/package 才生效；install 只读 composer.lock 里的记录

安装后怎么确认真锁住了那个 commit？

别信 composer show 输出的 dev-main —— 它只是版本别名，掩盖了真实哈希。

• 看 composer.lock 里对应包的 source.reference 字段，值必须是 commit hash，不是 main 或 HEAD
• 进 vendor/vendor/package 目录，执行 git rev-parse HEAD，输出应和 lock 文件里的一致
• 如果 source.type 是 git 但 reference 是分支名，说明没生效，大概率是 composer.json 格式写错，或执行的是 install 而非 update
• CI/CD 中若用了 --no-interaction，要额外检查是否设置了 COMPOSER 环境变量干扰了配置加载

最易被忽略的一点：commit 锁定本质是快照，不是版本。一旦远程分支被 force-push 覆盖掉该 commit，下次 install 就会失败——因为 reference 已不可达。生产环境慎用，临时调试或灰度验证才合适。