Nginx 配置文件解析：部署单页应用（SPA）

本文将讲解如何通过 Nginx 配置文件部署单页应用（SPA），并解释每一行的作用以及是否是必要的。

配置文件解析

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
server {
    listen 80 default_server;                      # 必要：监听 80 端口
    listen [::]:80 default_server;                 # 必要：同时监听 IPv6 的 80 端口

    server_name _;                                 # 必要：指定服务器名称，使用通配符表示任何域名
    root /var/www/html;                            # 必要：指定服务器静态文件的根目录
    # 让所有请求都指向 index.html，支持前端路由
    try_files $uri $uri/ /index.html;              # 必要：当请求路径未匹配到静态文件时，返回 index.html

    # 代理到 API
    location ^~ /api/ {                            # 必要：定义一个独立的代理路由前缀
        proxy_pass http://127.0.0.1:8080/;         # 必要：将请求代理到后端服务
        proxy_set_header Host $host;               # 可选：传递原始 host 头到后端
        proxy_set_header X-Real-IP $remote_addr;   # 可选：传递客户端真实 IP 到后端
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 可选：记录转发的 IP 链
        proxy_set_header REMOTE-HOST $remote_addr; # 可选：传递客户端真实 IP 到后端（备用字段）
        proxy_set_header Upgrade $http_upgrade;    # 可选：支持 WebSocket 协议升级
        proxy_set_header Connection $http_connection; # 可选：传递连接状态
        proxy_set_header X-Forwarded-Proto $scheme; # 可选：传递请求协议（HTTP/HTTPS）
        proxy_http_version 1.1;                    # 可选：设置使用的 HTTP 协议版本
        add_header X-Cache $upstream_cache_status; # 可选：添加响应头，显示缓存状态
        add_header Cache-Control no-cache;         # 可选：添加响应头，禁止缓存
        proxy_ssl_server_name off;                 # 可选：关闭 SSL 服务器名称指示支持
        proxy_ssl_name $proxy_host;                # 必要：指定后端服务器的 SSL 名称
    }
}

配置详解

listen 80 default_server

  • 作用：监听 80 端口，接收 HTTP 请求。
  • 是否必要：是，这是部署 Web 应用的基础。通常生产环境会选择 80 或 443 端口（HTTPS）。

listen [::]:80 default_server

  • 作用：监听 IPv6 的 80 端口，确保 IPv6 用户可以访问。
  • 是否必要：可选，现代网络环境下 IPv6 用户不可忽视。如果仅支持 IPv4 可省略。

server_name _

  • 作用：指定服务器名称，_ 表示匹配任何域名。
  • 是否必要：是，如果没有配置域名，使用通配符允许直接通过 IP 访问。

root /var/www/html

  • 作用：指定静态文件的根目录。
  • 是否必要：是，这是存放单页应用前端代码的地方。

try_files $uri $uri/ /index.html

  • 作用：支持前端路由的核心配置。
    • 如果请求路径匹配到静态文件（如 index.html 或 CSS 文件），直接返回。
    • 如果请求路径是目录（如 /about），尝试返回目录下的 index.html。
    • 如果以上都未匹配到，返回 /index.html，由前端路由处理。
  • 是否必要：是，这是单页应用能够正常工作的重要配置。

location ^~ /api/

  • 作用：定义一个独立的代理路径前缀。所有以 /api/ 开头的请求都将进入此区块处理。
  • 是否必要：是，单页应用通常会与后端 API 对接，需要代理后端服务。

proxy_pass http://127.0.0.1:8080/

  • 作用：将 /api/ 开头的请求代理到本地的 8080 端口。
  • 是否必要：是，这是实现前后端分离的关键配置。

proxy_set_header 各行

  • 作用：设置代理请求头，将客户端信息传递给后端服务器。
  • 是否必要：可选，但建议保留。它们可以帮助后端服务器更好地处理请求（如获取客户端 IP、支持 WebSocket 等）。

proxy_http_version 1.1

  • 作用：设置代理使用的 HTTP 协议版本。
  • 是否必要：可选，默认情况下多数情况下使用 HTTP 1.1。

add_header 各行

  • 作用：添加响应头。
  • 是否必要：可选，但 Cache-Control no-cache 是推荐的，可防止客户端缓存旧数据。

proxy_ssl_server_name off

  • 作用：关闭 SSL 服务器名称指示支持。
  • 是否必要：可选，通常不需要。

proxy_ssl_name $proxy_host

  • 作用：为后端服务器指定 SSL 名称。
  • 是否必要：是，支持 HTTPS 后端时需要。

总结

  • 单页应用关键配置：try_files $uri $uri/ /index.html 是最核心的部分，支持前端路由。
  • 代理服务配置：proxy_pass 和 location 块定义了如何将 /api/ 请求转发到后端。
  • 其他配置：proxy_set_header 和 add_header 用于改善前后端通信和响应行为，虽然不是完全必要，但建议保留。