离线安装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 这个命令，也不过是让你更快地看到报错信息而已。
