Composer离线缓存的核心是导出files/子目录并配置cache-files-dir：需先联网执行composer install --prefer-dist生成合法zip包，再复制该目录到离线机并显式配置路径，否则仅复制cache-dir无效。
Composer 本地缓存本身不是“建立”的，而是 Composer 在运行 composer install 或 composer update 时自动写入的产物；但如果你真正想要的是「离线可用、可迁移、可复用」的完整依赖缓存（即能脱离 packagist.org 运行），那就必须主动导出 files/ 子目录并配对使用 cache-files-dir——这不是普通缓存，是离线部署的最小可行单元。
为什么 cache-dir 不等于离线缓存能力
Composer 的 cache-dir 是个混合目录：里面包含 archived/（.zip/.tar 包）、repo/（packagist.org 的 packages.json 响应）、files/（实际解压前的归档副本）等。但只有 files/ 下的每个 vendor/package/version.zip 文件，才是离线安装时真正被 --prefer-dist 直接读取和解压的实体。其他子目录（如 repo/）在离线时会失效，除非你额外抓取并固化元数据。
常见误区：
- 只复制整个
cache-dir到内网，却不验证files/是否齐全 → 安装时仍报Could not find package ... in a version matching ... - 改了
cache-dir却没清旧缓存 → Composer 随机从两个路径读取，行为不可预测 - 在 CI 中设了
COMPOSER_CACHE_DIR，但未挂载持久卷 → 每次构建都是空缓存，等于白配
cache-files-dir 是离线场景唯一该配的路径
这个配置项专为离线设计，它只控制 files/ 子目录的位置，不干扰 repo/ 或 archived/。一旦设好，Composer 就会把所有下载的 dist 包（.zip/.tar）强制写入该路径，方便你打包带走。
操作步骤：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 联网机器上，先确保项目有
composer.lock，然后运行：composer config --global cache-files-dir /path/to/offline-cache
- 再执行：
composer install --no-autoloader --no-scripts --prefer-dist
（这会触发下载，且全部落到/path/to/offline-cache下） - 检查目标目录是否生成了类似
monolog/monolog/2.10.0.0/monolog-monolog-6a8c4b5.zip的结构 —— 这才是有效离线包 - 内网机器上，同样执行
composer config --global cache-files-dir /your/copied/cache/path，再跑composer install --no-autoloader --no-scripts --prefer-dist
注意：cache-files-dir 优先级低于 cache-dir，但高于默认值；如果已设过 cache-dir，建议先 composer config --global --unset cache-dir 再设 cache-files-dir，避免冲突。
自建镜像仓库？先确认你真需要它
90% 的所谓「内网镜像需求」，其实只需要一份干净的 files/ 缓存 + 固定的 composer.lock。Satis、Toran Proxy 或 Private Packagist 这类服务，本质是模拟 packagist.org 的 HTTP 接口，提供 packages.json 和重定向下载，但它们：
- 无法绕过 GitHub/GitLab 等源站的访问限制（比如私有 repo 的 token 校验）
- 元数据更新需定时拉取，若上游删包或改 license，镜像不会自动同步
- 部署运维成本远高于直接复制
files/目录
只有当满足以下全部条件时，才值得上镜像服务：
- 多个团队/项目共享同一套依赖生态
- 需要支持私有包（非 packagist.org 上的）并统一鉴权
- 有专人维护元数据 freshness 和安全扫描
否则，就老实用 cache-files-dir + rsync 或 tar -cf 打包传输，快、稳、无中间件依赖。
最容易被忽略的一点：files/ 目录里的每个 zip 文件名，是 Composer 根据包名、版本、dist URL 的 hash 生成的，不是原始文件名。所以不能靠「手动下载 rename 后丢进去」来伪造——必须让 Composer 自己下载一次，它才会生成合法路径和校验信息。
