Composer如何实现依赖项的离线安装_利用缓存目录进行内网迁移【离线技巧】

离线安装Composer依赖需确保缓存完整、lock文件可信且环境一致：检查缓存目录中dist包shasum是否匹配，确认PHP与Composer版本及扩展完全相同，并使用COMPOSER_DISABLE_NETWORK=1配合--no-plugins --no-scripts --no-autoloader等参数强制禁用网络。

很多人以为离线安装依赖，无非就是拔掉网线再运行 composer install。其实不然，真正的离线安装，是让整个安装过程完全不触发任何HTTP请求。这背后有个硬性前提：缓存必须准备就绪、锁文件绝对可信，并且所有的元数据校验都能在本地完成。缺了任何一环，离线安装都无从谈起。

怎么确认缓存目录里真有你要的包？

首先得明白，Composer的默认缓存目录（~/.composer/cache/files/）只存放dist包，也就是ZIP或TAR压缩包。像source源码包或者git克隆的数据，是不会自动存进去的。所以，如果你的 composer.lock 文件里，某个依赖项的 "type" 标注为 "git"，或者它的 "dist" 字段指向一个私有Git地址，那这个包压根就不会出现在默认缓存里。

• 第一步，先做个检查。运行 composer show vendor/package --all，看看目标包是否被标记为 dist 类型。如果不是，那它基本不会从缓存加载。
• 第二步，仔细核对 composer.lock。找到对应包的条目，确认它包含 "dist": {"shasum": "xxx", "url": "https://..."} 这段信息。离线时，那个URL地址不重要，但那个 shasum 校验值至关重要——它必须和缓存里ZIP文件的校验和完全匹配。
• 最后，不妨手动去缓存目录看一眼。比如 monolog/monolog 的 v2.4.0 版本，缓存路径通常是 ~/.composer/cache/files/monolog/monolog/abc123.zip，文件名就是由shasum决定的。

迁移缓存前必须对齐 Composer 版本和 PHP 平台约束

环境不一致，是离线安装失败的隐形杀手。不同版本的Composer，生成的缓存结构可能互不兼容。更棘手的是，如果目标机器的PHP版本或缺少某些扩展，composer install 可能会静默跳过某些包的安装，等到项目运行时才抛出 Class not found 的错误，让你措手不及。

• 所以，在源机器和目标机器上，务必确保 composer --version 和 php -v 的输出完全一致。
• 别忘了检查 composer.json 里的 "platform" 配置（比如 "php": "8.2.0"），目标机的PHP版本绝不能低于这个设定值。
• 另外，如果你习惯使用 --prefer-dist 参数，得确保所有依赖包都支持dist方式安装。有些私有包可能只提供 "type": "package" 加 "source" 的方式，遇到这种情况，就得考虑换成artifact仓库或者path本地路径的方式了。

离线机执行 install 时最关键的三个参数

即使vendor目录已经存在，默认的 composer install 命令依然会尝试访问packagist.org进行元数据校验。因此，必须通过明确的参数来压制这些联网行为。

• 加上 --no-plugins --no-scripts：这能防止post-install-cmd之类的钩子脚本因为缺少网络而卡死或报错。
• 加上 --no-autoloader：可以避免在生成自动加载文件时，某些插件去读取远程配置。
• 最关键的一步：设置环境变量 COMPOSER_DISABLE_NETWORK=1。这才是强制跳过所有仓库请求的“硬开关”，光靠 --no-interaction 是远远不够的。

完整的正确命令应该是这样：COMPOSER_DISABLE_NETWORK=1 composer install --no-plugins --no-scripts --no-autoloader --prefer-dist --no-interaction

为什么有时明明缓存拷过去了，install 还是去联网？

这个问题很常见，根源往往被忽略。当 composer.lock 里某个包的 dist.url 指向一个HTTPS地址，而Composer在离线模式下，发现缓存里没有能匹配shasum的ZIP文件时，它不会明确告诉你“缓存缺失”，而是可能卡住，或者直接报一个 Failed to download 的错误。

• 怎么验证？给install命令加上 -v 参数，查看详细日志。如果看到 Loading from cache 就说明成功了；如果出现了 Downloading...，那毫无疑问，缓存没有命中。
• 如何补救？回到能联网的机器上，使用 composer require vendor/package --update-with-dependencies 命令，强制拉取一次完整的依赖树，然后重新打包缓存目录。
• 还有一个更彻底的方案：使用artifact仓库。把所有ZIP包直接放进项目的 ./packages/archives 目录，然后在composer.json中配置 "type": "artifact"。这样，Composer会直接扫描本地目录，既不查询远程仓库，也不依赖复杂的shasum匹配逻辑。

说到底，缓存迁移这件事，看着步骤简单，但成败完全取决于锁文件、缓存内容、PHP环境这三者能否严丝合缝地匹配。缺少任何一个条件，COMPOSER_DISABLE_NETWORK=1 这个命令，也不过是让你更快地看到报错信息而已。