cache-files-dir是离线复用缓存的唯一有效配置项，需配合--prefer-dist使用，且必须禁用packagist源并确保目录权限正确；其他缓存路径配置均无法实现离线复用。
cache-files-dir 是离线复用缓存的唯一有效配置项
Composer 的 cache-dir 是混合目录（含 repo/、archived/、files/），断网后只有 files/ 子目录下的 ZIP 包能被 --prefer-dist 直接读取；其他部分（如 repo/ 下的 packages.json）离线即失效。所以别配 cache-dir，改用专为离线设计的 cache-files-dir —— 它只控制 ZIP 包存放路径，不干扰元数据逻辑。
- 先清旧配置：
composer config --global --unset cache-dir（避免冲突） - 设新路径：
composer config --global cache-files-dir /opt/composer-offline-cache（必须是绝对路径） - 确认目录已创建且当前用户可读写：
mkdir -p /opt/composer-offline-cache && chmod 755 /opt/composer-offline-cache - 验证是否生效：
composer diag输出中 “Cache directory” 行应显示/opt/composer-offline-cache，且ls /opt/composer-offline-cache应能看到包名哈希子目录
离线机必须禁用默认源并指向本地缓存路径
即使缓存 ZIP 全在，只要 repo.packagist 配置还存在，composer install 就会尝试联网请求 packages.json，直接卡死或报 Could not fetch packages.json。必须显式禁用默认源，并确保 Composer 不去查任何远程地址。
- 执行：
composer config --global --unset repos.packagist（不是repo.packagist，注意 key 名） - 检查是否清空：
composer config -g repos.packagist应返回空或报错，而非 JSON 对象 - 若项目级有
composer.json中的repositories，也需手动删掉或注释掉 packagist 条目 - 环境变量
COMPOSER_DISABLE_NETWORK=1可作为兜底，但不能替代源禁用 —— 它只抑制网络请求，不改变仓库解析逻辑
必须用 --prefer-dist + --no-scripts 安装，否则缓存不生效
cache-files-dir 只在 --prefer-dist 模式下起作用；如果用了 --prefer-source 或没加该参数，Composer 会跳过 ZIP 缓存，转而尝试 clone Git 仓库 —— 这在离线时必然失败。同时，--no-scripts 能防止 post-install-cmd 脚本因缺失依赖或路径错误中断流程。
- 正确命令：
COMPOSER_DISABLE_NETWORK=1 composer install --prefer-dist --no-scripts --no-plugins --no-dev --no-autoloader -
--no-autoloader是安全项：避免 autoload.php 生成失败导致后续命令报错 - 安装完立刻补：
composer dump-autoload -o（否则类可能找不到） - 常见误操作：漏掉
--prefer-dist，或用了--update-with-dependencies—— 后者会触发元数据重解析，强制联网
最容易被忽略的权限与证书问题
即使路径、配置、ZIP 包全对，离线机仍可能静默失败：一是 PHP 进程用户（如 www-data）对缓存目录无读权限；二是 OpenSSL 配置缺失导致本地 HTTP 请求也卡在 TLS 握手阶段 —— 尤其当用 Python http.server 或 Nginx 提供本地镜像服务时。
- 检查缓存目录所有权：
ls -ld /opt/composer-offline-cache，确保运行composer的用户有读权限 - 验证 PHP 的
openssl.cafile是否设置：php -i | grep cafile，若为空，需在php.ini中补上或临时设export COMPOSER_DISABLE_TLS=1（仅限内网可信环境） - 不要依赖
composer config --global cache-dir的输出来判断实际路径 —— 以composer diag为准，它反映真实运行时行为
