Composer支持直接引用Git仓库的commit hash（需dev-前缀，如"dev-main#abc1234"）或tag（如"v1.2.3"），但须确保仓库可访问、composer.json存在且name匹配；推荐用tag保障稳定性，commit仅作临时快照；强制source安装需配置preferred-install，否则可能因dist缺失或权限问题失败。
Composer 支持直接引用 Git 仓库的特定 commit hash 或 tag，无需发布到 Packagist，但必须确保仓库可公开访问（或已配置 SSH/HTTPS 认证）且 composer.json 存在。
用 dev- 前缀 + commit hash 指定精确提交
Composer 不支持裸 commit hash 作为版本号，必须加 dev- 前缀。它会把该 commit 视为 dev-main（或对应分支名）的快照。
- 写法：
"vendor/package": "dev-main#abc1234"（abc1234是短哈希，也可用完整 40 位） - 必须确保远程仓库中该 commit 确实存在，且
composer.json的name字段与依赖声明一致 - 执行
composer update vendor/package时，Composer 会 fetch 该 commit 并锁定其dist信息（含reference字段）到composer.lock - 若该 commit 所在分支被 force-push 覆盖，下次 install 可能失败——因为 reference 已失效
用 tag 引用稳定版本（推荐用于生产）
Tag 是语义化、可重用的锚点，比 commit hash 更适合协作和回滚。
- 写法：
"vendor/package": "v1.2.3"（前提是 tag 名符合 Composer 版本约束规则，如以v开头或纯数字格式） - 如果 tag 名不带
v（如1.2.3），需显式声明为"1.2.3 as 1.2.3"或确保composer.json中version字段匹配 - Composer 默认只识别 annotated tag；lightweight tag 需要手动在仓库中执行
git tag -a v1.2.3 -m "release"再 push - 运行
composer update后，composer.lock中该包的source.reference会记录对应 tag 的 commit hash
强制走 source 安装（跳过 dist 缓存）
默认情况下，Composer 优先使用 dist（zip 包），但 commit hash 和某些 tag 可能未生成 dist。此时需强制从源码安装。
- 在
composer.json根级别添加："config": { "preferred-install": { "vendor/package": "source" } } - 或全局设置：
composer config --global preferred-install.source vendor/package - 否则可能报错：
Could not find package vendor/package at version v1.2.3（尤其当 packagist.org 未收录该 tag 时） - 注意：source 安装会 clone 整个仓库，比 dist 慢，且依赖 git 命令可用
验证是否生效及常见失败原因
执行 composer show vendor/package 查看实际解析的 commit 和 source 类型。失败往往不是语法问题，而是环境或权限细节被忽略。
- 私有 GitLab/GitHub 仓库未配置
auth.json→ 报401 Unauthorized或Cloning into ... Permission denied - SSH URL（如
git@github.com:...git）未配 SSH key → 切换为 HTTPS URL 或补全 key - 仓库根目录缺少
composer.json→ Composer 根本不会识别为合法包 - 本地
composer.lock锁定了旧 reference，但远程 commit 已被 GC → 清理vendor/和composer.lock后重试
commit hash 引用本质是“临时快照”，tag 引用才是可维护的契约。真正棘手的是权限链和 source/dist 混合行为——它们不出现在错误提示里，却决定安装成败。
