本地调试Composer包必须用path仓库+"*"约束,因Composer不识别本地路径版本号;写死版本如1.2.3会被当作远程包查找而失败,path仓库仅读取本地composer.json的version字段。

本地调试 Composer 包必须用 path 类型仓库 + "*" 版本约束,其他写法(如 ^1.2.0、dev-main、1.2.3)都会失败或静默失效。
为什么 composer require vendor/pkg:1.2.3 会报错
Composer 默认只查 Packagist 或 Git 仓库,不解析本地路径。你写的 1.2.3 被当成远程包名去搜,结果返回 Could not find package。
-
repositories没配、类型不是path→ 直接失败 - 写了
"vendor/pkg": "^1.2.0"→ 不报错但无效,仍按本地composer.json的version字段装,还可能带 warning -
url写成https://或git@→ 被当 VCS 处理,跳过本地读取逻辑
path 仓库配置的硬性要求
这是唯一能启用本地包的入口,错一个字就白搭。
-
type必须是"path",不能是"package"或"vcs" -
url是相对于项目根目录的路径,支持./packages/foo或绝对路径,但不能带尾部斜杠 - 该路径下必须存在合法的
composer.json,且其中name字段要和require中完全一致(包括大小写) - 路径含空格或特殊字符不用转义,但得确保 shell 能访问(CI 环境里权限问题常被忽略)
为什么 require 里只能写 "*"
path 类型仓库不参与语义化版本解析——它本质是“符号链接式挂载”,Composer 只做一次读取:拿到本地包 composer.json 里的 version,然后照单全收。
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
- 写
"*"是唯一明确告诉 Composer “请信任本地version字段” 的方式 - 写
"dev-main"或"1.2.3@dev"→ 报错Invalid version string,因为path不支持稳定性标记 - 想“锁定”内容?靠的是文件系统快照(Git commit hash / 文件修改时间),不是版本号字符串
- 本地
composer.json里version改了,下次composer update就立刻生效,无需改主项目require
调试失败时优先检查这三件事
别急着删 composer.lock 重装。
- 运行
composer config repositories,看输出里有没有你配的path条目,以及url是否拼错 - 进本地包目录,执行
composer validate,确保它的composer.json语法合法、name字段存在且匹配 - 执行
composer show vendor/pkg,如果返回Package not found,说明仓库没注册成功;如果返回版本信息但和本地composer.json不一致,说明version字段被覆盖或缓存未刷新(可加-vvv看详细日志)
最易被忽略的是:CI 环境中某些 Docker 镜像或部署脚本会自动清理 vendor,但忽略 repositories 配置,导致本地包在构建时根本没加载进去。










