COMPOSER_DISABLE_NETWORK=1是离线模式的硬性前提，不设则所有--no-xxx参数无效；必须提前设置该环境变量，否则composer install仍强制联网请求元数据而失败。
COMPOSER_DISABLE_NETWORK=1 是离线工作的硬性开关
不设这个环境变量，所有 --no-xxx 参数都无效。它不是“建议开启”，而是 Composer 离线行为的总闸门——没它，composer install 仍会尝试 DNS 解析、HTTP HEAD 请求甚至 TLS 握手，哪怕 vendor 目录已存在、composer.lock 完整。
常见错误现象：Could not fetch https://repo.packagist.org/packages.json 或卡在 Loading composer repositories。这不是缓存没配好，是根本没切断网络通路。
- 必须在运行命令前设置：
COMPOSER_DISABLE_NETWORK=1 composer install --no-plugins --no-scripts --no-autoloader - 不能只写进
.bashrc就以为全局生效；Docker 容器里要显式用ENV COMPOSER_DISABLE_NETWORK=1 - 验证是否生效：执行
composer config --list | grep network，输出应为空；再跑composer install -v，日志里不能出现任何GET或HEAD请求行
cache-files-dir 必须显式指向 /files 子目录
cache-dir 配了也白配，真正决定 ZIP 包能否离线复用的是 cache-files-dir。Composer 的缓存结构是分层的：repo/ 存元数据（断网即失效）、archived/ 存解压后归档（不参与安装）、只有 files/ 下的 ZIP 才会被 --prefer-dist 直接读取并校验。
常见失败点：
- 把
cache-files-dir设成/opt/composer-cache，但实际 ZIP 写到了/opt/composer-cache/files/...—— 这没问题；但如果设成/opt/composer-cache/files却漏掉末尾/files，Composer 就不会往里写 - 离线机上该路径权限不对，PHP 进程用户（如
www-data）无法stat()目录，结果静默 fallback 到重下 - 在线机配过
cache-dir没清掉，cache-files-dir会被忽略，Composer 回退到默认~/.composer/cache/files，而离线机上这个路径通常为空
本地仓库必须用 artifact 或 path 类型
改 repo.packagist 地址或加 repositories 指向 https:// 域名，都不能实现真离线。唯一能跳过所有 HTTP 请求的类型只有 artifact 和 path。
artifact 用于部署场景：
- 包文件必须是
.tar.gz或.zip，命名严格为vendor-name/package-name-version.tar.gz - 所有包平铺在一个目录下（如
/opt/artifacts/），不能嵌套子目录 - 配置命令：
composer config repositories.offline '{"type":"artifact","url":"/opt/artifacts/"}'
path 用于本地开发联调：
- 包目录必须含有效
composer.json，且name字段与require时写的完全一致（包括大小写） - 配置中必须带
"options": {"symlink": false}，否则离线机软链失效 - require 时必须加
@dev，例如：composer require my-utils/my-utils:@dev
vendor 目录迁移比重新 install 更可靠
只要源和目标环境的 PHP 版本、扩展（如 mbstring、openssl）、composer.json 中的 platform 配置一致，直接复制 vendor/ + composer.lock 是最稳的离线方案。
容易被忽略的关键点：
- 目标机必须已安装所有
ext-*依赖（如ext-redis），否则运行时报错，不是安装时报错 - 含
bin/脚本的包（如phpunit）要求目标机php在$PATH中，且路径与源机一致 - 执行完
composer install --no-plugins --no-scripts --no-autoloader后，必须补一记composer dump-autoload -o，否则大概率报Class not found - 不要用
composer create-project初始化离线项目——它强制联网解析元数据，COMPOSER_DISABLE_NETWORK=1对它无效
