离线安装需先在联网机生成含完整 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.lock 校验、或混用 source/dist 混合缓存的操作，都会在切换环境时暴露一致性裂缝。 
