Nginx 同时代理静态资源和 API 服务
前后端分离项目交付时,常见需求是在同一个对外端口上完成分发:/ 返回 SPA 打包产物、/api/ 转发给后端服务、/upload/ 直接读服务器上的用户上传文件。三者对 Nginx 的能力要求完全不同:静态要缓存高效,API 要代理转发并保留真实客户端信息,上传目录要兼顾路径映射与体积上限。
一、路由拓扑
1 | |
注意三处前缀都带尾斜杠:/api/ 与 /upload/ 写成不带尾斜杠会意外匹配 /apixxx、/uploadxxx 这类路径。
二、完整配置模板
以下几段合起来是一份可直接套用的配置。upstream 和 map 属于 http 块(nginx.conf 里),其余在 server 块:
1 | |
1 | |
三、关键细节拆解
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 | |
会把所有请求的 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 | |
API 侧重点确认后端拿到的 Host、X-Real-IP、X-Forwarded-For 是否为真实值;前端重点确认预压缩资源 Content-Encoding: gzip 正常。
五、常见问题
| 现象 | 原因 / 处理 |
|---|---|
| 刷新 SPA 子路由 404 | 缺 try_files ... /index.html;确认 location / 的 root 指向构建产物目录 |
| 缺失 JS 变成 200 的 HTML | try_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 404 | root/alias 尾斜杠不一致;API 路径里 /api 匹配到了 /apixxx |
六、参考资料
- Nginx 官方文档:ngx_http_proxy_module ——
proxy_pass拼接规则、请求头、超时、缓冲; - Nginx 官方文档:WebSocket 代理;
- Nginx 官方文档:root / alias;
- Nginx 官方文档:try_files / client_max_body_size;
- Vue Router:History 模式、React Router:部署说明 —— 为什么 SPA 需要服务端回退。
七、小结
一套配置同时服务三种资源,本质是把三种不同的语义放对位置:静态讲缓存与回退,API 讲透传与超时,上传目录讲体积与安全。proxy_pass 拼路径、WebSocket 升级、缓存头写几次,是最常踩的三个坑;把模板里的注释过一遍,基本就能覆盖 90% 的部署场景。
