离线部署需在与目标环境完全一致的有网机器上执行 composer install --no-dev --prefer-dist --optimize-autoloader 生成 vendor，再 tar 打包并校验哈希后传入内网，解压至项目目录，跳过 composer install 直接验证 autoload 和扩展。
离线服务器无法直接运行 composer install，必须提前在有网环境下载完整依赖包并打包，再传入内网。核心是确保 vendor/ 内容与目标环境完全一致——包括平台相关扩展、PHP 版本兼容性、以及所有递归依赖的精确版本。
用 composer install --no-dev --prefer-dist --optimize-autoloader 生成可移植 vendor
这是最关键的一步。不能只跑 composer update 或简单复制本地 vendor/，因为：
-
--no-dev排除开发依赖（如phpunit），避免引入内网不需要且可能冲突的工具 -
--prefer-dist强制下载压缩包而非 Git 克隆，保证可离线复现；否则某些包若配置了"source"类型，会在无网时失败 -
--optimize-autoloader生成扁平化类映射，减少 autoloader 查找开销，也避免因内网 PHP 扩展缺失（如ext-zip）导致composer dump-autoload失败 - 务必在与目标服务器**相同 PHP 版本、相同架构（x86_64 / aarch64）、相同扩展启用状态**的机器上执行该命令
打包前检查 composer.lock 和平台约束
离线部署成败取决于 composer.lock 是否锁定全部细节。常见翻车点：
- 锁文件中
"platform": {"php": "..."}必须与目标服务器php -v输出严格匹配，否则composer install会跳过某些包或报错Your requirements could not be resolved - 检查是否有
"platform-check": false被手动添加——这会绕过平台校验，但可能导致扩展缺失时运行时报错，不推荐 - 确认所有包的
dist.url指向的是稳定镜像（如https://mirrors.aliyun.com/composer/dists/...），而不是 GitHub raw 链接；后者在离线时无法验证完整性
用 tar 打包并校验哈希，别用 ZIP
Linux 服务器间传输首选 tar，原因明确：
- ZIP 在解压时可能丢失 Linux 文件权限（如
vendor/bin/phpunit的可执行位），导致后续命令无法运行 -
tar -czf vendor.tar.gz vendor/保留所有元数据；加--owner=0 --group=0可避免 UID/GID 差异问题 - 传输前务必生成校验值：
sha256sum vendor.tar.gz
并将结果一并传入内网。目标服务器收到后先比对哈希再解压，防止传输损坏 - 解压命令统一用：
tar -xzf vendor.tar.gz --strip-components=1 -C /path/to/project
（--strip-components=1确保解压后直接是vendor/目录，而非多一层父目录）
内网服务器上跳过 Composer 安装步骤，直接验证运行
离线环境里不需要、也不应该再运行 composer install。正确做法是：
- 确认
vendor/autoload.php存在且可读（php -l vendor/autoload.php） - 检查关键扩展是否就位：
php -m | grep -E 'curl|openssl|mbstring'—— 缺少任一都可能让某些包启动失败 - 运行最小验证脚本：
<?php require_once 'vendor/autoload.php'; echo "OK\n";
若报错Class not found，大概率是打包时没用--optimize-autoloader或 PHP 版本不匹配 - 如果项目用到
ext-sodium或ext-redis等非默认扩展，需提前在内网服务器编译安装，Composer 不会帮你解决系统级依赖
最常被忽略的是：打包机和目标机的 php.ini 中 extension_dir 路径不同，会导致 require_once 成功但扩展函数调用失败。建议在打包前，在目标机上运行 php --ini 和 php -r "print ini_get('extension_dir');"，然后在打包机上模拟相同环境再生成 vendor/。
