composer install --no-dev --prefer-dist 不能直接当离线包用，因默认不保留压缩包、校验信息和元数据，离线时仍会联网请求 packagist.org；需用 composer pack 预生成含 packages.json 的本地 artifact 仓库，并在 composer.json 中配置 "type": "artifact" 指向该路径，方可完全离线安装。
composer install --no-dev --prefer-dist 为什么不能直接当离线包用
因为 composer install 默认只下载并解压包到 vendor/，不保留原始压缩包、哈希校验信息和元数据。离线环境安装时，Composer 仍会尝试访问 packagist.org 或其他仓库去获取 composer.lock 中记录的包 URL 和 checksum，一旦网络不通就报错：Could not fetch https://repo.packagist.org/p2/monolog/monolog.json。
真正能离线安装的前提是：让 Composer 完全绕过远程仓库，仅靠本地文件完成依赖解析与安装。这需要两个关键动作——预下载完整包存档 + 替换仓库源为本地路径。
用 composer archive 命令打包单个包不可行
composer archive 只是把某个已安装的包（比如 vendor/monolog/monolog）打成 zip，不包含其自身依赖、autoload 映射、版本约束等元信息，也无法被 composer require 或 install 识别为合法包源。
正确做法是利用 Composer 内置的 pack 功能（需 Composer 2.2+），它会按 composer.lock 中每个条目，下载完整 dist 包（.zip/.tar.gz）并附带 packages.json 索引：
composer pack --format=zip --output=offline-pkg.zip
执行后生成的 offline-pkg.zip 解压出来是标准的「本地仓库结构」：根目录含 packages.json，子目录按 vendor/name 分组存放各包的 dist 归档。
如何配置项目使用本地离线包仓库
在目标离线机器上，不能直接运行 composer install。必须先告诉 Composer：所有包都从本地找，而不是联网拉取。方法是在项目根目录创建或修改 composer.json 的 repositories 配置：
{
"repositories": [
{
"type": "package",
"package": {
"name": "local/offline-mirror",
"version": "1.0.0",
"dist": {
"url": "/path/to/offline-pkg.zip",
"type": "zip"
}
}
}
]
}
但更通用可靠的做法是启用本地 artifact 仓库：
- 把
offline-pkg.zip解压到任意路径，例如/opt/composer-mirror - 在项目
composer.json中添加："repositories": [ { "type": "artifact", "url": "/opt/composer-mirror/" } ] - 确保该路径下有有效的
packages.json（composer pack已自动生成） - 运行
composer install --no-interaction --no-progress即可完全离线完成安装
常见失败点：checksum 不匹配与平台限制
即使用了 composer pack，离线安装仍可能报错 Invalid package archive (checksum mismatch)。原因通常是：
- 打包时用的是不同版本 Composer（如 2.5 打包，2.1 安装），导致 hash 计算方式不一致
- 源包 dist URL 在
composer.lock中记录的是https://...，而本地 artifact 仓库未强制忽略原始 URL 校验 - 某些包声明了
"platform": {"php": "8.1"}，但离线机器 PHP 版本不满足，Composer 会跳过该包且不提示（静默丢弃）
规避方式：打包前统一锁定 Composer 版本（推荐 composer self-update 2.5.8），并在打包命令中加 --strict 参数验证完整性；离线安装前先运行 composer check-platform-reqs 确认环境兼容性。
最易被忽略的是：composer pack 不处理 path 类型仓库或 vcs 类型包（如 GitHub private repo），这类依赖必须提前手动导出为 dist 包并放入 artifact 目录，否则离线安装必然失败。
