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 中显式声明调用逻辑，或者用插件方式加载。
