path仓库忽略version字段，仅依据Git分支名匹配require中的dev-前缀标识（如dev-main），要求本地包目录已初始化Git且HEAD位于对应分支；否则静默失败。
path仓库根本不认version字段，只看Git分支名
本地包的composer.json里写的"version": "1.2.0"或"dev-feature"在path类型下完全被忽略。Composer只读取当前Git HEAD所在的分支名（如main、develop），然后要求你在主项目require中写成"acme/utils": "dev-main"这种格式。
常见错误现象：composer require acme/utils:1.2.0失败，报“Could not find package”——不是版本号写错，而是你用了稳定版约束，而path源只响应dev-前缀的分支标识。
- 必须用
dev-main、dev-develop、dev-feature/login这类写法，不能省略dev- - 如果本地包所在目录没初始化Git，或HEAD不在任何分支上（比如处于detached HEAD），Composer会直接跳过该仓库，且不报错
- 验证是否识别成功：运行
composer show acme/utils，输出中的versions字段应显示* dev-main（带星号表示当前激活）
require里写错分支名，和repositories配置无关
repositories只是告诉Composer“这个包在哪”，require才是决定“我要哪个分支”的唯一位置。哪怕你把url指向一个含dev-v2分支的目录，只要require里写的是"acme/utils": "dev-main"，Composer就只找main分支——它不会自动 fallback，也不会提示“该分支不存在”。
容易踩的坑：
- 本地包Git分支名是
master，但你写了dev-main→ 安装失败 - 分支名含斜杠（如
feature/auth），没加引号导致Shell解析出错：composer require acme/utils:dev-feature/auth会报语法错误；正确写法是composer require "acme/utils:dev-feature/auth" - CI环境未检出分支（只fetch了tag或用了
--depth=1），导致dev-main查不到提交 → 构建失败
想临时切到某次commit？别用path，换vcs
path仓库不支持commit hash锁定。你不能写"acme/utils": "dev-main#abc1234"让它指向某个特定提交——这个语法只对vcs类型仓库有效。
如果确实需要精确到commit：
- 把
repositories类型从"path"改成"vcs"，url指向Git地址（如"https://github.com/acme/utils.git"） - 保持
require不变："acme/utils": "dev-main#abc1234" - 或者，先在本地包目录执行
git checkout abc1234，再确保当前HEAD在main分支上（git switch main && git reset --hard abc1234），这样path源才能匹配dev-main
Windows下symlink + dev-分支组合最易失效
Windows默认禁用符号链接，而path仓库启用"options": {"symlink": true}时，若权限不足，Composer会静默回退为复制模式，但不会告诉你——结果就是你改了本地代码，vendor/里还是旧文件。
必须确认的三件事：
- 以管理员身份运行终端，或已开启“开发者模式”（设置→更新与安全→开发者选项）
- 检查
vendor/acme/utils是否为快捷方式（右键属性看“目标”），不是则说明symlink失败 - 如果CI或部署脚本跑在无权创建symlink的环境（如Docker Alpine），直接设
"symlink": false，接受复制行为，并在文档里注明“本地开发需手动composer update同步”
真正卡住人的地方往往不是配置写法，而是Git状态和权限这两层看不见的依赖。path仓库快、离线、直观，但它的脆弱性全藏在本地文件系统和Git工作区里。
