Composer 的 path 仓库本质是符号链接而非文件复制，修改本地代码立即生效，但需确保 PSR- 4 规范、合法 composer.json 及 name 字段匹配；支持相对 / 绝对路径，Windows 需管理员权限；配置分全局 repositories 声明与 require 内联两种方式；更新失效时需检查 allow-plugins、清缓存并重删 vendor 目录；严禁用于生产环境，CI 中须自动移除 path 配置。

本地 path 仓库的本质是软链接，不是复制文件

Composer 的 path 类型仓库不会把包源码拷进 vendor/，而是用符号链接（Linux/macOS）或目录联结（Windows）指向你指定的本地路径。这意味着：改本地代码 = 立即生效，无需 composer update；但前提是你的开发目录结构符合 PSR-4 自动加载规范，且 composer.json 中的 autoload 配置正确。

• 必须确保目标目录里有合法的 composer.json，且包含 name 字段（格式如 "myorg/mypackage"），该名称要和主项目 require 中声明的一致
• 路径支持相对（如 ../mypackage）和绝对（如 /Users/me/dev/mypackage），但相对路径以主项目根目录为基准
• Windows 用户注意：mklink /D 权限问题可能导致链接失败，可临时用管理员权限运行 composer install

在 composer.json 中配置 path 仓库的两种写法

有两种等效方式：全局仓库级声明（推荐用于多包协同），或仅针对某依赖的内联写法（适合快速验证）。关键 区别 在于作用范围和可维护性。

• 方式一（推荐）：在主项目的 composer.json 根级加 repositories 块，再 require 对应包名
• 方式二（临时）：直接在 require 中用对象语法写路径，不需额外声明 repositories
• 两者都要求目标包的 composer.json 中 version 字段存在（哪怕写 "dev-main"），否则 Composer 会报 Could not find a matching version

{"repositories": [         {             "type": "path",             "url": "../mypackage"}     ],     "require": {"myorg/mypackage": "*"} }

composer update 不触发重链接？检查 allow-plugins 和缓存

常见现象：改了本地包的 composer.json（比如更新了 version 或 autoload），但 composer update myorg/mypackage 没反应，vendor/myorg/mypackage 仍是旧链接甚至变成普通目录。

• 先确认是否启用了 composer-plugin-api 兼容插件：Composer 2.2+ 默认禁用未声明的插件，path 仓库依赖 composer-plugin-api，需在主项目 composer.json 中显式允许
• 执行 composer clear-cache，否则 Composer 可能复用旧的元数据缓存，忽略路径变更
• 若链接已损坏（变成普通文件夹），手动删掉 vendor/myorg/mypackage 再 composer update，强制重建链接

生产环境严禁使用 path 仓库，CI/CD 中要自动切换

path 是纯开发期机制，上线部署时若没清理，会导致构建失败（路径不存在）或引用错误代码。不能靠“上线前手动改 composer.json”来规避。

• CI 脚本中应在安装前移除 repositories 中的 path 条目，或用 composer config --unset repositories 清空
• 更稳妥做法：用 COMPOSER_ROOT_VERSION=1.0.0 composer install 强制忽略本地开发分支，走 packagist 正式版本
• 团队协作时，建议把 path 配置放在 composer.json.dist 外，或通过 COMPOSER_HOME 指向不同配置，避免误提交

路径映射看着简单，但链接状态、缓存行为、环境隔离这三处最容易出 silent fail —— 出问题时先看 ls -la vendor/xxx 是否真为链接，再查 composer show myorg/mypackage 输出里的 source 字段是否含 path。