path仓库适合内部包因支持实时软链接和本地开发，但不适合跨团队分发因其依赖绝对路径、禁用版本约束、CI易失败且不兼容vcs仓库。
为什么 path 仓库类型适合内部包但不适合跨团队分发
path 仓库是 Composer 原生支持的本地路径映射机制，它不走网络、不依赖 Git 认证、不生成远程元数据，只做“符号链接式”软引用。这意味着：你改了私有包源码，composer install 后 vendor 里的代码会实时反映变更（前提是启用了 symlink 模式）。但它完全绕过版本解析逻辑——Composer 不会读取该包 composer.json 中的 version 字段，也不校验稳定性，只认当前文件系统状态。
常见误用场景包括：把 path 仓库 URL 写成相对路径如 ../packages/my-utils，结果在 CI 环境或同事机器上路径不存在；或把它和 vcs 混用，导致同名包在不同仓库中冲突却无提示。
-
path仓库必须用绝对路径（推荐${PWD}/../packages/my-utils这类 shell 变量展开写法），否则composer install在非项目根目录执行时会失败 - 它不支持
dev-main或^2.0这类版本约束，只能用*或dev-develop（实际含义是“取当前 HEAD”） - CI 流水线里禁用 symlink（
"config": {"symlink": false}）后，path仓库会退化为全量拷贝，体积和构建时间陡增
path 仓库配置必须显式声明 options 才能生效
很多人写了 "type": "path" 却发现 Composer 完全无视该仓库，根本原因是：从 Composer 2.2 开始，path 类型仓库默认被禁用，必须手动启用 options 并设 "symlink": true 或 "copy-on-install": true。不加这个块，Composer 解析时直接跳过该仓库条目。
正确写法示例：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"repositories": [
{
"type": "path",
"url": "${PWD}/../internal/payment-sdk",
"options": {
"symlink": true
}
}
],
"require": {
"acme/payment-sdk": "*"
}
}
- 路径中的
${PWD}是 Composer 原生支持的变量，不是 shell 展开，无需额外处理 - 若目标目录下没有
composer.json，Composer 会报Could not find package acme/payment-sdk，而不是路径错误——检查私有包根目录是否存在合法composer.json - 不要在
options里写"git": false之类无效字段，Composer 会静默忽略，但可能掩盖真实问题
当多个 path 仓库共存时，优先级由声明顺序决定且不可覆盖
Composer 对 path 仓库也遵循“先到先得”原则：如果两个 path 仓库都提供 acme/utils，那么排在 repositories 数组前面的那个会被采用，后面的完全被忽略。这种行为无法用 only 或 exclude 控制——这两个过滤选项对 path 类型无效。
典型陷阱是：开发环境本地调试时启用了 path 仓库 A，上线前忘了注释掉，结果生产构建时仍试图从本地路径拉包，CI 报错 No such file or directory。
- 建议在项目根目录放一个
composer.local.json，把path配置放这里，再用composer install -c composer.local.json显式加载，避免污染主配置 - CI 脚本中应加检查：
grep -q '"type": "path"' composer.json && echo "ERROR: path repo detected in CI" && exit 1 - 同一包名禁止同时出现在
path和vcs仓库中，否则composer show acme/utils输出混乱，require-dev依赖可能意外降级
path 仓库下 autoload 失效的三个硬性条件
即使 acme/utils 成功装进 vendor/acme/utils，new UtilsClient() 仍报 Class not found，大概率是因为 autoload 没触发。这不是缓存问题，而是 path 仓库的 autoload 注册有三道硬门槛：
- 私有包自己的
composer.json必须含autoload段，且路径是相对于它自身根目录的（例如"psr-4": {"Acme\Utils\": "src/"}），不能写成"src/Acme/Utils/" - 主项目运行
composer dump-autoload时，必须带--optimize或至少确保vendor/composer/autoload_psr4.php里出现了该映射行；否则只生成 classmap，不注册 PSR-4 - 如果私有包用了
filesautoload（比如全局函数），必须确认这些文件在vendor/composer/autoload_files.php中被列出——path仓库不会自动重载这类文件，改完要手动dump-autoload
最省事的验证方式：删掉 vendor/composer/autoload_*.php，再跑一次 composer install，看新生成的文件里有没有你的包名。
