离线环境必须设置COMPOSER_DISABLE_NETWORK=1,否则composer install必请求远程元数据而失败;该变量是硬性前提,不设则--no-plugins等参数无效,且需配合--no-scripts、--no-autoloader及后续dump-autoload -o。

离线环境必须用 COMPOSER_DISABLE_NETWORK=1 才能真正断网
不设这个环境变量,composer install 会照常请求 https://repo.packagist.org/packages.json,哪怕 vendor/ 和 composer.lock 都齐全,也必然失败。报错可能是 Curl error 60 或 Could not resolve host,本质都是 Composer 还在联网。
常见误操作:
- 只配
composer config --global secure-http false—— 它只影响仓库协议策略,不阻止元数据请求 - 只加
--no-plugins --no-scripts—— 这些参数在网络通路未切断前根本不会执行到 - Windows PowerShell 中写成
$env:COMPOSER_DISABLE_NETWORK=1(缺引号),实际没生效
验证是否生效:运行 composer diag,输出中应明确显示 Network access disabled;再跑 composer install -v,日志里不能出现任何 GET https:// 行。
composer install 是离线部署唯一合法命令
composer update 在离线环境下完全不可用——它必须访问远程仓库校验版本可用性,强行运行会直接报错退出。只有 install 基于本地 composer.lock 解析依赖树,且支持从缓存 files/ 目录读取 ZIP 包。
关键前提:
-
vendor/必须为空或已彻底删除,残留旧包可能引发 autoload 冲突或类覆盖 -
composer.lock必须和在线机生成时完全一致,不能手动改过 - 若锁文件里存在
"source": {"type": "git"},离线安装必然失败——这种源类型无法离线校验
最小安全命令组合:COMPOSER_DISABLE_NETWORK=1 composer install --no-plugins --no-scripts --no-autoloader
执行完立刻补一记:composer dump-autoload -o,否则运行时大概率 Class not found。
离线扩展包只能靠 path 类型仓库引入
composer require vendor/name 在离线模式下无效,因为它默认要查远程包名和版本。唯一可行路径是提前声明 path 仓库,并确保本地包结构合规。
配置要点:
- 项目根目录
composer.json的repositories字段必须是数组:[{"type": "path", "url": "./packages/my-ext"}] -
url必须为相对路径,不能带file://或绝对路径;目录必须真实存在且含合法composer.json - 本地包的
name(如"acme/ext")必须和require语句中写的完全一致(大小写敏感) - 若本地包无
version字段,需在项目级设"minimum-stability": "dev",否则dev-main分支会被过滤
装完后若 Class not found,不是路径问题,而是 autoload 没注册:确认本地包 composer.json 有 "autoload": {"psr-4": {"Acme\Ext\": "src/"}},然后在项目中运行 composer dump-autoload。
缓存 ZIP 包必须落进 cache-files-dir 而非 cache-dir
离线复用依赖包,只认 files/ 子目录下的 ZIP 文件。设 cache-dir 不等于设了 ZIP 存放点——它只是混合缓存父目录,repo/(元数据)和 archived/(解压归档)都放里面,但这些在离线时全失效。
正确做法:
- 在线机先清旧配置:
composer config --global --unset cache-dir - 显式设
cache-files-dir,且路径末尾必须带/files:composer config --global cache-files-dir /opt/composer-cache/files - 触发完整下载:
composer install --prefer-dist --no-autoloader --no-scripts - 验证:
ls /opt/composer-cache/files/vendor/package/version-hash/package-version.zip是否存在
离线机上,除了拷贝整个 /files 目录,还必须运行:composer config --global cache-files-dir /your/copied/path/files。漏掉这步,Composer 会静默 fallback 到默认空路径,然后重下。











