必须用path仓库+Git初始化,因Composer只认已git init且commit的本地目录;未初始化Git时即使composer.json合法也会静默跳过,不报错也不装包。

本地包必须用 path 类型仓库 + Git 初始化
Composer 不会把任意目录当包用,path 类型仓库只认已初始化 Git 的本地目录。没 git init、没 git commit,哪怕 composer.json 写得再标准,composer update 也会静默跳过——不报错,也不装包。
常见错误现象:Could not find package vendor/name at any version,其实不是网络问题,而是 Git 状态不满足。
- 进本地包目录,运行
git init && git add . && git commit -m "init" - 如果不想用 Git,可在本地包的
composer.json里加"version": "dev-main"显式声明,但这是临时绕过,不是推荐做法 -
url必须指向含composer.json的目录,不能是文件路径(比如不能写成../my-pkg/composer.json)
repositories 必须写在主项目 composer.json 顶层
这个字段不能嵌套在 config、extra 或任何其他字段下,也不能写在本地包自己的 composer.json 里——对主项目完全无效。
正确位置是主项目根目录 composer.json 的最外层,和 require、autoload 平级。
- 错误写法:
"extra": { "repositories": [...] }→ Composer 直接忽略 - 错误写法:
"config": { "repositories": [...] }→ 同样无效 - 正确写法示例:
"repositories": [ { "type": "path", "url": "../my-pkg" } ]
name 字段必须逐字节匹配,大小写敏感
90% 的 Could not find package 是因为 name 不一致。不是“看起来一样”,是字节级完全相同:空格、斜杠、大小写、连字符,一个都不能差。
使用 GitHub Next 的 CI Doctor 工作流来监视 GitHub Actions 运行、拉取失败日志、追踪重复模式,并打开带有具体下一步操作的调查问题。这是供代理作为 CI 失败调查员使用的,而不是用于将 GitHub Agentic Workflows 列为产品。
主项目 require 写的是 "acme/utils": "*",那本地包 composer.json 的 name 就只能是 "acme/utils"。
-
"Acme/Utils"→ 不匹配 -
"acme-utils"→ 不匹配 -
"acme/utils-dev"→ 不匹配 - 验证方式:进本地包目录执行
composer validate,看输出是否提示name缺失或格式错误
symlink 需手动启用且平台行为不同
默认不创建符号链接,composer install 或 update 会 copy 文件内容,改了本地包代码也不会实时生效。
要真正“调试”,必须显式开启 symlink,并注意平台限制:
- 在
repositories条目里加"options": {"symlink": true} - Linux/macOS 下通常可用;Windows 必须以管理员身份运行终端,否则创建失败且无提示
- 首次接入必须用
composer update vendor/name,install不重建链接 - 验证是否成功:检查
vendor/vendor/name是否是符号链接,指向你本地的目录
最容易被忽略的是 Git 初始化和 symlink 显式配置——这两个条件漏掉任何一个,整个本地调试流程就卡在“看似配置对了,但就是不生效”的状态里。

















