必须将path仓库配置写在主项目根目录composer.json的repositories数组中，子模块自己的composer.json中配置无效；url需为相对路径，本地包须有合法composer.json且name、version与require严格一致。
path仓库必须写在主项目composer.json的repositories里
Composer 不会自动扫描子目录下的 composer.json，repositories 字段只能出现在**主项目根目录**的 composer.json 中，写在模块自己的 composer.json 里完全无效。常见错误是把 path 配置误放在 modules/user/composer.json 里，结果 composer install 根本不识别路径。
正确做法是：在项目根目录 composer.json 的 repositories 数组中显式声明每个模块路径，例如：
{
"repositories": [
{ "type": "path", "url": "modules/user" },
{ "type": "path", "url": "modules/payment" }
],
"require": {
"myorg/user": "dev-main",
"myorg/payment": "dev-main"
}
}
- 所有
url必须是相对于主项目composer.json的路径，不能用~/或环境变量 - 每个模块目录（如
modules/user）下必须有独立的composer.json，且其中name字段必须与require中的包名完全一致（包括 vendor 名） - 模块目录需已执行过
git init并至少有一个 commit，否则 Composer 拒绝加载
本地模块的composer.json必须含合法name和version
path 仓库不是“挂载文件夹”，而是把本地目录当作一个完整包来解析。若模块的 composer.json 缺少 name 或 version，composer install 会报 Could not find a matching version of package myorg/user——这不是网络问题，是包元数据不全。
最小可用配置示例（modules/user/composer.json）：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"name": "myorg/user",
"version": "dev-main",
"autoload": {
"psr-4": { "MyOrg\User\": "src/" }
}
}
-
version不必是语义化版本，但必须存在；开发阶段推荐用"dev-main"或"dev-develop"，且要与主项目require中的版本约束一致 -
autoload必须正确映射命名空间到目录，否则类无法被自动加载 - 如果模块依赖其他包，可正常写
require，Composer 会递归解析，但注意：这些依赖不会被装进主项目的vendor/，只影响该模块自身的类加载上下文
软链接生效需满足系统+配置双重条件
默认情况下，Composer 对 path 类型包会创建符号链接（Linux/macOS）或复制（Windows），但实际行为受操作系统能力与显式配置共同控制。很多人执行 composer install 后发现 vendor/myorg/user 是个普通文件夹而非链接，本质是没触发 symlink 模式。
- Linux/macOS 默认启用 symlink，但 Windows 需开启“开发者模式”或以管理员权限运行终端，否则 fallback 为复制
- 必须在**模块自己的**
composer.json中加"options": {"symlink": true}，仅在主项目 config 里设path.repo.symlink不生效 -
composer install不刷新已有链接；改了本地模块代码后，必须运行composer update myorg/user才会重建 symlink - 验证是否成功：执行
ls -la vendor/myorg/user（Linux/macOS）或dir vendormyorguser（Windows），输出应含->或<symlinkd></symlinkd>
上线前必须清理path仓库并更新lock文件
CI/CD 环境中 modules/ 目录通常不存在，path 仓库必然失败；更严重的是，composer.lock 里会记录本地路径的 source.reference 和 dist.url，导致线上构建拉取失败或哈希校验不通过。
- 上线前务必从主项目
composer.json的repositories中删除所有type: "path"条目，替换为私有 Packagist 地址或 vcs 类型仓库 - 执行
composer update myorg/user（指定包名，避免全量重算），让 lock 文件更新为远程源的 dist 信息 - 确认
composer.lock已提交，且 CI 脚本中只用composer install，严禁出现composer update - 团队内应约定：path 仓库仅用于本地开发，
composer.json中的 path 配置属于“临时开发配置”，不视为生产就绪状态
真正容易被忽略的是：path 仓库的 symlink 行为只在本地开发有意义，它和 autoload、classmap、dump-autoload 完全无关；一旦忘记删 repositories 或未更新 lock，CI 构建就会在第一行 composer install 就卡死或报错，而错误提示往往掩盖了根本原因。
