用 path 类型仓库是本地多项目共享组件最轻量、最可控的方式，但默认行为是复制而非软链接，且上线前必须移除或替换为正式源，否则构建不可重现。
直接说结论：用 path 类型仓库是本地多项目共享组件最轻量、最可控的方式，但默认行为是复制而非软链接，且上线前必须移除或替换为正式源，否则构建不可重现。
为什么 path 仓库适合本地共享组件
它把本地目录当作一个“包”，不依赖网络、不走 Packagist、不强制发布，改完代码立刻在主项目中生效。特别适合 SDK、通用工具类、内部框架模块这类高频迭代又尚未稳定发布的组件。
- 每个共享组件目录（如
../shared-utils）必须有合法composer.json，含"name"（如"myorg/utils"）和"autoload"映射 - 主项目
composer.json的repositories中添加：{ "type": "path", "url": "../shared-utils" } -
require段写"myorg/utils": "dev-main"（分支名要匹配，dev-前缀不能漏） - 执行
composer install后，vendor/myorg/utils默认是复制体；要软链得额外配置
如何让 path 仓库生成软链接而不是复制
默认复制是为了保证构建可重现，但开发时你肯定不想每次改完都要 composer update。启用软链接有两种方式，且只对 composer update 生效（install 无视）：
- 在共享组件的
composer.json中加："options": { "symlink": true } - 或全局配置：
composer config --global repo.packagist composer https://packagist.org不影响，但软链需运行：composer config --global fxp-asset.installer-paths '{"bower-asset-library": "vendor/bower"}'—— 实际上更简单的是：运行composer update myorg/utils --with-dependencies，并确保本地 Git 配置支持符号链接（Windows 需管理员权限或启用 Developer Mode） - 注意：
symlink: true在 Composer 2.2+ 中仅对update有效，install仍会复制，这是设计使然
多个 path 仓库共存时的常见坑
当项目同时引用 ../user-sdk、../payment-core 等多个本地组件时，容易出现路径错位、包名冲突、autoload 覆盖等问题：
- 所有
url必须是相对路径，从主项目composer.json所在位置起算，不能用~/或绝对路径 - 多个组件若声明了相同命名空间（如都映射
"MyApp\": "src/"），会导致自动加载冲突，必须差异化命名空间或调整psr-4映射路径 - 如果两个
path仓库里有同名包（如都叫"myorg/common"），Composer 只认repositories数组中靠前的那个，后一个完全被忽略 -
composer dump-autoload -o在多 path 场景下可能生成错误的 classmap，建议开发阶段用-a（不优化），上线前再跑一次-o并验证
上线前必须做的三件事
path 仓库是开发捷径，不是部署方案。不处理好，CI 构建会失败，生产环境会找不到包：
- 删掉
repositories中所有type: "path"条目，换成对应私有仓库（如type: "vcs"或私有composer源） - 把
require中的"dev-main"改成语义化版本（如"^1.2"），并确保该版本已打 tag 或发布到私有源 - 提交更新后的
composer.lock—— 这是唯一能锁定真实来源和版本的文件，CI 只读lock，不看repositories配置
最容易被忽略的一点：团队成员各自 clone 主项目后，若没同步拉取所有 path 模块目录，composer install 会静默跳过那些模块（因为路径不存在），但不会报错——最终 autoload 缺失，运行时报 Class not found。所以务必在 README 里写清初始化命令，或用 git submodule + post-checkout 钩子兜底。
