path 类型仓库是 Composer 支持的本地仓库，通过配置相对路径将本机目录作为包依赖，要求源目录含合法 composer.json 且 name 与 require 一致，更新时创建符号链接实现热修改。

什么是 path 类型仓库

path 是 Composer 支持的一种本地仓库类型，允许你把本机某个目录当作一个包来 require。它不走 Packagist，也不需要发布到任何远程源，适合开发中快速联调私有组件、调试 fork 后的包，或做模块化拆分时的本地依赖验证。

关键点：目标目录必须包含合法的 composer.json，且其中的 name 字段要与你在主项目中 require 的包名完全一致——否则 Composer 会报 Could not find package xxx。

在 composer.json 中配置 path 仓库

你需要在主项目的 composer.json 里显式声明一个 path 类型仓库，并确保它出现在 repositories 数组中（顺序无关，但不能嵌套在其他字段下）。

{
  "repositories": [
    {
      "type": "path",
      "url": "../my-private-package"
    }
  ],
  "require": {
    "vendor/my-private-package": "*"
  }
}

注意：

• url 值是相对于当前 composer.json 文件的路径，支持 ../、./，但不支持绝对路径写法（如 /home/user/pkg）——除非你用 file:// 协议（不推荐，跨环境易出错）
• "*" 版本约束会被自动解析为该目录下 composer.json 中的 version 字段值；如果没写 version，Composer 默认用 dev-main 或 dev-master
• 若目标包使用了 autoload（如 psr-4），它会正常生效，无需额外配置

运行 composer update 时的常见行为

执行 composer update vendor/my-private-package 或全量更新后，Composer 不会复制文件，而是创建符号链接（Linux/macOS）或目录 Junction（Windows）指向源目录。这意味着：

• 你对 ../my-private-package 的任何修改，立刻反映在主项目的 vendor/ 下
• composer install 在 CI 或他人机器上会失败——因为 path 仓库只在本地有效，上线前必须换成 git 或 artifact 类型仓库
• 如果你在源包里改了 composer.json 的 name 或 autoload，需手动运行 composer dump-autoload 或再次 update
• 若看到 Skipped installation of bin ... symlink does not exist，说明源包没定义 bin，可忽略；如有，确保源包的 bin 脚本路径正确且可执行

为什么 path 依赖没生效？排查要点

最常卡在这几步：

• 主项目 composer.json 中的 require 名称和源包 composer.json 的 name 不一致（大小写、vendor 名都算不同）
• 源包目录下没有 composer.json，或 JSON 格式错误（可用 composer validate 检查）
• 执行的是 composer install 而不是 update——install 只读 composer.lock，不会重新解析 repositories
• 用了相对路径但当前工作目录不是主项目根目录（比如你在子目录下运行命令）
• 源包的 version 字段写成了 1.0.0@dev 这类非法格式，导致版本解析失败

临时验证方式：运行 composer show vendor/my-private-package，如果输出包含 source: path ../my-private-package 就说明已成功挂载。