COMPOSER_DISABLE_NETWORK=1 是离线前提，否则任何镜像配置均无效；需禁用 packagist、用 path/artifact 仓库、补 dump-autoload -o 生成自动加载。
COMPOSER_DISABLE_NETWORK=1 是硬性前提，不设它，任何“本地镜像源”配置都无效——Composer 仍会尝试请求 packages.json，直接卡在 Loading composer repositories 或报 Could not fetch https://...。
你不能靠改 repositories 字段就实现离线，也不能把阿里云镜像地址写进本地配置就当它是“本地源”。真正的离线，是切断所有网络通路 + 精确复用已有资源。
为什么改了 repo.packagist 还是联网失败
常见错误是执行了 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，以为这就“换成本地源”了。其实这只是换了下载地址，校验逻辑没变：
– Composer 仍要请求 https://mirrors.aliyun.com/composer/packages.json 获取元数据
– 断网后立刻报错，且不会 fallback 到缓存或 vendor 目录
– 即使你删掉这行配置，只要没运行 composer config --global --unset repo.packagist，它仍可能残留并触发 fallback 校验
必须做两件事：
– 全局禁用 packagist： composer config --global repo.packagist false
– 同时启用离线开关：COMPOSER_DISABLE_NETWORK=1
path 类型仓库怎么配才真正离线可用
这是唯一无需 HTTP 服务、纯文件系统就能跑通的离线方案，但有强约束：
-
url必须是本地相对路径（如./packages/my-utils），Windows 需带盘符（如C:/dev/my-utils） - 目标目录下必须有 Git 仓库（至少一个
git commit），否则 Composer 拒绝识别 - 该目录下的
composer.json必须含完整name字段（如"acme/utils"），且大小写、vendor 名与项目require中完全一致 -
require里不能写语义化版本（如"^1.2"或"1.0.0"），只能写"dev-main"、"dev-develop"这类分支名 - 添加依赖必须用
composer require acme/utils:dev-main，不能只写包名让 Composer 自动查版本
示例：
项目 composer.json 加：
"repositories": [{"type": "path", "url": "./packages/my-utils"}]再运行：
composer require acme/utils:dev-main
artifact 类型仓库报 “Package not found” 怎么排查
artifact 适合打包分发已知版本的 zip/tar 包，但匹配规则极其严格：
- 压缩包文件名必须为
vendor-name/package-name-version.tar.gz（注意不是.zip，也不是package-version顺序） - 包内
composer.json的name和version字段必须与文件名**逐字符一致**，连-beta1和-RC都不能多也不能少 - 所有压缩包必须平铺放在同一级目录下，不能有子目录（如
/artifacts/monolog/monolog-2.13.0.tar.gz❌，应为/artifacts/monolog/monolog-2.13.0.tar.gz✅） - 配置命令必须用
composer config repositories.offline '{"type":"artifact","url":"/opt/artifacts/"}'——url是本地路径，不是 URL，末尾不加斜杠 - 必须全局禁用 packagist：
composer config --global repo.packagist false，否则 fallback 行为会绕过 artifact
验证是否生效：运行 composer show --all --locked，看对应包的 dist.type 是否为 artifact，且 dist.url 是 file:// 开头。
离线安装后为什么还是 Class not found
因为 composer install 在 COMPOSER_DISABLE_NETWORK=1 下跳过了 autoload 生成。这不是 bug，是设计行为。
必须补一记：composer dump-autoload -o（注意加 -o，否则不生成优化后的 autoload_classmap.php）
容易被忽略的点：
– dump-autoload 不联网，可放心执行
– 如果项目用了 PSR-4 映射但没跑这步，运行时必报 Class not found
– 若之前已存在 vendor/autoload.php，它只是引导文件，真正映射表在 vendor/composer/autoload_*.php 里，这些文件必须由 dump-autoload 生成
最稳的离线命令组合：COMPOSER_DISABLE_NETWORK=1 composer install --no-plugins --no-scripts --no-autoloader && composer dump-autoload -o
