Composer离线使用artifact仓库需满足：ZIP包名、composer.json的name/version、require声明三者字面完全一致；url指向ZIP所在目录（不加斜杠）；必须配置repo.packagist false并设置cache-files-dir，断网后执行composer install --prefer-dist验证。
用 artifact 仓库类型配静态 ZIP 包目录
artifact 是 Composer 唯一原生支持的纯离线仓库类型，不发任何 HTTP 请求，只读取本地 .tar.gz 或 .zip 文件。关键不在“怎么写配置”，而在于包文件是否满足命名与结构规范：
- 所有压缩包必须命名为
vendor-name/package-name-version.tar.gz（如monolog/monolog-2.13.0.tar.gz），路径层级不能嵌套，直接放在一个平级目录下（例如/opt/artifacts/） - 每个包内必须含有效
composer.json，且name和version字段必须与文件名完全一致（大小写敏感） - 离线机上执行：
composer config --global repositories.offline '{"type":"artifact","url":"/opt/artifacts/"}' - 运行
composer install --no-plugins --no-scripts时，Composer 会按composer.lock中的dist.shasum查找对应文件；校验失败直接报错，不 fallback 到网络
为什么 repo.packagist false 必须配，且不能只靠 repositories 配置
即使加了 artifact 仓库，composer install 仍可能尝试连接 repo.packagist.org，根本原因是默认源的 fallback 行为未被真正切断：
- 必须全局禁用：
composer config --global repo.packagist false（注意是false，不是null或空字符串） - 检查项目级配置：
composer config repo.packagist输出应为空；若显示composer https://packagist.org，说明项目composer.json的repositories里还残留 Packagist 条目，需手动删掉 -
ENV COMPOSER_DISABLE_NETWORK=1要在容器环境里设为硬性开关，否则--no-network参数会被忽略 - 验证方式：断网后运行
composer install -v，输出中不能出现Downloading https://repo.packagist.org/packages.json
cache-files-dir 必须显式设到 /files 子目录才有效
离线复用 ZIP 包只依赖 cache-files-dir，cache-dir 对此无效。很多人配了 cache-dir 却发现断网仍重下，就是因为它不控制 ZIP 存放位置：
- 在线机先清旧配置：
composer config --global --unset cache-dir - 只设这一项：
composer config --global cache-files-dir /path/to/offline-cache/files（末尾必须带/files） - 触发下载：
composer install --prefer-dist --no-autoloader --no-scripts，然后确认/path/to/offline-cache/files/vendor/name/version-hash/name-version.zip真实存在 - 离线机上复制整个
/files目录（保留结构），再执行同上的composer config --global cache-files-dir指向该路径 - 常见坑：
cache-files-dir设成/cache，但实际 ZIP 写到了默认~/.composer/cache/files；或目录权限导致 PHP 进程无法stat()，结果静默 fallback
离线机上验证 ZIP 是否真被识别
最常被跳过的一步：别只跑 composer --version 或 composer config --list 就认为成功。真正要测的是 ZIP 匹配逻辑是否生效：
- 启动容器或进入离线机后，先断网：
ip link set eth0 down - 运行：
composer install --no-plugins --no-scripts --no-autoloader --prefer-dist - 若报
Could not find package xxx in a version installable using your PHP version，说明composer.lock里的dist.url指向了远程地址，没被 artifact 或 cache-files-dir 覆盖 - 若报
Failed to download vendor/name: file could not be downloaded，检查composer diag输出中Cache files directory是否和你设的一致，且该路径下有对应 ZIP 文件 - 注意：ZIP 文件名中的版本号必须和
composer.lock中记录的完全一致（包括-dev、-RC等后缀），否则匹配失败
