离线环境无法使用composer global require,因其强制联网解析包名、校验版本并下载资源,且COMPOSER_DISABLE_NETWORK=1对其无效;必须改用path仓库+项目级require,预置工具源码并配置本地路径,配合@dev版本约束和--no-plugins等参数实现真正离线安装。

离线环境不能靠“配置全局依赖”来解决,必须提前把包固化成可验证的产物(vendor/ 或 cache/files),再通过环境隔离 + 行为禁用让 Composer 完全不发网络请求。
为什么 composer global require 在离线时根本走不通
Composer 的 global require 本质仍是在线行为:它会访问 repo.packagist.org 解析包名、校验版本、下载 ZIP 或 clone Git 仓库。即使你之前全局装过某个包,断网后执行 composer global list 能看到,但一旦执行 composer global require foo/bar,立刻报 Could not fetch https://repo.packagist.org/packages.json。
-
COMPOSER_DISABLE_NETWORK=1对global require无效——它只影响项目级install,不拦截全局命令的元数据请求 - 全局缓存目录
~/.composer/cache/下的files/子目录,只有在项目install --prefer-dist时才会写入;global require不走这个路径 - 没有机制能把本地 ZIP 包“注册”进全局依赖体系;
repositories配置对global命令也不生效
离线可用的“全局工具包”替代方案:用 path 仓库 + 项目级 require
真正能落地的离线做法,是放弃 global,改用 path 类型仓库,在每个需要工具的项目里显式引入。比如你想离线用 phpunit/phpunit 或 phpstan/phpstan:
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
- 先在联网机把工具包源码克隆到统一目录,例如
./tools/phpunit,确保其composer.json中"name"字段与你要require的完全一致(大小写敏感) - 项目根目录执行:
composer config repositories.local-tools '{"type":"path","url":"./tools/phpunit","options":{"symlink":false}}' - 再执行:
composer require phpunit/phpunit:@dev --no-interaction --no-plugins --no-scripts - 关键点:
@dev必须加,否则 Composer 不认path源;symlink:false避免离线机软链失效
离线机上怎么让工具命令(如 phpunit)可用
Composer 不会自动把 vendor/bin/ 加进系统 $PATH,离线时更不能依赖全局 bin 目录。正确做法是:
- 所有工具包都走项目级
require,然后统一用vendor/bin/phpunit这类相对路径调用 - 如果必须简化命令,写个 shell wrapper:
alias phpunit='php ./vendor/bin/phpunit',或在 CI/CD 脚本里直接写完整路径 - 不要试图把
vendor/bin加进/usr/local/bin—— 离线机 PHP 版本或扩展若有微小差异,运行时直接Class not found,错误延后且难定位
真正要离线预装的,其实是 composer.phar 本身
很多人忽略这点:离线机连 composer 命令都没有,谈何装包。必须先搞定 Composer 二进制:
- 在同 PHP 版本的联网机上,用官方脚本生成带哈希校验的
composer.phar,命令链不能断(copy → hash_file → composer-setup.php → unlink) - 拷贝过去后,检查权限:
chmod +x composer.phar;建议软链到/usr/local/bin/composer - 验证是否可用:
composer --version;若报ext-zip missing,说明目标机缺扩展,不是网络问题
离线场景下最易被跳过的,是 PHP 扩展一致性检查——mbstring、openssl、zlib 少一个,composer.phar 启动就失败,根本不会走到依赖安装那步。

















