离线备份 Composer 包必须导出完整本地镜像（packages.json + 所有匹配 dist.shasum 的 ZIP 归档），并配置 composer 和 artifact 两类仓库、禁用网络（COMPOSER_DISABLE_NETWORK=1），否则仅复制 vendor/ 或 lock 文件会导致 install 失败。
离线备份 Composer 包，不能只拷 vendor/ 目录或只导出 composer.lock —— 这两类操作在断网后都会导致 composer install 失败，因为 Composer 仍会尝试请求 packages.json 或校验远程 dist.url。
为什么只复制 vendor/ 或只保留 lock 文件一定失败
常见错误现象：Could not fetch https://repo.packagist.org/packages.json、Package not found、Failed to decode response。这些不是网络超时，而是 Composer 根本没读本地文件，因为它缺少元数据入口（packages.json）或无法验证 ZIP 内容（缺失 shasum 对应的 dist 归档）。
-
composer.lock只记录版本、URL 和dist.shasum，不含任何代码，也不含包索引 -
vendor/是安装产物，不包含自动加载初始化逻辑（如vendor/composer/autoload_*.php），且含开发机绝对路径（vendor/composer/installed.json）和软链接（vendor/bin/），直接复制到新环境极易报Class not found或Bad interpreter - 中文镜像（如阿里云、腾讯云）只是代理源，断网后它们本身不可达；镜像缓存 ≠ 离线镜像
必须导出完整离线镜像：packages.json + 所有 ZIP 包
真正在断网环境“当 Packagist 用”，就得构造一个本地静态源：它既要提供包元数据（packages.json），又要提供可解压的 dist 归档（ZIP 文件），且二者严格匹配。
-
packages.json必须放在镜像根目录，内容需覆盖所有直接/间接依赖（比如你没require psr/log，但monolog/monolog依赖它，这个包的元数据也得存在） - ZIP 文件名必须为
vendor-name-package-name-version.zip（如monolog-monolog-3.5.0.zip），不能带下划线、斜杠或额外前缀 - 推荐用
packagist-mirror工具导出，比手写脚本可靠；若手动构造，务必用composer archive验证 ZIP 内容与composer.lock中的dist.shasum一致 - 不要搭 Nginx/Apache——镜像服务本身可以不用 HTTP 服务器；用
file://协议或本地路径即可
导入时必须禁用网络并显式配置两类仓库
即使所有文件都拷进内网，composer install 默认仍会去 https://repo.packagist.org 拉元数据。必须组合使用 composer 类型源（读 packages.json）和 artifact 类型源（读 ZIP），并切断联网路径。
- 项目
composer.json顶部加：
{"repositories": [
{"type":"composer","url":"file:///path/to/mirror"},
{"type":"artifact","url":"./packages/archives"}
]}
COMPOSER_DISABLE_NETWORK=1（Linux/macOS：export COMPOSER_DISABLE_NETWORK=1；Windows：set COMPOSER_DISABLE_NETWORK=1）composer config -g --unset repo.packagist 和 composer config -g --unset http-proxy
-v 运行 composer install，输出中应出现 Reading packages.json from file:///path/to/mirror/packages.json，而非 Downloading https://repo.packagist.org/
打包前必须清理 vendor/ 中的两个危险文件
vendor/ 目录里藏着两个容易导致离线失败的“雷”：一个是 vendor/bin/ 下的软链接或批处理脚本，另一个是 vendor/composer/installed.json 中的开发机绝对路径。这两类文件在新环境基本失效，且可能被插件误读触发异常。
- 打包命令建议用：
zip -r app-offline.zip . -x "vendor/bin/*" "vendor/composer/installed.json" "node_modules/*" ".git/*" - 别用图形化压缩工具——它可能丢掉 symlink 或 chmod 权限
- 如果用
tar，加-h参数展开符号链接，避免解压后失效 - 还原时分三步走：
COMPOSER_DISABLE_NETWORK=1 composer install --no-plugins --no-scripts --no-autoloader→composer dump-autoload -o→php -r "require 'vendor/autoload.php'; echo 'OK';"
最关键的细节往往藏在 ZIP 文件名格式、packages.json 覆盖范围、以及 COMPOSER_DISABLE_NETWORK=1 是否真正生效这三个地方——漏掉任一环节，整个离线流程就会卡在第一秒。
