如何在一个离线环境中使用Composer安装依赖？ (本地缓存或打包)

离线安装需先在联网机生成含完整 dist zip 和 composer.lock 的缓存包，再通过 –repository-url=file:// 指向本地 dist 目录执行 install，确保按 lock 文件精确还原依赖并校验完整性。

离线安装前必须准备一个完整的 vendor 缓存包

离线环境无法访问 packagist.org 或其他远程仓库，composer install 会直接失败。核心前提是：你得在有网络的机器上提前生成一份「可离线复用」的依赖快照——不是只复制 vendor/，而是要确保所有包（含 dist zip、git commit hash、autoload 映射）能被离线还原。

• 在联网机器上，用 composer install --no-dev --prefer-dist --optimize-autoloader 安装，确保走的是压缩包（dist）而非源码（source），体积更小、校验更稳
• 执行 composer archive --format=zip --file=deps-full.zip 打包整个 vendor/ 目录（需 Composer 2.5+；旧版本可用 zip -r deps-full.zip vendor/）
• 同时备份 composer.lock —— 离线机必须用它来对齐版本，不能只靠 composer.json

离线机上用 –repository-url 指向本地 dist 包目录

单纯复制 vendor/ 到离线机并运行 composer install 仍可能触发网络请求（比如 autoload 重建、插件初始化或某些包的 post-install-cmd）。更可靠的方式是让 Composer 把本地文件夹当成「私有仓库」来读取 dist 包。

• 把联网机上 ~/.composer/cache/files/ 下的全部 .zip 文件（按 vendor/name/commit-hash.zip 结构组织）拷贝到离线机某路径，例如 /opt/composer-dist/
• 在离线机项目根目录运行：

  composer install --no-dev --prefer-dist --repository-url=file:///opt/composer-dist/

• 该命令会让 Composer 跳过 packagist，只从本地路径查找 zip 包，并按 composer.lock 中记录的 exact commit 和 sha256 验证完整性

遇到「Package not found」错误时优先检查 lock 文件与 cache 的匹配性

离线安装失败最常见的原因是 composer.lock 里记录的某个包 hash，在本地 dist 目录中找不到对应 zip 文件——这通常因为联网机没完整下载所有依赖（比如中途 Ctrl+C、磁盘满、或用了 --ignore-platform-reqs 导致跳过某些平台特定包）。

• 在联网机执行 composer show --all --locked，确认每个包的 dist.url 字段是否为 https://api.github.com/... 类型；若出现 source 类型，说明该包被强制走了 git clone，无法打包为 zip
• 检查 composer.lock 中每个包的 dist.shasum，然后在本地 dist 目录里搜索对应文件名（如 monolog/monolog/7f10e4d9a18b95c6b1202f67597c5f6e.zip）
• 如果缺失，回到联网机，删掉 vendor/ 和 composer.lock，改用 composer update --no-dev --prefer-dist --with-dependencies 强制刷新所有 dist 包

php 版本和扩展差异会导致离线安装后运行时报错

即使 composer install 成功，离线机 PHP 环境不一致也会让应用启动失败——这不是 Composer 的问题，但常被误认为是离线流程出错。

• 离线机 PHP 版本必须 ≥ composer.json 中 config.platform.php 或 require.php 声明的最低版本；否则 composer install 可能静默跳过某些包
• 检查是否启用了必要扩展：比如 ext-zip（解压 dist）、ext-json（解析 lock）、ext-openssl（验证签名）；缺少任一都可能卡在「Verifying archive integrity」阶段
• 若离线机是 Alpine linux，注意 php-zip 和 php-phar 是独立包，需显式安装，不能只装 php

离线依赖管理的关键不在「怎么复制文件」，而在于让 Composer 相信它面对的是一个功能完整的、可验证的 dist 仓库。任何跳过 composer.lock 校验、或混用 source/dist 混合缓存的操作，都会在切换环境时暴露一致性裂缝。