私有仓库本身不加速下载，它解决的是“能不能下”和“安不安全”，真正的加速靠镜像源+缓存+dist策略三者协同；配置后变慢主因是默认走vcs/source模式、缺乏dist支持、HTTPS/HTTP2未启用、缓存未挂载或响应头无Cache-Control。
私有仓库本身不加速下载，它解决的是“能不能下”和“安不安全”，真正的加速靠镜像源 + 缓存 + dist 策略三者协同。
为什么私有仓库配置后反而更慢？
私有仓库（如 Satis、Private Packagist、GitLab Composer Registry）默认走 vcs 或自建 composer type 源，这类源不享受公共镜像加速——Composer 会直接向你的私有服务发起 HTTP 请求或 git clone，网络延迟、认证开销、服务响应慢都会拖累整体安装速度。
- 私有源 URL 是
https://packages.internal.corp，但没配 HTTPS 证书或没开 HTTP/2，TLS 握手就耗几百毫秒 - 用
vcstype 指向 Git 仓库时，Composer 默认走source模式（即 git clone），比dist慢 3–10 倍 - 私有包自身
composer.json中没声明"dist"字段，导致无法预生成 ZIP 包，每次 install 都得现场打包 - CI 环境没挂载缓存目录，每次构建都重下所有私有包
如何让私有包也走 dist 下载？
关键不是换源，而是让私有包支持 dist 分发。Satis 和现代 Private Packagist 都支持生成 ZIP 包并托管在同个域名下，只需两步确认：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 检查私有仓库生成的
packages.json中，对应包的版本项是否含"dist"字段，例如：{"type": "zip", "url": "https://packages.internal.corp/dist/myorg/utils-1.2.0.zip", "reference": "abc123"} - 确保私有包自己的
composer.json里有"archive": {"exclude": ["/tests/", ".gitignore"]}配置，否则 Satis 不会生成 dist - 项目中强制走 dist：
composer install --prefer-dist；若仍 fallback 到 source，加-v看日志里是否出现Downloading https://...而非Cloning...
私有源 + 公共镜像如何共存且不冲突？
必须显式分层声明，且顺序决定查找优先级。错误写法是把私有源塞进 repo.packagist 全局配置——这会直接覆盖整个 Packagist 代理逻辑。
- 正确结构：在项目级
composer.json的repositories字段里，按顺序列多个源：{"type": "composer", "url": "https://packages.internal.corp"}放第一行，{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}放第二行 - 必须保留
"packagist.org": false键（不是"packagist"），否则 Composer 2.9+ 会忽略你配的所有composertype 源 - 验证是否生效：
composer install -vvv中看到请求发往packages.internal.corp/packages.json和mirrors.aliyun.com/composer/packs/xxx.json，才算真正共存
缓存路径和权限是企业环境最容易漏的点
私有包下载慢，80% 情况下不是网络问题，而是缓存没命中或被拒绝写入。
- 全局缓存路径需可写且不跨网络盘：
composer config -g cache-dir /data/composer-cache（Linux）或composer config -g cache-dir C:\temp\composer-cache（Windows） - Docker CI 中必须挂载缓存卷：
-v $(pwd)/.composer-cache:/root/.composer/cache，否则每次容器启动都是全新缓存 - 私有源返回的 HTTP 响应头里必须带
Cache-Control: public, max-age=3600，否则 Composer 不缓存元数据 - 如果用了
auth.json认证，文件权限必须是600，且不能放在 NFS 或 SMB 共享盘上（Composer 会跳过）
真正卡住的地方往往不在配置语法，而在私有包自身的 composer.json 是否声明了 dist、私有仓库服务是否启用了 HTTP 缓存头、以及 CI 容器里那个看似无关的缓存挂载路径有没有写错。这些细节不验证，光调 config 命令毫无意义。
