离线环境下Composer报“ext-xxx缺失”本质是PHP CLI环境缺扩展，须在目标机安装对应系统包（如Ubuntu用php-zip、CentOS 7用php-pecl-zip）、验证libzip≥1.6.0及unzip命令存在，并重启终端确认php -m输出，否则vendor完整也无法运行。
离线环境下 Composer 报“ext-xxx is missing”，不是网络问题，是 PHP CLI 环境本身缺模块——必须在目标机上补全扩展，否则 vendor 目录再完整也运行失败。
确认报错扩展是否真没加载（别信错误文字）
离线时无法靠换源或重试绕过，第一步必须验证缺失是否属实：
- 运行
php -m | grep zip（把zip换成报错里的扩展名，如fileinfo、gd）——无输出才说明真没加载 - 用
php --ini查清 CLI 实际读的php.ini路径，别改宝塔/FPM 那个配置文件 - 执行
php -r "var_dump(extension_loaded('zip'));"，返回bool(false)才坐实缺失
按系统装对包名（Ubuntu/CentOS/macOS/Windows 差异极大）
装错包名 = 白干。不同系统命名规则完全不同，且 PHP 版本影响后缀：
- Ubuntu/Debian：
sudo apt install php-zip（自动启用，不需改php.ini） - CentOS/RHEL 7：
sudo yum install php-pecl-zip（不是php-zip） - CentOS/RHEL 8+：
sudo dnf install php-zip - Alpine（Docker）：
apk add php8-zip（版本号必须和php -v输出一致） - macOS + Homebrew：
brew install php@8.2-zip，再确认php.ini里有extension=zip.so - Windows：打开
php --ini显示的php.ini，取消;extension=php_zip.dll前的分号，并确认php_zip.dll真的存在于extension_dir指向的目录
装完仍报错？检查三个静默失效点
扩展显示已安装，但 composer install 还卡住，大概率是以下任一环节断链：
- Linux 下装完没新开终端——旧 shell 缓存了旧的
php -m结果，新终端才能看到新增扩展 - libzip 库太旧（如 CentOS 7 自带 0.10），PHP 8.0+ 要求 ≥ 1.6.0；查版本：
pkg-config --modversion libzip - Docker 中只装了
php8-zip，但没装系统级unzip命令（apk add unzip），Composer 默认优先调它，报unzip not found
离线加新包只能靠 path 仓库，不能靠 require
composer require xxx 在离线时必然失败，因为要联网查包信息。唯一可行方案是手动维护本地 path 类型仓库：
- 在有网环境把目标包完整 clone 到本地目录，如
./packages/my-package - 在项目
composer.json的repositories里加：{"type": "path", "url": "./packages/my-package"} - 再运行
COMPOSER_DISABLE_NETWORK=1 composer require my/package:dev-main --no-plugins --no-scripts - 注意：该包的
composer.json必须声明正确autoload，且不含需编译的post-install-cmd
最常被忽略的是：即使 vendor 完整复制过去，只要目标机 PHP 缺少 mbstring 或 openssl，运行时照样 Class not found 或连接失败——扩展兼容性不是“能装上就行”，而是“CLI 环境、扩展版本、底层库三者必须对齐”。
