composer怎么强制使用本地缓存？

composer 离线安装核心是启用 –offline 模式，强制跳过网络请求、仅从本地缓存（~/.composer/cache/）或 vendor/ 读取包；需提前联网执行 composer install 写入缓存，确保 composer.lock 中的 exact version 和 shasum 与缓存文件匹配，私有仓库需预先配置，ci/cd 中须显式缓存并恢复 ~/.composer/cache/ 目录。

composer install 时跳过远程包下载

强制走本地缓存，本质是让 Composer 完全不碰网络，只从 vendor/ 或 ~/.composer/cache/ 里找包。但注意：Composer 默认不会“自动回退到缓存”，它只在首次安装或版本变更时才下载；所谓“强制缓存”，其实是关掉网络依赖、确保离线可用。

• 加 --no-install 没用，那是跳过安装步骤，不是跳过下载
• 真正起效的是 --prefer-source 和 --prefer-dist 的组合行为——但它们不控制缓存，只控制包来源类型
• 核心开关是 --offline：启用后 Composer 拒绝任何 http 请求，找不到本地副本就直接报错，不会尝试 fallback 到 packagist

怎么提前把包塞进本地缓存

缓存不是“用了就自动变快”，而是靠 composer install 或 composer update 过程中下载的包被存进 ~/.composer/cache/（linux/macos）或 %LOCALAPPDATA%Composercache（windows）。想离线能用，得先联网跑一遍，且确保缓存没被清空。

• 运行 composer install --no-scripts --no-dev（按需删减），触发缓存写入
• 别手动删 ~/.composer/cache/files/ 下的 zip，那是 dist 包缓存，删了 offline 就失效
• composer clear-cache 会清空所有，离线前务必确认没执行过
• 如果项目用的是私有 repo，要提前用 composer config --global repositories.xxx 注册好，否则 offline 时连 repo 地址都解析不了

为什么 –offline 还是报错 “Package not found”

常见于两种情况：缓存里压根没这个包，或者包的 hash 不匹配（比如你改过 composer.lock 但没更新缓存）。Composer 的 offline 模式非常严格——它不校验“有没有类似版本”，只认 lock 文件里写的 exact version + exact hash。

• 检查 composer.lock 里对应包的 dist.shasum 字段，再去看 ~/.composer/cache/files/[vendor]/[package]/[hash].zip 是否存在且大小非零
• 私有包若用的是 path repository，--offline 是 OK 的，但必须确保 path 路径真实存在且可读
• 如果用 composer require xxx 增量装包，记得加 --no-update，否则会触发网络请求去 resolve 新依赖

CI/CD 中稳定复用缓存的实操要点

在 github Actions 或 gitlab CI 里想靠缓存提速，不能只靠 --offline，因为 runner 是干净环境，缓存目录默认为空。必须显式 restore + save 缓存路径。

• 缓存路径要覆盖 ~/.composer/cache/ 全量，不是只缓存 vendor/
• GitHub Actions 示例：composer install --no-interaction --no-progress --prefer-dist --optimize-autoloader --offline 必须放在 cache restore 之后、且前面没任何 composer update
• GitLab CI 注意：默认镜像可能没预装 Composer，或版本太老（composer –version 确认
• 如果项目用了 platform-check 或 config.platform，某些 PHP 扩展缺失会导致 install 卡住，这和缓存无关，但容易误判为“缓存失效”

缓存路径是否真实存在、lock 文件里的 shasum 是否与磁盘文件一致，这两点最容易被忽略。offline 模式下没有模糊匹配，差一个字符就失败。