repositories 字段必须写在项目根目录的 composer.json 文件顶层,与 require、autoload 同级,不可放在 vendor 或子包中;仅对当前项目生效,按数组顺序匹配,vcs 类型 url 应为干净的代码托管地址。

repositories 字段写在哪?不是写在 vendor 里
它必须出现在项目根目录的 composer.json 文件顶层,和 require、autoload 同级。写进子包的 composer.json 或者 vendor/composer/installed.json 都无效——Composer 只读取你当前项目的主配置。
常见错误现象:composer require my/private-package 报错 Could not find package my/private-package,但明明写了 repositories ——八成是放错了文件,或者没加 "type": "vcs"。
- 只对当前项目生效,不继承给依赖项(除非显式设置
"packagist.org": false) - 多个仓库按数组顺序匹配,靠前的优先;同名包会用第一个能解析到的版本
- 如果同时启用了 Packagist 官方源,又没禁用,它默认排最前,你的私有包可能被跳过
vcs 类型仓库怎么填 URL?别带 .git 后缀也不用 ssh
URL 值得是代码托管地址,不是 Composer 包地址。GitHub/GitLab/自建 Git 服务都走 "type": "vcs",但 URL 格式要干净:
- HTTPS 推荐:用
"url": "https://gitlab.example.com/group/project.git"——.git后缀可以留,但不是必须;去掉也行,Composer 能自动补全 - SSH 不推荐:像
"git@gitlab.example.com:group/project.git"在 CI 或无密钥环境大概率失败 - 别写成
https://gitlab.example.com/group/project/tree/main/composer.json这种页面链接,Composer 解析不了 - 私有 GitLab 自建实例要注意:确保 Composer 能访问该域名,且未被公司代理拦截(常见于
curl: (7) Failed to connect)
示例正确写法:
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/my-team/utils"
}
]
package 类型适合什么场景?不是拿来托管 zip 包的
"type": "package" 是手动声明一个“不存在于任何 Git 仓库”的包,比如你只有 ZIP 包或内部 PHP 工具脚本,没有 Git 元数据。它本质是硬编码包信息,不支持版本自动发现。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论(Discussion)”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性,以及撰写结论。当用户输入以下任一指令时也会自动触发该功能: - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 必须手写完整
version、dist(含url和shasum)、source(可选)字段 -
dist.url必须是可直接curl下载的公开 HTTP(S) 地址,不能是本地路径或内网 UNC 路径 - 每次更新都要改
shasum,否则 Composer 会拒绝安装(校验失败报错:Invalid checksum for ...) - 不适合日常开发协作,仅用于极简分发或临时兜底;长期维护请用 vcs + tag
典型适用场景:把某个老系统抽出来的工具函数集打包成 ZIP,扔到内部 Nginx 目录下供几个项目引用。
为什么 run-script 没触发?因为 repositories 不影响脚本执行时机
repositories 只管「从哪找包」和「怎么下载」,不影响 scripts 的注册与执行。如果你加了自定义仓库后,composer run-script post-install-cmd 突然不运行了,问题肯定不在 repositories 字段本身。
- 检查是否误删了
"scripts"段,或拼错了钩子名(如写成post-update而非post-update-cmd) - 确认该脚本对应命令确实存在于
require-dev或已安装包中;私有仓库包里的脚本,必须先composer require成功才能被识别 - 某些 IDE 或 CI 环境会跳过脚本(例如
composer install --no-scripts),看清楚实际执行命令
一句话:repositories 是地图,scripts 是司机;地图画得再细,司机不上车也没用。
最常被忽略的是:私有包里的 scripts 不会自动注入到根项目,必须在根项目的 composer.json 中显式声明调用逻辑,或者用插件方式加载。










