Path仓库是Composer提供的本地包加载机制，让Composer将指定本地目录当作包源解析安装，适用于开发中私有组件、调试第三方包或共享内部工具库等场景。

什么是 path 仓库，它适合什么场景

path 仓库是 Composer 提供的一种本地包加载机制，本质是让 Composer 把某个本地目录当作一个“包源”来解析和安装。它不走 Packagist，也不需要发布到任何远程仓库，适用于：

• 正在开发中的私有组件，还没稳定或不想公开
• 需要临时调试、修改第三方包源码（比如 fork 后打补丁）
• 多项目共享一套内部工具库，又不想搭私有 Packagist

注意：path 不会自动监听文件变化，每次改完代码后得手动运行 composer update vendor/package-name 或 composer install 才能同步。

配置 path 仓库的两种写法

必须在项目的 composer.json 中声明仓库，并确保目标包的 name 和 version 与本地 composer.json 一致。常见写法有两种：

• 直接在 repositories 里写路径（推荐）：

  

  Academic Composer Upload

  辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

  下载

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

• 使用通配符匹配多个本地目录（适合多包协同开发）：

  {
    "repositories": [
        {
            "type": "path",
            "url": "../packages/*"
        }
    ]
  }

  这时 ../packages/foo 和 ../packages/bar 下的包都会被识别，前提是它们各自有合法的 composer.json。

为什么 require 后没生效？常见卡点

• 本地包的 composer.json 缺少 name 字段，或格式错误（比如 name 值含大写字母、下划线，而 Composer 要求小写+短横线）
• 本地包的 version 是 dev-main 或 dev-master，但你在主项目里 require 写的是 "^1.0" —— 版本不匹配，Composer 会跳过该源
• 主项目已通过 Packagist 安装过同名包，Composer 默认优先远程源；解决办法是删掉 vendor/ 和 composer.lock，再 composer install
• 路径是相对路径，但位置错了：它相对于主项目的 composer.json，不是当前命令行所在目录

path 仓库 + symlink 模式：改代码实时生效

默认 path 会把本地包整个复制进 vendor/，改源码还得反复 update。加一个 options 就能启用符号链接：

{
    "repositories": [
        {
            "type": "path",
            "url": "../my-local-package",
            "options": {
                "symlink": true
            }
        }
    ]
}

这样 vendor/vendor/my-local-package 就是软链，直接编辑源目录即生效。但要注意：

• Windows 用户需管理员权限开启开发者模式，否则 symlink 会失败并回退为复制
• 如果本地包用了 autoload-dev，且你依赖它的测试类，记得在主项目中运行 composer install --with-all-dependencies 或确保 autoload-dev 被加载
• symlink 模式下不能用 composer dump-autoload -o 的优化模式（classmap 会失效），建议开发阶段用 --classmap-authoritative 以外的方式

实际用的时候，最麻烦的往往不是配置，而是版本字段对不上、路径写错、或者忘了清 lock 文件——这些地方多 check 一遍比重装 PHP 还省时间。