离线部署hyperf需四步：环境预检（php≥8.1、swoole≥5.0、禁用opcache cli）、依赖离线化（同构环境打包vendor及swoole.so等）、手动部署（配置扩展、权限、.env）、启动验证（检查监听、http响应、扩展加载）。
离线部署Hyperf，核心是把所有依赖提前打包、验证、复制到位，不依赖网络下载。整个过程分四步：环境预检与准备、依赖离线化、项目构建与配置、服务启动与验证。
一、离线前必须完成的环境确认
在有网机器上先做完这三件事，再把成果拷贝到目标服务器：
- 确认PHP版本 ≥ 8.1（php -v），且已编译启用 pcntl、mbstring、bcmath、sockets 扩展；
- 安装 Swoole ≥ 5.0：用 pecl install swoole 编译，生成 swoole.so 文件，并记下其完整路径（如 /usr/lib/php/20210902/swoole.so）；
- 禁用 CLI 模式下的 OPcache：opcache.enable_cli = Off（修改 php.ini 后执行 php --ini 确认生效位置）。
二、离线依赖包全量打包
在联网机器上操作，确保使用与目标服务器一致的 PHP 架构（x86_64/arm64）、相同操作系统大版本（如 CentOS 7 / Ubuntu 22.04）：
- 创建骨架：composer create-project hyperf/hyperf-skeleton myapp --no-install（加 --no-install 防止自动拉包）；
- 进入目录，手动安装必需组件：composer require hyperf/http-server hyperf/watcher --no-scripts --no-plugins（跳过脚本执行，只下载代码）；
- 执行 composer install --no-dev --optimize-autoloader --ignore-platform-reqs，生成 vendor/ 目录；
- 把整个项目目录（含 app/、config/、vendor/、bin/、composer.json、composer.lock）打包为 myapp-offline.tar.gz；
- 额外打包：Swoole 扩展文件（swoole.so）、PHP 运行时所需动态库（如 libnghttp2.so.14，用 ldd $(php -r "echo ini_get('extension_dir');")/swoole.so | grep 'not found' 检查缺失项）。
三、目标服务器上的手动部署
将压缩包解压到目标路径（如 /opt/myapp），然后逐项配置：
- 复制 swoole.so 到 PHP 扩展目录（php -r "echo ini_get('extension_dir');" 输出路径），并在 php.ini 中添加：extension=swoole.so；
- 若提示缺少系统库，把对应 .so 文件复制到 /usr/lib64 或 /usr/lib，并执行 ldconfig；
- 检查 config/autoload/annotations.php 中 scan 配置是否包含 app/Controller，否则注解路由不会被加载；
- 设置权限：chown -R www-data:www-data /opt/myapp（按实际运行用户调整），并确保 runtime/ 目录可写；
- 关闭调试模式：echo "APP_DEBUG=false" > .env。
四、启动验证与常见问题处理
执行启动命令后，重点看三类输出：
- php bin/hyperf.php start —— 成功应显示 HTTP Server listening at http://127.0.0.1:9501；
- 访问 curl -I http://127.0.0.1:9501/api/index（需提前写好带 AutoController(prefix: '/api') 的控制器），返回 200 OK 及 JSON 即通；
- 若报 "Swoole extension not loaded"，检查 php --ri swoole 是否有输出；若报 "Class not found"，确认 vendor/autoload.php 被正确引入，且未遗漏 composer dump-autoload -o（离线环境下建议提前执行好）。
不复杂但容易忽略
