Composer 支持通过 commit hash 精确安装 Git 仓库特定提交，推荐写法为 "vendor/package": "dev-main#abc1234"；若用 reference 字段则需完整 40 位 SHA-1，并配合自定义仓库配置，且安装依赖需执行 composer update。
直接写 commit hash 到 version 字段就能装特定提交
Composer 不需要额外插件或 hack，只要在 composer.json 的 version 字段里填 Git 提交哈希（完整或缩写均可），它就会拉取那个确切的 commit。前提是包源是 Git 仓库（如 GitHub、GitLab），且该 commit 在目标分支/历史中可达。
- 必须用
"dev-<em>分支名</em>"作为包的版本约束前缀，例如"dev-main"或"dev-master"，再配合reference或直接写 hash - 推荐写法：在
require中指定"vendor/package": "dev-main#abc1234"—— 这里的abc1234是提交哈希缩写，Composer 会自动解析为完整 hash 并检出 - 如果写成
"dev-main#v1.2.3"，它会找 tag；写成"dev-main#abc1234"，才找 commit - 注意大小写：GitHub 返回的 hash 全小写，但 Git 本身不区分，不过 Composer 解析时建议统一用小写，避免某些镜像服务校验失败
用 reference 字段显式指定 commit 更稳定
当包不在 Packagist 上、或你 fork 后想固定某个私有提交时，repositories + reference 是更可控的方式。它绕过版本别名解析，直连 Git 引用。
- 在
composer.json中添加自定义仓库："repositories": [ { "type": "vcs", "url": "https://github.com/yourname/package" } ] - 然后 require 它，并在
require同级加package配置块（需使用composer require --no-update后手动编辑，或直接写）："yourname/package": "dev-main", "yourname/package": { "version": "dev-main", "reference": "a1b2c3d4e5f67890..." } -
reference值必须是完整 40 位 SHA-1 hash（Composer 不接受缩写），否则安装时报错Reference "xxx" does not exist - 执行
composer update yourname/package才会真正应用该 reference；install只读composer.lock里的记录
常见错误：hash 拉不到、提示 “does not exist” 或 “could not be found”
这类报错几乎都和 Git 引用解析路径有关，不是网络或权限问题。
- 检查目标 commit 是否在远程默认分支上：Composer 默认只 fetch
origin/HEAD对应的分支（通常是main或master），如果 commit 只在feature/x分支而你写的是dev-main#abc1234，就会失败 - 确认 remote URL 可访问且未被重定向：某些企业 GitLab 实例启用了子路径（如
/groups/proj/-/tree/...），但 Composer 只认标准 Git 协议 URL（https://host/group/repo.git） - 私有仓库没配 SSH key 或 token？Composer 走的是系统 Git，不是 PHP curl —— 如果
git clone https://...在命令行能通，Composer 就该能通；若不行，先解决 Git 层认证 - 运行
composer install -vvv，看日志里实际执行的git rev-parse和git ls-remote命令，能快速定位是找不到 ref 还是 fetch 权限问题
commit 版本无法被 Packagist 自动更新，lock 文件必须手动维护
用 commit hash 安装的包，composer update 不会自动升级到新 commit，也不会触发 Packagist 的元数据刷新——因为它根本不在 Packagist 的版本索引里。
-
composer.lock里会记录精确的source.reference，下次install全靠这个，和远程仓库当前状态无关 - 想升级？只能手动改
composer.json里的 hash，再跑composer update vendor/package；或者删掉 lock 里对应条目后 update - CI 环境中要注意：如果 CI 缓存了 vendor/ 但没更新 lock，可能跑着旧 commit 却以为是新代码，排查时务必比对
vendor/package/.git/HEAD和 lock 文件中的 reference - 这不是 bug，是设计使然：commit hash 表达的是“不可变快照”，Composer 就是按这个语义实现的
