COMPOSER_DISABLE_NETWORK=1是离线模式硬性前提，不设则所有--no-xxx参数无效；必须提前设置环境变量，否则composer install仍强制请求远程元数据而失败。
COMPOSER_DISABLE_NETWORK=1没设，其他全是白忙
离线模式不是“断网就自动生效”，而是必须显式启用的开关。不设这个环境变量，composer install 仍会尝试请求 https://repo.packagist.org/packages.json，报错可能是 Curl error 60、Could not resolve host 或 SSL certificate problem——本质都是它还在发网络请求。
常见错误操作：
- 只改了
composer.json里的"secure-http": false，没设环境变量 - 用了
--no-network参数（该参数不存在，Composer 不识别） - 在 Windows PowerShell 中漏写
$env:COMPOSER_DISABLE_NETWORK="1"，而用了 CMD 语法set - 设了但没导出：比如
COMPOSER_DISABLE_NETWORK=1 composer install在子 shell 执行后失效，应改用export COMPOSER_DISABLE_NETWORK=1（Linux/macOS）或全局设置（Windows）
cache-files-dir 配错等于没配
离线复用 ZIP 包只认 cache-files-dir 指向的 /files 子目录，cache-dir 是父目录，不控制 ZIP 存放位置。只配 cache-dir，Composer 会回退到默认路径 ~/.composer/cache/files，而离线机上这个路径通常为空。
必须确保：
-
cache-files-dir值是绝对路径，且末尾含/files（例如/opt/composer-cache/files，不能是/opt/composer-cache） - 执行过
composer config --global --unset cache-dir，否则旧配置可能干扰新设置 - 在线机下载时用了
--prefer-dist，且验证过目标路径下存在类似/monolog/monolog/2.10.0.0/monolog-monolog-6a8c4b5.zip的文件 - 离线机上该路径可被 PHP 进程用户（如
www-data）读取，stat()不失败
vendor 目录直接复制，但 PHP 环境不一致就崩
直接拷 vendor/ 是最快方案，但前提是源与目标环境高度一致。稍有偏差就会在运行时报 Class not found 或扩展缺失错误，而不是安装阶段失败。
关键检查点：
- PHP 版本完全相同（如 8.2.12），小版本差异也可能导致 opcache 兼容问题
- 必需扩展已启用：如
mbstring、openssl、json、curl；若项目依赖ext-redis，目标机必须已装并启用 - Composer 版本兼容：源机用 Composer 2.5+ 生成的
autoload_classmap.php，在 Composer 2.2 下可能无法加载 -
composer.lock必须一并拷贝，且未被手动修改过 dist URL 字段（如把https://改成file://）
离线机上还报 “Package not found”？先看 lock 文件里有没有 git source
composer.lock 中若存在 "source": {"type": "git", ...} 条目，Composer 离线时无法校验 commit hash，install 会直接退出，哪怕你配了所有缓存和禁网参数。
这类锁文件天生不支持离线，修复方式只有两种：
- 在线机重跑
composer install --prefer-dist（强制走 ZIP 分发），再重新生成composer.lock - 手动编辑
composer.lock，把所有"source"块删掉，只保留"dist"块，并确认dist.url是 ZIP 地址、dist.shasum非空 - 避免使用
composer create-project生成初始项目，它默认拉 git source；改用git clone+composer install --prefer-dist组合
最常被忽略的一点：离线部署不是“让 Composer 少联网”，而是“让它根本没机会联网”。任何残留的远程元数据引用、未清理的全局镜像配置、或权限/路径错位，都会让整个流程在最后一刻静默 fallback 回重下。
