Composer path仓库生效需同时满足：type为"path"、url是相对于主项目根目录的合法相对路径（无尾部斜杠）、路径下存在name与require完全一致的composer.json；否则静默忽略。
软链接目标路径必须是相对路径，且不能带尾部斜杠
Composer 的 path 仓库类型只接受相对于主项目根目录的路径，比如 "../my-package" 是合法的，而 "../my-package/"（末尾有斜杠）、/home/user/my-package（绝对路径）、file:///home/user/my-package（带协议）都会被静默忽略。它不会报错，但也不会加载该仓库——导致后续 composer install 完全无视你写的本地包。
验证方式很简单：运行 composer install --verbose，看日志里是否出现 Reading ../my-package/composer.json。没这行，说明路径根本没被识别。
- 用
ls -ld ../my-package确认目录存在且可读（权限至少是dr-xr-xr-x） - 确保
../my-package/composer.json文件真实存在，并且里面的"name"字段和require中的字符串**逐字一致**（大小写、中划线、vendor 名一个都不能错） - 删掉
vendor/和composer.lock后重试，避免缓存干扰
repositories 配置必须禁用 packagist.org 才生效
很多人把 repositories 块加进 composer.json 就以为完事了，结果 composer show --all | grep vendor/name 无输出——因为 Composer 默认优先查 packagist.org，你的本地源只是“备选”，除非显式关掉默认源。
正确写法必须把 {"packagist.org": false} 放在 repositories 数组的第一项：
"repositories": [
{"packagist.org": false},
{
"type": "path",
"url": "../my-package"
}
]
否则即使路径对、name 对，Composer 也会跳过你的本地目录，直接去远程源找包，自然报 Could not find package。
符号链接在 Docker / WSL / CI 中容易被隔离
你在宿主机上 ls 能看到 composer.json，cat 也能读，但容器内或某些 CI 环境里执行 composer install 却报 Source path does not exist，这不是路径写错了，而是文件系统层面被限制了。
常见原因：
- Docker 挂载时没把
../my-package目录一并映射进去，容器里压根没有那个路径 - WSL2 或 GitHub Actions runner 使用了跨挂载点的软链接（例如
ln -s /mnt/c/project/my-pkg ./my-pkg），Composer 内部调用realpath()失败后直接跳过 - Windows 上用 Git Bash 创建的软链接，在 PowerShell 或 CMD 中不可见
临时绕过方法：改用绝对路径传给 -d 参数，比如 composer -d /abs/path/to/project install；长期方案是避免在关键路径上用软链接，改用 cp -r 或子模块同步。
composer link 不适合首次安装，且不更新 autoload
composer link 只对已通过 composer require 安装过的包有效，它本质是在 vendor/ 下创建符号链接，但不会触发 autoload 重新生成，也不写入 composer.lock。下次 composer update 极可能把它覆盖回远程版本。
更麻烦的是：如果你还没装过这个包，直接跑 composer link vendor/name 会报错 Package vendor/name is not installed，没法补救。
所以真要调试本地包，优先走 path 仓库 + dev-main 版本号这条路。只有当你改完代码想快速切回远程版本验证兼容性时，composer link 才有点用——但也得记得手动跑一次 composer dump-autoload。
