Composer要求指定commit哈希时必须用“dev-branch#hash”格式，如"dev-main#abc1234"，不可省略dev-前缀或直接写纯哈希；命令行需加引号防shell截断，且须配合repositories配置（若非Packagist包）及composer update生效。
require指定commit哈希时，必须用dev-branch-name#commit-hash格式
Composer不支持直接写require vendor/package:abc1234这种纯哈希形式——它会报Could not find package。真正有效的写法是把哈希挂载在某个分支别名后面，例如"monolog/monolog": "dev-main#abc1234"或"monolog/monolog": "dev-master#abc1234"。这里的dev-main只是占位符，Composer实际只认#后面的哈希值，但前面的dev-前缀不可省略。
常见错误包括：
- 漏掉
dev-前缀，写成"monolog/monolog": "main#abc1234"→ 静默失败 - 用
@代替#，如monolog/monolog@abc1234→ 命令行解析报错 - 哈希写错位数（应为完整40位SHA-1）或大小写混用 → 找不到对应dist包
用composer require命令行写commit哈希要加引号
终端里直接执行时，#会被shell当作注释符吃掉，导致命令截断。必须用单引号包裹整个版本字符串：
composer require monolog/monolog:'dev-main#abc1234'
不加引号的composer require monolog/monolog:dev-main#abc1234在大多数shell中等价于composer require monolog/monolog:dev-main，后面哈希被丢弃。
其他注意事项：
- 确保目标commit在远程仓库存在且可访问（私有仓库需配置认证）
- 如果该commit未打tag，Composer会回退到
source方式安装（git clone），而非dist（zip包），速度更慢且依赖git环境 - 运行后检查
composer.lock中对应条目的source.reference字段是否为该哈希值
手动改composer.json后必须跑composer update vendor/package
只改composer.json里的版本字段，不执行update，composer.lock不会更新，等于没生效。尤其当你要锁定到某个特定commit时，这个步骤不能跳过。
正确流程是：
- 编辑
composer.json，将"monolog/monolog": "2.11.0"改为"monolog/monolog": "dev-main#abc1234" - 运行
composer update monolog/monolog（指定包名，避免连带更新其他依赖） - 确认
vendor/monolog/monolog/.git/HEAD指向该commit（若为source安装） - 验证
composer show monolog/monolog输出的source reference是否匹配
别用composer install替代——它只读lock，不会拉新commit。
commit哈希安装失败的三个高频原因
不是网络问题，大概率是这三处之一卡住：
-
repositories没配或配错：如果包不在Packagist上（比如私有Git库），必须在composer.json根级显式声明repositories，类型为vcs，url指向Git仓库地址（不含.git后缀） - 分支名不一致：写
dev-main但远端主分支叫dev-master，或没初始化Git（git init都未执行）→ Composer无法识别该分支别名 - 哈希对应代码不可见：commit在本地未
push，或远端仓库权限不足（如SSH密钥未配置、HTTPS凭据过期）
最稳的排查顺序是：composer show -s vendor/package看能否列出该哈希对应的版本；不行就检查repositories和远端可达性；再不行就确认Git仓库状态和权限。
