path仓库依赖被忽略或装错版本的根本原因是composer.lock未记录其source元数据，导致install跳过；必须用composer update my/local-package --with-dependencies强制写入source.type/url/reference，后续install才可正确symlink。
path仓库依赖为什么总被忽略或装错版本
当你在 composer.json 里用 "type": "path" 声明本地包（比如 "my/local-package": "*" + "repositories" 配置），composer install 却没拉你改过的代码，甚至报 "Package my/local-package is not installed" —— 根本原因不是路径不对，而是 composer.lock 里根本没存它的真实来源信息。
composer.lock 默认只记录 Packagist 或远程 VCS 包的 dist.sha256 和 source.reference；而 path 类型包没有 dist、没有 commit hash，它的“版本”实际由本地文件系统状态决定。所以：
-
composer install看到 lock 文件里没有该包的source字段，就跳过安装（尤其 Composer ≥2.5） - 即使装了，lock 文件也不会写入
source.type: "path"，下次install就认为“这包不存在”，直接报错退出 - 手动加
"source": {"type": "path", "url": "../local-package"}到 lock 文件？不行——字段顺序/空格参与哈希计算，会触发content-hash不匹配警告，且下次update会被覆盖
怎么让 path 依赖进 lock 文件并稳定生效
唯一可靠方式是强制 Composer 把 path 包识别为“可锁定”的源类型，靠 composer update 触发重解析，而不是靠 install 读 lock。
- 确保
repositories配置中明确指定"type": "path"和"url"（支持 glob，如"../packages/*"） - 运行
composer update my/local-package --with-dependencies，不是install—— 它会把该包的source元数据（包括type、url、reference）写入packages或packages-dev区块 - 检查生成的
composer.lock：对应包下应有"source": {"type": "path", "url": "../local-package", "reference": "dev-main"}字段（reference是你本地分支名或 tag） - 此后
composer install才能正确软链接（symlink）该目录，且不校验 dist hash
注意：reference 值必须是你本地 git 仓库当前 HEAD 的分支名或 commit，否则 symlink 失败；改了本地代码但没切分支，reference 不变，install 不会重新链接。
path 依赖和 --no-dev 的兼容性陷阱
如果你把 path 包放在 require-dev 里，CI 脚本跑 composer install --no-dev 时会直接跳过它——这没问题；但若它被生产代码 runtime require（比如 new My\LocalClass()），就会 Class not found。
- path 包是否进
require还是require-dev，取决于它是否被index.php或 CLI 入口直接加载 - 不能因为“本地开发才用”，就盲目塞进
require-dev；只要线上也依赖其类，就必须进require - 进
require后，composer install --no-dev仍会安装它，但 CI 必须确保 path 目录在部署机器上存在且路径一致（比如通过 rsync 或 volume mount） - 否则
install会成功，但运行时报"Failed to open stream: No such file or directory"—— 因为 symlink 指向了不存在的路径
lock 文件里 path 包的 reference 怎么更新
你改了本地 path 包的代码，想让其他环境也同步，但 composer install 不生效——因为 lock 文件里的 reference 没变，Composer 认为“还是那个版本”。
- 不要手动改 lock 文件里的
reference；它不参与校验，改了也没用 - 正确做法：cd 进 path 包目录，
git commit或git tag v1.0.1，然后回到主项目，运行composer update my/local-package - 如果 path 包没 git，Composer 会 fallback 到
dev-main，此时改代码后必须git add && git commit才能推进reference - CI 环境若禁用 git（如 shallow clone），
reference会变成空字符串或null，导致 symlink 失败；解决方案是提前git init && git add . && git commit -m "ci"
真正难搞的从来不是怎么写配置，而是当 path 包同时被多个项目引用、又混着 git submodule 和 symlink 时，reference 的语义到底以谁为准——这时候 lock 文件已经不是快照，而是需要人工对齐的契约。
