断网时必须设置COMPOSER_DISABLE_NETWORK=1才能真正离线安装,否则composer install会卡在远程元数据校验;vendor存在仍报Connection refused是因默认强制校验包存在性、版本合法性及dist URL可达性,该行为无法跳过。

断网时不能靠“断网自动离线”,必须提前切断所有网络触发点,否则composer install一定会卡在https://repo.packagist.org/packages.json请求上。
为什么 vendor 存在还报 Connection refused
错误不是因为文件缺失,而是 Composer 在 install 阶段仍会主动校验远程元数据:包是否存在、版本是否合法、dist URL 是否可访问。这个行为默认开启,且无法跳过——哪怕 vendor/ 和 composer.lock 都完整。
-
COMPOSER_DISABLE_NETWORK=1是硬性开关,不设它,所有--no-xxx参数(包括--no-plugins、--no-scripts)都无效 - 若项目
composer.json里写了"repositories": [{"type": "packagist", "url": false}],设了环境变量也会直接退出,不是静默忽略 - 全局配置残留
repo.packagist(比如之前配过镜像)会导致 fallback 校验,必须先运行composer config --global repo.packagist false
最稳的离线 install 命令组合
前提是:目标机已存在未改动的 composer.lock、完整 vendor/、PHP 版本与扩展(mbstring、openssl、zlib)完全一致。
- 执行前必须设置:
COMPOSER_DISABLE_NETWORK=1 - 推荐命令:
composer install --no-plugins --no-scripts --no-autoloader - 执行完必须立刻补一记:
composer dump-autoload -o,否则运行时大概率报Class not found - 不要用
--offline:该参数不存在,是常见误传
离线添加新包只能靠 path 仓库
composer require 默认必须联网查包名和版本,离线不可用。唯一可靠方式是把本地目录当仓库用:
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
- 目标包根目录下必须有合法
composer.json,含完整name(如"acme/utils")和明确version(如"1.2.0")或分支标识(如"dev-main") - 项目
composer.json的repositories段要显式声明:{"type":"path","url":"./packages/my-utils"} - 执行
composer require acme/utils:@dev,注意必须带@dev,否则不识别 - 安装后必须立即运行
composer dump-autoload -o,否则 PSR-4 自动加载规则不会生效
预下载缓存打包是最稳妥的长期方案
适用于需频繁部署、环境异构或含大量子依赖的场景:
- 在联网机执行:
composer install --no-install --prefer-dist,让所有包缓存到~/.composer/cache/files/ - 打包整个缓存目录:
tar -czf deps.tgz ~/.composer/cache/files/(Windows 路径为C:\Users\用户名\AppData\Roaming\Composer\Cache\files) - 目标机先清空缓存:
composer clear-cache,再解压到相同路径:tar -xzf deps.tgz -C ~ - 最后运行:
composer install --no-interaction,Composer 就会从本地缓存读取,不再联网 - 注意:
~/.composer/cache/files/下的目录结构是vendor/name/version-hash/,文件名含哈希,不可手动改名;该方式对含 Git 仓库源的包无效,需在联网机加--prefer-dist强制走 zip
最容易被忽略的是:即使 vendor/ 已存在,composer install 仍会尝试 fallback 到远程源做一致性校验——这个行为只有 COMPOSER_DISABLE_NETWORK=1 能真正绕过,其他任何参数或断网操作都无法替代。










