私有仓库镜像生效需满足三条件：repo.packagist键名单数、type值为composer、URL为HTTPS且末尾带/；验证必须输出完整JSON如{"type":"composer","url":"https://your-private-mirror.com/"}，并执行composer clear-cache后用composer install -vvv确认日志中请求/p2/路径。
如何确认私有仓库镜像是否真正生效
私有仓库缓存失效，90% 是因为镜像配置根本没走通。Composer 不报错，但会静默 fallback 到原始源（比如 packagist.org 或你定义的私有 URL），导致所有缓存都白配。
必须执行 composer config -g repo.packagist，输出必须是完整 JSON 对象，例如：{"type": "composer", "url": "https://your-private-mirror.com/"}。以下情况均无效：
- 输出为纯字符串
"https://your-private-mirror.com/" - 输出为
null或空行 - 字段名写成
repos.packagist（多一个s）——Composer 忽略但不提示 - URL 缺末尾斜杠，如
https://your-private-mirror.com→ 必须是https://your-private-mirror.com/ - 在 CI 中用
sudo composer config -g，写入了 root 的配置，但实际运行用户是gitlab-runner或www-data
验证是否真走镜像：加 -vvv 运行 composer install，日志中出现 GET https://your-private-mirror.com/p2/xxx.json 才算成功；若看到 GET https://packagist.org/ 或原始私有域名的非 /p2/ 路径，说明配置未生效。
私有仓库缓存路径必须满足的三个硬性条件
缓存目录不是设了就起效。对私有仓库而言，cache-dir 必须同时满足：
-
绝对路径：不能含
~，composer config -g cache-dir ~/.composer-cache看似正常，实则创建字面目录~/，最终 fallback 到默认路径 -
挂载在高速本地盘：若指向 NFS、Docker volume 或慢速云盘，解压 ZIP 包和读取
repo/元数据会卡顿，缓存反而拖慢安装 -
当前用户有完整读写权限：尤其 CI 容器中，
mkdir -p /data/composer-cache && chown -R $USER:$USER /data/composer-cache必须显式执行
推荐写法：composer config -g cache-dir "/tmp/composer-cache"（Linux/macOS 临时盘通常为内存或 SSD）；CI 中更稳妥的是用环境变量：COMPOSER_CACHE_DIR=$HOME/.composer-cache-$(php -r 'echo PHP_VERSION_ID;')，避免多 PHP 版本混用。
离线场景下私有包 ZIP 缓存必须单独配置 cache-files-dir
私有仓库离线安装失败，常见原因是只改了 cache-dir，但没告诉 Composer 去哪找 ZIP 包。cache-dir 和 cache-files-dir 是两套路径逻辑：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
cache-dir是总根目录，下面有files/、repo/、vcs/子目录 -
cache-files-dir是专门存 ZIP 包的路径，默认等于$cache-dir/files，但可单独设置，且composer install --prefer-dist断网时只认它
正确操作：
- 先清旧配置：
composer config -g --unset cache-dir（避免冲突） - 再设专用路径：
composer config -g cache-files-dir "/opt/offline-cache/files" - 验证是否写入：
ls -l /opt/offline-cache/files/your-vendor/your-package/1.2.3.0/，应能看到类似your-vendor-your-package-abc123.zip的文件
注意：cache-files-dir 必须存在且可写，否则 --prefer-dist 会直接报错退出，不 fallback。
composer install 在私有仓库中必须带的参数组合
漏掉任意一个，私有仓库缓存利用率就会断崖式下跌：
-
--no-dev：跳过require-dev，省掉私有工具包（如内部 linter、mock server）的下载和解压，节省 30%–60% 时间 -
--prefer-dist：强制走 ZIP 包安装，比--prefer-source更快更稳定；即使某私有包没提供 dist，Composer 也会自动 fallback，无需担心 -
--optimize-autoloader（或-o）：生成vendor/composer/autoload_classmap.php，减少类加载时的文件系统扫描，PHP 7.4+ 下还能进 opcache
生产构建黄金命令：composer install --no-dev --prefer-dist --optimize-autoloader。若私有包不含运行时生成类，可追加 --classmap-authoritative 进一步提速，但开发环境绝对禁用——新增类会直接 Class not found。
私有仓库缓存最易被忽略的一点：镜像 URL 和缓存路径必须同步清理。改完镜像后不执行 composer clear-cache，Composer 仍会从旧 repo/ 目录读取过期元数据，导致 composer install 卡在 “Loading composer repositories” —— 表面看是网络问题，实则是缓存污染。
