私有包必须在项目composer.json的repositories数组中显式声明，镜像源仅代理packagist.org元数据，对vcs/package类型私有源无感知；repositories须为数组、type必须合法、URL须可git clone或含有效dist，且需清缓存、删lock、重装。
私有包必须显式声明 repositories，不能只靠全局镜像
Composer 默认不查私有源，哪怕你已配好阿里云镜像，composer install 仍会跳过你的 GitLab 或 GitHub 私有仓库——因为镜像源只代理 packagist.org 的公开元数据，对 "type": "vcs" 或 "type": "package" 类型的私有定义完全无感知。
必须在项目 composer.json 的 repositories 字段里显式列出，且顺序和写法直接影响是否生效：
-
repositories必须是数组（不是对象），否则 Composer 解析失败，报错Invalid repository type或静默忽略 - 私有源条目需放在数组首位，否则可能被后续的
packagist条目覆盖 - 若同时用国内镜像 + 私有包，必须手动加
{"packagist.org": false}禁用兜底，否则 Composer 在私有源未命中时仍会 fallback 到官方源（哪怕你已配镜像）
Git 仓库类私有包：type=vcs + url 是 HTTPS/Git URL
适用于托管在 GitHub、GitLab、Bitbucket 的私有仓库，Composer 会自动解析 composer.json 并支持语义化版本（如 "dev-main", "^2.0"）。
正确写法示例（写入项目 composer.json 的 repositories 数组中）：
{
"type": "vcs",
"url": "https://gitlab.example.com/myorg/my-package.git"
}
常见坑点：
- URL 必须可被机器直接
git clone；若需 SSH，改用git@gitlab.example.com:myorg/my-package.git，并确保宿主机或 CI 环境已配置 SSH key - GitLab 私有项目若启用了 2FA 或 IP 白名单，需在 URL 中嵌入 Personal Access Token：
https://oauth2:<token>@gitlab.example.com/myorg/my-package.git - 不要在
url后加.git以外的路径（如/tree/main），Composer 不识别
静态包类私有包：type=package + 手动写 version 和 dist
适用于无法提供 Git 访问权限、或只想发布 ZIP 归档的场景（比如交付给客户闭源组件）。它绕过 Git，靠人工维护元数据。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
示例（repositories 数组中的一项）：
{
"type": "package",
"package": {
"name": "mycorp/secret-sdk",
"version": "1.2.0",
"dist": {
"url": "https://files.mycorp.com/secret-sdk-1.2.0.zip",
"type": "zip"
},
"autoload": {
"psr-4": { "MyCorp\SecretSdk\": "src/" }
}
}
}
关键约束：
-
version必须是完整版本号（不能写dev-master），且与dist.url实际文件名一致 -
dist.url必须返回 HTTP 200，支持 Range 请求（否则下载中断），且服务器需允许跨域（CI 中 fetch 失败常因 CORS） - 不能依赖
require自动解析子依赖——所有依赖必须在package对象内显式声明"require": {...}
私有源 + 镜像共存时，清缓存和删 lock 是强制动作
一旦改过 repositories，旧 composer.lock 里记录的包来源仍是原地址，Composer 会坚持校验旧哈希，导致 install 报 hash does not match 或 Could not find package。
必须执行三步（缺一不可）：
- 运行
composer clear-cache—— 清掉本地元数据缓存（含旧源的 packages.json） - 删除
vendor/和composer.lock - 运行
composer install --no-cache强制重新解析全部源
特别注意：Windows 下若用 WSL 或 Docker，clear-cache 要在对应环境里执行；GitHub Actions 中需用 composer cache:clear（新版本命令）并确认 runner 用户有写权限。真正卡住的往往不是配置，而是缓存没清干净。
