单机部署前后端分离的Hyperf项目时，Nginx需静态托管前端（含history模式兼容）、反向代理后端API（路径自动剥离、头信息透传、Cookie路径修正）。
单机部署前后端分离的 Hyperf 项目时，Nginx 的反向代理规则核心是：前端静态资源由 Nginx 直接服务，后端 API 请求统一转发给 Hyperf 启动的 HTTP 服务（如监听 9501 端口），且路径需对齐、头信息需透传。
前端静态资源直接托管
Hyperf 本身不托管前端页面，所以需将构建后的前端产物（如 dist/ 目录）放入 Nginx 的 root 路径。关键在于支持前端路由（如 Vue Router 的 history 模式）：
- 配置 location / 块，指向前端根目录（如
/var/www/hyperf-frontend） - 必须包含
try_files $uri $uri/ /index.html;，确保刷新或直接访问子路由不 404 - 建议开启 gzip 和静态资源缓存（
expires 1y;），提升加载速度
后端 API 反向代理到 Hyperf
Hyperf 默认启动在 0.0.0.0:9501（可自定义），Nginx 需将其暴露为统一路径前缀（如 /api/）：
- 使用
location /api/ { proxy_pass http://127.0.0.1:9501/; }—— 注意末尾斜杠，它决定路径替换行为 -
proxy_pass后带斜杠，表示将/api/user转发为http://127.0.0.1:9501/user（自动剥离/api） - 务必设置
proxy_set_header Host $host;和X-Real-IP等头，否则 Hyperf 获取不到真实客户端信息
关键请求头与 Cookie 处理
Hyperf 依赖标准 HTTP 头做鉴权、日志、限流等，Nginx 必须正确传递并适配：
- 添加
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;保留原始 IP - 若 Hyperf 使用 Session 或 JWT Cookie，需用
proxy_cookie_path /api/ /;将后端返回的Path=/api改为Path=/，避免浏览器不携带 - 跨域问题已在代理层解决，前端无需再配
withCredentials: true的额外兼容逻辑
完整最小可行配置示例
放在 /etc/nginx/conf.d/hyperf.conf 中，reload 即生效：
server {
listen 80;
server_name your-domain.com;
<pre class="brush:php;toolbar:false;"># 前端
location / {
root /var/www/hyperf-frontend;
index index.html;
try_files $uri $uri/ /index.html;
}
# 后端 API
location /api/ {
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_cookie_path /api/ /;
}}
