单机部署采用nginx动静分离：nginx直接服务静态资源（需准确配置root/alias），反向代理/api/请求至hyperf（proxy_pass末尾斜杠去除前缀），并启用gzip、强缓存、连接数优化及完整验证流程。
单机用 Nginx 转发静态资源 + 部署 Hyperf 应用，核心是“动静分离”：Nginx 直接服务前端文件（JS/CSS/图片/HTML），同时把动态请求（如 API）反向代理给 Hyperf。这样既能发挥 Nginx 处理静态内容的高性能，又能让 Hyperf 专注业务逻辑，不被文件 I/O 拖慢。
静态资源路径配置要准确
Nginx 不会自动猜你把前端构建产物放哪，必须明确指定 root 或 alias：
- 若前端打包后放在
/var/www/dist，且希望访问/就看到首页，用root：
root /var/www/dist;
index index.html;
try_files $uri $uri/ /index.html;
}
注意：root 是拼接路径，$uri 是请求路径，所以 root /var/www/dist; + 请求 /js/app.js → 实际读取 /var/www/dist/js/app.js。
- 若静态资源统一放在
/data/static，但想通过/static/访问，用alias更安全（结尾带斜杠）：
alias /data/static/;
expires 1y;
add_header Cache-Control "public, immutable";
}
alias 是完全替换路径，/static/logo.png → /data/static/logo.png；别漏掉末尾斜杠，否则会出错。
Hyperf 接口反向代理要干净
Hyperf 默认监听 127.0.0.1:9501（HTTP 服务），Nginx 只需把它当后端转发即可，无需重写路径：
proxy_pass http://127.0.0.1:9501/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
关键点：proxy_pass 末尾的 / 表示“去掉 /api/ 前缀再转发”，Hyperf 收到的就是原始路径（如 /v1/user），不用额外做 path rewrite。
如果 Hyperf 启用了 HTTPS 回调或需要真实客户端 IP，上面那几行 proxy_set_header 必须保留，否则 $request->ip() 可能拿到的是 127.0.0.1。
基础性能优化不能跳过
单机部署不是“装上就能跑”，几个小配置直接影响并发能力和缓存效果：
- 启用 Gzip 压缩（减小 JS/CSS/HTML 体积）：
gzip_types text/plain text/css application/javascript application/json image/svg+xml;
- 设置静态资源强缓存（减少重复请求）：
expires 1y;
add_header Cache-Control "public, immutable";
}
- 调大连接数（尤其在高并发测试时）：
worker_connections 4096;
multi_accept on;
}
默认 worker_connections 1024 在中等流量下就可能不够，结合 worker_processes auto; 和服务器 CPU 核数，一般设为 2048–4096 更稳妥。
验证与排错要点
配完别急着 reload，先检查语法、确认路径存在、再测行为：
- 执行
nginx -t确保配置无语法错误 - 手动访问
curl -I http://localhost/js/app.js，看是否返回200和正确Content-Type - 访问
/api/v1/ping，检查响应头是否有X-Powered-By: Hyperf（Hyperf 默认加的） - 查看 Nginx 错误日志：
tail -f /var/log/nginx/error.log，常见问题如权限拒绝（Nginx 用户没读取静态目录权限）、上游连接拒绝（Hyperf 没启动或端口不对）
Hyperf 启动后，建议用 netstat -tlnp | grep :9501 确认它确实在监听，并且绑定的是 127.0.0.1（不是 0.0.0.0，除非你明确需要外网直连）。
