Nginx 配置踩坑大全：我在生产环境犯过的 8 个错误
Nginx Configuration Pitfalls: 8 Mistakes I Made in Production
| Ryan Zhang | 2026-08-04T18:15:18
用了好几年 Nginx，还是经常踩坑。这篇文章总结了我在生产环境犯过的 8 个典型配置错误，有些真的很隐蔽。
A collection of 8 common Nginx configuration mistakes encountered in production environments, including some surprisingly subtle ones.
## 错误 1：location 匹配顺序搞不清 ```nginx # 以为这样可以拦截所有 /api/ 请求 location /api/ { proxy_pass http://backend; } # 实际上这个会优先匹配 location /api/upload { client_max_body_size 100m; proxy_pass http://backend; } ``` Nginx 的 location 匹配规则： 1. `=` 精确匹配（最高优先级） 2. `^~` 前缀匹配（停止正则搜索） 3. `~` / `~*` 正则匹配（按配置文件顺序） 4. 普通前缀匹配（最长匹配优先） 我之前以为正则是按"最长匹配"，结果是按"配置文件中的顺序"。调了一下午才发现。 **建议**：对确定的路径用 `^~`，避免被后面的正则覆盖。 ## 错误 2：proxy_pass 末尾的斜杠 这个坑每年都有人踩： ```nginx # 有斜杠：/api/users → http://backend/users location /api/ { proxy_pass http://backend/; } # 没斜杠：/api/users → http://backend/api/users location /api/ { proxy_pass http://backend; } ``` 一个斜杠的差别，转发路径完全不同。我在这上面浪费了无数时间。 ## 错误 3：没设置 proxy_set_header ```nginx location /api/ { proxy_pass http://backend; # 如果不设这些，后端拿到的全是错误信息 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; } ``` 有一次后端日志里所有请求的 IP 都是 `127.0.0.1`，排查了半天——忘了设 `X-Real-IP`。 ## 错误 4：WebSocket 反代缺配置 ```nginx location /ws/ { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } ``` 少了 `Upgrade` 和 `Connection` 头，WebSocket 握手直接失败，浏览器只会告诉你一个模糊的 "connection failed"。 ## 错误 5：缓冲区太小导致 502 ```nginx # 默认的 proxy_buffer 只有 4k/8k # 后端返回的 header 太大（比如一堆 Set-Cookie）就会 502 proxy_buffer_size 16k; proxy_buffers 4 32k; proxy_busy_buffers_size 64k; ``` 我们的 SSO 系统登录后会设十几个 Cookie，默认缓冲区装不下，Nginx 直接返回 502。日志里的报错是 `upstream sent too big header`，如果不知道这个坑，很容易往后端方向排查。 ## 错误 6：try_files 和 SPA 的坑 ```nginx # SPA 应用必须这样配 location / { try_files $uri $uri/ /index.html; } ``` 不加 `try_files`，用户直接访问 `/about`、`/dashboard` 这类前端路由会 404。这是 SPA 的基操，但新手经常忘。 还有一个更隐蔽的坑：如果你把 API 也放在同一个 server 块里，`try_files` 会把 API 请求也重定向到 `index.html`。所以 API 的 location 必须用 `^~` 或放在前面。 ## 错误 7：gzip 没排除图片 ```nginx gzip on; gzip_types text/plain text/css application/json application/javascript text/xml; # 千万别加 image/png image/jpeg！ # 图片已经是压缩格式，再 gzip 反而会变大，还浪费 CPU ``` 有一次我手抖加了 `image/*`，CPU 使用率直接涨了 30%，但传输大小一点没变。 ## 错误 8：没限制请求体大小 ```nginx # 默认只允许 1MB 的请求体 # 文件上传接口必须单独设置 location /api/upload { client_max_body_size 50m; proxy_pass http://backend; } ``` 默认 1MB 的限制对大多数 API 够用，但文件上传接口会直接返回 `413 Request Entity Too Large`。而且这个错误在开发环境经常不会出现（因为测试文件小），到了生产环境用户上传大文件才暴露。 ## 一些通用建议 1. **改完配置先 `nginx -t`**，语法检查不通过就别 reload 2. **用 `include` 拆分配置文件**，别把所有东西塞一个 `nginx.conf` 3. **日志格式加上 `$upstream_response_time`**，方便分析后端耗时 4. **定期检查 error.log**，很多问题在 access.log 里看不出来 Nginx 是个看起来简单但细节很多的工具，希望这些踩坑经验能帮大家少走弯路。
## 8 Production Nginx Mistakes 1. **Location matching order**: regex matches by config order, not longest match 2. **Trailing slash in proxy_pass**: completely changes the forwarded path 3. **Missing proxy_set_header**: backend gets wrong IP and host info 4. **WebSocket missing Upgrade headers**: silent connection failure 5. **Buffer too small for large headers**: causes 502 with SSO cookies 6. **Missing try_files for SPA**: frontend routes return 404 7. **Gzipping images**: wastes CPU without reducing size 8. **Default body size limit**: blocks file uploads with 413 error Each mistake includes the fix and how to avoid it in the future.