详解Composer install命令执行时的缓存命中机制-composer-PHP中文网

composer install 能否命中缓存取决于 cache/files/ 和 cache/repo/ 是否同时存在对应包的 zip 文件和元数据 json；缺一不可，且需配合 composer_disable_network=1 才能真正离线缓存命中。

详解composer install命令执行时的缓存命中机制

Composer install 能否命中缓存，不取决于你有没有运行过 install，而取决于 cache/files/ 和 cache/repo/ 两个目录是否同时存在对应包的 ZIP 文件和元数据 JSON —— 缺一不可。

cache/files/ 和 cache/repo/ 必须共存才能真正缓存命中

Composer 的缓存不是“有文件就能用”，它走的是两级查表逻辑：先查 cache/repo/https---packagist.org/packages.json 确认某个包版本对应的 SHA256；再按这个 SHA 去 cache/files/ 找 ZIP。如果 repo/ 下没有 packages.json，哪怕 files/ 里 ZIP 齐全，Composer 也会跳过缓存、直接报错或卡住。

常见错误：只同步 files/ 目录做离线迁移 → 日志仍出现 Fetching https://repo.packagist.org/packages.json
正确做法：打包整个 cache/ 根目录（含 files/、repo/、archived/），并确保隐藏文件（如 .htaccess）不被忽略
验证方式：composer config --global cache-dir 查出路径后，手动检查 $(composer config --global cache-dir)/repo/https---packagist.org/ 下是否存在 packages.json

composer.lock 不变 ≠ 自动复用缓存，但它是缓存复用的前提

composer.lock 文件没改，只是让 Composer 跳过依赖解析阶段，不等于它就一定能从缓存装包。能否跳过下载，还要看缓存中是否有 lock 里声明的每个包的 dist ZIP 及其元数据记录。

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

若 lock 中某包版本是 "monolog/monolog": "2.10.0"，而 cache/repo/ 里只有 2.9.0 的记录 → 缓存不命中，会尝试联网拉取
若 lock 没变，且 cache/files/ 中已有该 ZIP，cache/repo/ 中也有对应 SHA 记录 → Composer 直接解压，不发任何网络请求
注意：即使缓存命中，composer install 仍会读取 vendor/autoload.php 并生成 autoloader（除非加 --no-autoloader）

--prefer-dist 不是缓存开关，而是包来源策略

--prefer-dist 的作用是告诉 Composer “优先选 dist（ZIP/TAR 包）而不是 source（Git 克隆）”，但它本身不触发缓存，也不保证缓存一定生效。它只是让 Composer 在决定用哪个包时，把 dist 类型排在前面。

当缓存中既有 dist ZIP 又有 source clone 记录时，--prefer-dist 会让 Composer 选 ZIP
当缓存中只有 source（比如之前用 --prefer-source 装过），--prefer-dist 会失败并报错，因为找不到 dist 缓存
CI 场景下建议固定使用 --prefer-dist + 挂载完整 cache/ 目录，避免因 source 缓存缺失导致 fallback 到慢速 Git 克隆

COMPOSER_DISABLE_NETWORK=1 是离线缓存命中的硬性守门员

没有这个环境变量，哪怕缓存目录 100% 完整，composer install 也会在启动时尝试请求 https://repo.packagist.org/packages.json，然后卡住或报 Could not fetch。

--no-network 是无效参数，Composer 官方根本不识别它
--offline 只跳过更新行为，挡不住初始元数据请求
Linux/macOS：必须前置写成 COMPOSER_DISABLE_NETWORK=1 composer install --prefer-dist
Windows PowerShell：得用 $env:COMPOSER_DISABLE_NETWORK="1"; composer install --prefer-dist

缓存机制本身很朴素，但它的生效链条很长：lock 文件 → repo 元数据 → files ZIP → 环境变量守门。任意一环断裂，都会退化成全量联网安装。最常被忽略的，其实是 repo/ 目录的存在感——它不像 ZIP 那样“看得见”，却决定了整个缓存系统能不能启动。