如何在不发布的情况下，通过Composer本地路径引用测试开发中的包？

本文共计880个文字，预计阅读时间需要4分钟。

使用Composer支持通过指定路径加载本地文件夹，无需使用`git push`或注册到Packagist。只需确保你的包包含合法的`composer.json`文件（包含`name`和`version`字段），项目就能识别。

在主项目的 composer.json 中添加：

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

注意：url 是相对于主项目 composer.json 的路径；require 中的包名必须和目标包 composer.json 里的 name 完全一致。

path 仓库的版本匹配规则很关键

默认情况下，path 仓库只匹配 dev- 开头的版本（比如 "*" 或 "dev-main"），不匹配 1.0.0 这类稳定版 —— 即使你本地 composer.json 写了 "version": "1.0.0"，Composer 也会忽略它，只认分支名或 dev- 前缀。

解决办法只有两个：

• 把本地包的 composer.json 中 version 改成 "dev-main"（或 "dev-develop"），并确保 require 里也写 "dev-main"
• 或者干脆删掉 version 字段，让 Composer 自动从 Git 分支推断（前提是目录是 Git 仓库且有当前分支）

如果漏掉这步，composer install 会报错：Could not find package vendor/name at version *，不是路径错了，是版本没对上。

软链接方式更灵活，但要注意 Composer 缓存

有些场景下，你希望多个项目共用同一份开发中的包源码，又不想反复改 repositories.url。这时可以用符号链接（symlink）配合 path 仓库：

先在主项目旁建个统一目录，比如 ./packages/my-package，然后用 ln -s（macOS/Linux）或 mklink（Windows）把它链到真实开发路径；repositories.url 就固定写 "packages/my-package"。

但要注意：Composer 会缓存 path 包的元数据（包括 autoload 映射）。改了本地包的 autoload 或新增了类，必须运行 composer dump-autoload，否则自动加载器找不到新文件。

别忘了 autoload-dev 和测试类的可见性

如果你在本地包里写了测试（比如 tests/ 目录），并且用了 autoload-dev，那主项目默认是无法直接 require 这些测试类的 —— 因为 autoload-dev 只在包自身执行 composer install 时生效。

要让主项目也能加载测试类，有两个选择：

• 把测试目录加进主项目的 autoload-dev（不推荐，污染主项目配置）
• 在本地包的 composer.json 中，把测试类也放进 autoload（非 -dev）部分，比如："psr-4": { "MyPackage\Tests\": "tests/" }

否则跑 phpunit 时会提示 Class XXX not found，问题不在路径，而在自动加载范围没覆盖到。

路径引用省事，但版本、缓存、autoload 边界这三个点，稍不注意就会卡住半天。