Composer识别path仓库需显式声明repositories，严格校验本地composer.json的name与require一致；默认软链接，修改代码后须composer update刷新。
Path仓库不是“自动扫描子目录”，必须显式声明每个模块路径
很多人以为在项目里放一堆 modules/ 子目录，Composer 就能自动识别并加载——根本不会。它只读当前目录的 composer.json，对其他 composer.json 文件完全无视。真正起作用的是你在主项目 composer.json 的 repositories 字段里手动写的每一条 {"type":"path","url":"./modules/user"}。
常见错误现象：composer install 后 vendor/myorg/user 是空的、报 Could not find package myorg/user，大概率是以下几点之一：
-
url值写成绝对路径（如/home/user/project/modules/user），而没用相对路径（./modules/user或../user-sdk） - 目标目录（如
modules/user）下没有合法composer.json，或里面缺name字段，或name值（如"myorg/user"）和你require里的不一致 -
require写了"myorg/user": "dev-main"，但目标模块实际分支叫main或develop，版本号不匹配就找不到
软链接生效的前提：必须用 composer install 或 composer update vendor/name
只改了本地模块代码，却没触发 Composer 重建软链接？那 PHP 加载的还是旧副本。Path 类型仓库默认行为是创建符号链接，但这个链接只在安装或更新时生成，不是实时监听。
关键操作点：
- 首次引入模块，执行
composer install（不是dump-autoload） - 后续修改模块代码，无需任何命令——只要
vendor/myorg/user是软链接，改modules/user/src/下文件就立刻生效 - 如果发现
vendor/myorg/user是普通目录（不是链接），说明之前装错方式：先composer remove myorg/user，再确认repositories和require配置无误，最后重跑composer install - Composer 2.2+ 支持
"symlink": true字段，但即使不写，默认也是软链；真要强制复制，得加--no-plugins或删掉path类型配置
上线前必须清理 repositories 中的 path 条目
CI 流水线构建失败最常见的原因：构建机上没有 ../user-sdk 这个路径，而你的 composer.json 还留着 {"type":"path","url":"../user-sdk"}。Path 仓库纯属本地开发机制，生产环境必须切换为真实源。
正确发布流程：
- 把模块推到私有仓库（如 GitLab、Satis 或 Private Packagist），打上 tag 或确保分支可访问
- 主项目
composer.json中删掉对应path条目，改为vcs类型仓库或直接依赖私有源 URL - 把
require中的开发版（如"dev-main"）换成稳定版约束（如"^1.0"） - 运行
composer update myorg/user --with-dependencies，生成新的composer.lock - 提交更新后的
composer.json和composer.lock
多个模块共存时，autoload 映射冲突怎么破
所有模块都用 psr-4 自动加载，但命名空间撞车或路径拼接出错，就会报 Class not found。根本问题不在 Composer，而在每个模块自己的 composer.json 中 autoload.psr-4 配置是否规范。
典型坑点：
- 子模块
composer.json里写"MyOrg\Auth\": "src/"，末尾多了一个反斜杠（"MyOrg\Auth\\"），导致最终类路径变成src//Auth/LoginController.php，文件找不到 - 两个模块都声明了
"App\": "src/"，后加载的会覆盖前一个，造成部分类失效 - 主项目也配了
autoload.psr-4，和子模块映射范围重叠（比如都覆盖MyOrg\*），结果类被加载两次或漏加载 - 解决办法很直接：每个模块用唯一根命名空间（如
"MyOrg\User\": "src/"），主项目 autoload 只管自己代码，不覆盖模块命名空间
最易被忽略的一点：改完任意模块的 autoload 配置后，必须在主项目中运行 composer dump-autoload，否则新映射不会进 vendor/composer/autoload_psr4.php——软链接存在，但类还是找不到。
