composer的path仓库类型专为本地开发设计，需在项目composer.json中配置type为path的repositories，指向含合法composer.json的本地目录，且name与require完全一致；默认创建符号链接实现热更新，但需显式启用symlink选项并满足系统权限。
Composer 的 path 仓库类型不是用来“安装远程包”的替代方案，而是专为本地开发协作设计的——它让你在不发布、不提交、不推送到 Packagist 的前提下，把本地另一个目录当作一个可 require 的包来用。关键在于：它只在开发阶段有效，且必须满足路径可访问、结构合规、版本可解析三个硬条件。
什么是 path 仓库？为什么不能直接 require 相对路径？
Composer 默认只认 Packagist 或自建 Composer 仓库（如 Satis）里的包，require "myorg/utils": "dev-main" 这种写法背后依赖的是包名 + 版本号的解析机制，而普通文件系统路径没有元信息、没有版本标签、也没有 autoload 规则声明。所以你不能写 "myorg/utils": "../utils" ——这会直接报错 Could not find package myorg/utils。
path 仓库的作用，就是告诉 Composer：“这个本地目录，我把它当做一个合法的 Composer 包来对待”，前提是该目录里有有效的 composer.json，并且你显式注册了仓库来源。
常见错误现象：
- 执行
composer require myorg/utils后提示Package myorg/utils not found——没配仓库或包名不匹配 - 配了仓库但安装后
vendor/myorg/utils是空的或报 autoload 错误 ——本地包的composer.json缺autoload或name字段 - 更新后发现代码没变 ——因为
path模式默认启用 symlink（符号链接），但 Windows 默认禁用或权限受限，导致实际未联动
path 仓库的两种注册方式：项目级 vs 全局
推荐优先使用项目级配置（即改当前项目的 composer.json），避免污染全局行为。全局配置适合多项目共用同一套本地 SDK 的场景，但容易引发版本混淆。
项目级写法（在你的主项目 composer.json 中添加）：
{
"repositories": [
{
"type": "path",
"url": "../myorg-utils"
}
],
"require": {
"myorg/utils": "*"
}
}
注意：url 是相对于当前 composer.json 文件的路径，不是相对于命令行当前目录；myorg/utils 必须与目标目录中 composer.json 的 "name" 字段完全一致（包括大小写）。
全局注册（慎用）：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
composer config -g repositories.myorg-utils '{"type":"path","url":"/Users/you/dev/myorg-utils"}'
这样所有项目都能 require "myorg/utils"，但无法控制哪个项目用哪个本地路径，也容易因路径失效导致全盘报错。
path 模式下的 reference 参数是干什么的？
reference 不是必需字段，但它解决的是“软链接指向哪个 commit”的问题。默认情况下，path 仓库总是 symlink 到本地目录的当前 HEAD，也就是说：你改了本地包的代码，主项目里立刻可见（无需重新 install）。但如果你希望锁定到某个特定状态（比如测试某个分支或 tag），就得加 reference：
{
"repositories": [
{
"type": "path",
"url": "../myorg-utils",
"options": {
"symlink": true,
"reference": "v2.1.0"
}
}
]
}
这里 reference 必须是本地 Git 仓库中存在的 commit hash、branch 名或 tag 名。Composer 会在安装时检查该引用是否存在，不存在就失败。它不会 checkout，只是校验 —— 因为 symlink 本身不涉及 Git 操作，它只确保你“有意指向一个稳定点”。
容易踩的坑：
-
reference写成"dev-feature/login"，但本地仓库没这个分支 → 安装中断 - 用了
reference却忘了本地包目录是干净的（没 git init / 没 commit）→ 报Unable to get reference - 误以为
reference能触发自动 checkout → 实际上它只是断言，不改变工作区状态
为什么 composer update 有时不更新 symlink？
因为 path 类型仓库默认启用 symlink（"options": {"symlink": true}），而 symlink 是文件系统层面的指针，不是复制。所以 composer update 只会检查 reference 是否有效、是否需要重建链接，但不会拉取新代码 —— 新代码得靠你手动在本地包目录里 git pull 或修改文件。
如果你想要“每次 update 都强制同步最新内容”，有两个选择：
- 保持 symlink 开启，但养成习惯：在本地包目录里完成开发后，先
git add/commit，再回到主项目composer update myorg/utils（触发 reference 校验和链接刷新） - 关闭 symlink：
"options": {"symlink": false}，此时 Composer 会把整个目录 copy 进vendor/，变成一份独立副本 —— 这样update就真会覆盖，但失去实时调试能力，且占用双倍磁盘空间
Windows 用户特别注意：PowerShell 默认禁用 symlink，需以管理员身份运行或提前执行 cmd /c "mklink /D" 测试权限；否则即使配置了 symlink: true，Composer 也会静默 fallback 到 copy 模式，且不报错 —— 导致你以为在联动，其实没动。
真正难的不是配 path，而是让团队成员都理解：这个模式下，“本地包”不再是普通文件夹，它必须是一个带 name、带 autoload、带 Git 历史的完整 Composer 包；任何绕过 composer.json 手动改 vendor 里 symlink 目标的行为，都会在下次 install 时被覆盖。
