Nginx 同时代理静态资源和 API 服务

前后端分离项目交付时,常见需求是在同一个对外端口上完成分发:/ 返回 SPA 打包产物、/api/ 转发给后端服务、/upload/ 直接读服务器上的用户上传文件。三者对 Nginx 的能力要求完全不同:静态要缓存高效,API 要代理转发并保留真实客户端信息,上传目录要兼顾路径映射与体积上限。

一、路由拓扑

1
2
3
                      ┌─ location /        -> /xxx/dist(SPA,try_files 回退 index.html)
客户端: host:7001 ────┼─ location /api/ -> http://127.0.0.1:1234(反向代理)
└─ location /upload/ -> /var/serverSource/upload(本地静态)

注意三处前缀都带尾斜杠:/api/ 与 /upload/ 写成不带尾斜杠会意外匹配 /apixxx、/uploadxxx 这类路径。

二、完整配置模板

以下几段合起来是一份可直接套用的配置。upstream 和 map 属于 http 块(nginx.conf 里),其余在 server 块:

1
2
3
4
5
6
7
8
9
10
# ---- http 块 ----
upstream backend {
server 127.0.0.1:1234;
keepalive 32; # 与后端保持长连接,省掉重复 TCP 握手
}

map $http_upgrade $connection_upgrade {
default upgrade; # 有 Upgrade 头 -> upgrade
'' close; # 普通请求 -> close
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# ---- server 块 ----
server {
listen 7001;
server_name localhost;

# 上传体积上限,防止 413;也不用无脑调太大
client_max_body_size 100M;

# 1. 后端 API:原样转发 /api/...,不重写路径
location /api/ {
proxy_pass http://backend;

# 关键:WebSocket 按需升级,普通请求保持 close
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

# 传递真实客户端信息
proxy_set_header Host $http_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_connect_timeout 60s;
proxy_read_timeout 120s;

# 大文件上传时按需开启:关闭缓冲 = 直传后端;
# 默认 on 时 Nginx 先落盘再发,抗后端抖动但吃磁盘
# proxy_request_buffering off;
}

# 2. 用户上传的静态资源
location /upload/ {
root /var/serverSource; # 实际目录 = /var/serverSource/upload
expires 7d; # 同时输出 Expires 与 Cache-Control: max-age
add_header X-Content-Type-Options "nosniff";
access_log off;
}

# 3. SPA 前端
location / {
root /xxx/dist;
index index.html;
try_files $uri $uri/ /index.html; # History 路由刷新回退
gzip_static on; # 命中预压缩 .gz 时直接发
}

# 可选:带哈希的静态资源单独缓存,缺失就 404,而不是回退成 HTML
location ~* \.(?:js|css|png|jpe?g|gif|svg|webp|ico|woff2?)$ {
root /xxx/dist;
try_files $uri =404;
expires 1y;
access_log off;
}
}

三、关键细节拆解

3.1 proxy_pass 的路径拼接(最容易翻车)

proxy_pass 写法客户端请求后端实际收到
proxy_pass http://backend;/api/users/api/users(原样透传)
proxy_pass http://backend/;/api/users/users(剥掉 location 前缀)
proxy_pass http://backend/api/;/api/users/api/users(等价于不写 URI,冗余)

规则:proxy_pass 没带 URI 路径就原样透传;带了路径就把 location 匹配到的前缀替换掉。 后端路由本身就带 /api 时,直接用不带 URI 的写法最不容易错;只有"前缀需要剥离"的场景才写尾斜杠。另外 location /api/ 与 proxy_pass ... / 组合时,/api/(不带后续路径)会被转发成 /,后端需兼容。

3.2 WebSocket 别写死 Connection: upgrade

原文的静态写法:

1
proxy_set_header Connection "upgrade";

会把所有请求的 Connection 头都改成 upgrade,普通 HTTP 请求也受影响。正确姿势就是前面的 map $http_upgrade $connection_upgrade:有 Upgrade 头才升级,普通请求为 close。map 只能放在 http 块,不能放 server 里。

3.3 root 与 alias 的分界线

  • root(追加):location /upload/ { root /var/serverSource; } → root + /upload/ + 文件名,即 /var/serverSource/upload/avatar.png;
  • alias(替换):location /upload/ { alias /data/uploads/; } → 直接映射到 /data/uploads/avatar.png。

一句话:路径前缀要保留用 root,要去掉用 alias。用 alias 时 location 与 alias 的尾斜杠必须一致,否则 404;改配置后必须 nginx -t && nginx -s reload。

3.4 上传链路:体积与缓冲

  • client_max_body_size 默认 1MB,图片/视频业务必须显式调大;
  • proxy_request_buffering off 让请求体边收边传,后端压力大、Nginx 磁盘压力小,但后端抖动时没有 Nginx 兜底;
  • 保持默认 on 时,Nginx 会把 body 缓冲到临时目录再转发,注意磁盘余量;
  • 后端读取文件后用 Content-Length/Transfer-Encoding: chunked 返回大文件时,给 API 配足 proxy_read_timeout。

3.5 SPA 回退与静态缓存

  • try_files $uri $uri/ /index.html; 是 History 路由刷新不 404 的标准解;
  • 但缺失的 JS/CSS 也会被回退成 index.html(200 + HTML),前端会拿到 MIME 不对的响应;因此给带扩展名的资源单独一个 location,用 try_files $uri =404; 兜底(模板里可选段);
  • 带内容哈希的构建产物可以 expires 1y;HTML 入口不要长缓存,否则发版后用户可能拿到旧 HTML 引用已删除的哈希资源。

3.6 缓存头只写一次

expires 已经会输出 Expires 和 Cache-Control: max-age,如果再 add_header Cache-Control "public, no-transform",响应里会出现两个 Cache-Control。二选一:

  • 用 expires 7d;(简单,max-age 自动);
  • 或 add_header Cache-Control "public, max-age=604800, no-transform";(不加 expires);
  • 需要同时自定义两者时,装第三方 headers-more 模块的 more_set_headers。

3.7 其他生产建议

  • 安全头:静态与 API 都可加 X-Content-Type-Options: nosniff;SPA 的 HTML 建议按团队规范加 CSP、X-Frame-Options 等;
  • MIME:上传目录最好保持文件扩展名;对可疑扩展(.svg、.html)注意 MIME 与 XSS 风险,必要时强制 Content-Disposition: inline 时先确认来源;
  • 性能:http 块开 sendfile on; tcp_nopush on;,上传/图片目录可开 open_file_cache 缓存文件描述符;
  • API 健壮性:配合 upstream 的 keepalive,调 proxy_next_upstream 应对 502 重试(注意幂等性);
  • 日志:静态资源关 access_log off 或单独文件,避免高频小图把主日志冲爆(模板中已示例)。

四、验证方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 1. SPA 首页
curl -i http://localhost:7001/

# 2. History 路由刷新(预期 200 + text/html,而不是 404)
curl -i http://localhost:7001/user/dashboard

# 3. API 透传
curl -i http://localhost:7001/api/users

# 4. 上传文件
curl -i http://localhost:7001/upload/avatar.png

# 5. WebSocket 升级握手(看 101 Switching Protocols)
curl -i -N \
-H "Connection: Upgrade" -H "Upgrade: websocket" \
-H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
-H "Sec-WebSocket-Version: 13" \
http://localhost:7001/api/ws

# 6. 校验配置
nginx -t && nginx -T | less

API 侧重点确认后端拿到的 Host、X-Real-IP、X-Forwarded-For 是否为真实值;前端重点确认预压缩资源 Content-Encoding: gzip 正常。

五、常见问题

现象原因 / 处理
刷新 SPA 子路由 404缺 try_files ... /index.html;确认 location / 的 root 指向构建产物目录
缺失 JS 变成 200 的 HTMLtry_files 回退对带扩展名资源也生效;加正则 location try_files $uri =404
后端收到两份路径前缀检查 proxy_pass 是否写了 URI;对照 3.1 的表格
WebSocket 握手 400 / 被立即关闭Connection 写死 upgrade 或没配 proxy_http_version 1.1;改用 $connection_upgrade
上传 413 Payload Too Large调大 client_max_body_size,并确认后端也有体积限制
缓存不生效expires 与 add_header Cache-Control 重复,或上游代理/CDN 覆盖了头
大文件转发慢/占内存proxy_request_buffering off + 检查后端超时;同时留意 client_body_temp 磁盘
/upload 404root/alias 尾斜杠不一致;API 路径里 /api 匹配到了 /apixxx

六、参考资料

  1. Nginx 官方文档:ngx_http_proxy_module —— proxy_pass 拼接规则、请求头、超时、缓冲;
  2. Nginx 官方文档:WebSocket 代理;
  3. Nginx 官方文档:root / alias;
  4. Nginx 官方文档:try_files / client_max_body_size;
  5. Vue Router:History 模式、React Router:部署说明 —— 为什么 SPA 需要服务端回退。

七、小结

一套配置同时服务三种资源,本质是把三种不同的语义放对位置:静态讲缓存与回退,API 讲透传与超时,上传目录讲体积与安全。proxy_pass 拼路径、WebSocket 升级、缓存头写几次,是最常踩的三个坑;把模板里的注释过一遍,基本就能覆盖 90% 的部署场景。


Nginx 同时代理静态资源和 API 服务
https://bubao.github.io/posts/dbc638b7.html
作者
一念
发布于
2021年11月10日
许可协议