必须在项目根目录composer.json顶层repositories中配置type为path、url为相对路径的本地包,且本地包需含合法composer.json(name与require逐字一致)、已初始化Git并有commit,require版本须精确匹配分支名如dev-main。

不能直接用 composer require 加个路径就装上——必须显式告诉 Composer “这个本地目录是个包”,否则它永远只认 Packagist。
怎么配 repositories 才让 Composer 看见本地包
在项目根目录的 composer.json 里,repositories 字段必须和 require 同级,不能嵌在别的字段里。写法示例:
{
"repositories": [
{
"type": "path",
"url": "./packages/my-utils"
}
],
"require": {
"my-vendor/my-utils": "dev-main"
}
}
注意三点:
-
url是相对于composer.json的路径,不能用/home/user/pkg或file://开头 -
./packages/my-utils目录下必须有合法的composer.json,且含"name": "my-vendor/my-utils"(逐字一致,大小写敏感) - 改完后要删掉
vendor/和composer.lock,再运行composer install;只跑update可能因缓存跳过新仓库
require 时版本号写什么才不报错
本地 path 包不走语义化版本解析,写 ^1.0 或 * 都会失败。必须用分支别名,且和本地包 composer.json 中的 version 字段或 Git 分支名严格匹配。
- 如果本地包
composer.json写了"version": "dev-main",就写"my-vendor/my-utils": "dev-main" - 如果没写
version,但 Git 当前在main分支,也可以写"dev-main" - 必须加
"minimum-stability": "dev"到项目composer.json顶层,否则dev-main被过滤掉 - 别写
@dev或dev-master——万一本地没master分支,就直接报Could not find a matching version
改了本地代码,vendor 里为啥没变
默认情况下,Composer 对 path 包是复制(Windows)或硬链接(Linux/macOS),不是实时同步。改了 ./packages/my-utils 的代码,vendor/my-vendor/my-utils 不会自动更新。
- 正确做法:运行
composer update my-vendor/my-utils(只刷新这个包) - 想改即生效,得启用符号链接:在
repositories条目里加"options": {"symlink": true} - Windows 用户需以管理员身份运行终端,否则
symlink会静默 fallback 到 copy - 切勿删
vendor/后再install——这会让本地包被完整复制进vendor,失去调试意义
autoload 不生效?先查这三处
类找不到、测试类加载失败,90% 和 autoload 配置有关,和 Composer 本身无关。
- 本地包的
composer.json必须有正确的autoload或autoload-dev,例如:"psr-4": {"MyVendor\Utils\": "src/"}(注意双反斜杠和末尾斜杠) - 新增或修改 autoload 映射后,必须手动运行
composer dump-autoload(开发阶段不用加-o) - 如果测试类在
tests/下,且用了autoload-dev,映射末尾必须带反斜杠:"MyVendor\Tests\": "tests/",少一个就断掉 - 验证是否真生效:
php -r "echo class_exists('MyVendor\Utils\Helper') ? 'ok' : 'fail';"输出ok才算通过
最易忽略的点:所有 name 字段必须逐字一致,包括大小写、斜杠方向、连字符;url 必须是相对路径;改了 autoload 一定得 dump-autoload,不能只等下次 install。











