path仓库require失败90%因name或路径不匹配:name须大小写及短横线完全一致,url须指向含合法composer.json的目录且为相对于主项目composer.json的路径(末尾不可加/)。

path仓库require失败,90%是name或路径不匹配
报Could not find package vendor/name,但composer show --all里压根没它——这不是网络或权限问题,而是name字段和require语句不一致,或url指向了错误位置。
Composer 对 path 仓库的匹配极其严格:
-
name必须大小写、分隔符(仅短横线-)完全一致,"acme/utils"≠"Acme/Utils"≠"acme_utils" -
url必须指向**含有效composer.json的目录**,且路径是相对于主项目composer.json的位置,比如"../my-pkg",不能是"./my-pkg"或"../my-pkg/"(末尾斜杠会静默失效) - Windows 用户需确认路径不含中文、空格,某些 PHP 版本解析会失败
- 本地包的
composer.json必须语法合法:无尾逗号、全双引号、name字段存在且非空
symlink没生效?先查本地包自己的options
改了本地代码,vendor 里还是旧副本——大概率是 fallback 到了 copy 模式,而非真正符号链接。关键不在主项目配置,而在**本地包自身的composer.json是否声明了"options": {"symlink": true}。
缺这句,即使你用管理员权限运行终端(Windows)或加了--cap-add=SYS_ADMIN(Docker),也会静默降级。
验证方式:
- Linux/macOS:
ls -la vendor/vendor/name,看到箭头->才是 symlink - Windows:
dir vendorendor ame,看到JUNCTION或SYMLINKD才对 - 若显示普通文件夹,说明已 fallback,立刻检查本地包根目录下的
composer.json
autoload不加载新类?别忘了dump-autoload -o
path 仓库让包“存在”,但new AcmeServiceFoo()仍报Class not found,往往不是 Composer 没识别到包,而是自动加载映射没更新。
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
PSR-4 映射只在composer dump-autoload时生成,且-o(optimize)才能启用 classmap 加速并覆盖旧映射。
执行前确认两件事:
- 本地包
composer.json中autoload段写的命名空间和路径是否与真实文件结构一致(例如"Acme\": "src/"对应src/Service/Foo.php) - 主项目执行的是
composer dump-autoload -o,不是composer install或update——后者默认不重建 autoload - Linux 部署时注意大小写:文件名
Foo.php≠foo.php,Windows 不报错,服务器上直接挂
IDE断点不触发?检查路径映射是否对齐
Xdebug 在本地包源码里打不了断点,常见原因是 IDE(如 PhpStorm)里配置的路径和 PHP 实际加载的物理路径不一致。比如 IDE 认为/Users/me/my-pkg/src是源码目录,但 Composer symlink 后 PHP 加载的是/Users/me/project/vendor/acme/utils/src,而 IDE 并未将二者关联。
解决方法很直接:
- 在 IDE 的
Settings → PHP → Servers中,把本地包的绝对路径(如/Users/me/my-pkg)映射到 vendor 下的真实路径(如/Users/me/project/vendor/acme/utils) - 确保
composer.json里autoload路径是相对的(如"src/"),不要写死绝对路径 - 改完后重启 IDE 和 Web Server,否则缓存可能让断点继续失效
路径依赖不是“装上就完事”的功能,name、symlink、autoload、IDE 四层必须全部对齐,漏一环就会表现为“update 失败”或“行为异常”。最隐蔽的坑永远藏在本地包自己的composer.json里,而不是主项目的配置中。










