258 lines
10 KiB
Markdown
258 lines
10 KiB
Markdown
---
|
||
|
||
tags: [nginx, SPA, 部署, Slidev, 前端路由, try_files]
|
||
|
||
create time: 2026-05-28 15:30
|
||
|
||
---
|
||
# Nginx SPA 路由配置：解决前端单页应用刷新 404 问题
|
||
## 概述
|
||
|
||
本文记录了一个典型的 SPA 部署问题：将 Slidev 幻灯片站点部署到 nginx 后，直接访问子路径（如 `/resume/1`）返回 404。从根因分析（SPA 路由的本质）、nginx `location` 匹配规则、`try_files` 指令的工作原理，到最终配置方案的完整推导过程——不仅适用于 Slidev，也适用于所有使用 HTML5 History 模式的前端项目。
|
||
|
||
## 正文
|
||
|
||
### 问题现象
|
||
|
||
部署了一个 Slidev 幻灯片站点，有多个 deck（demo、resume 等）。访问首页 `http://server:8080/` 正常，点击按钮进入 resume 也正常。但把 `http://server:8080/resume/1` 分享给别人时，对方看到的是 404。
|
||
|
||
> [!question] 为什么从首页点进去一切正常，直连子链接却 404？
|
||
|
||
**关键线索**：首页能打开，assets（CSS/JS）也能加载——说明 nginx 基本工作正常，问题出在「某种特定请求路径」上。
|
||
|
||
### 根因：SPA 路由 vs 服务器路由
|
||
|
||
这是理解整个问题的核心。
|
||
|
||
**Slidev 是单页应用（SPA）**。构建后，每个 deck 目录下只有一个 `index.html`：
|
||
|
||
```
|
||
dist/resume/
|
||
├── index.html ← 唯一的 HTML 文件
|
||
├── assets/
|
||
│ ├── style.xxx.css
|
||
│ └── app.xxx.js
|
||
```
|
||
|
||
没有 `1`、`2`、`3` 这样的独立文件。幻灯片的翻页完全由浏览器端 JavaScript 完成——它读取 URL 中的数字决定显示第几页。
|
||
|
||
这就引出了两种截然不同的访问方式：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["用户点击首页按钮"] --> B["JS 执行 pushState"]
|
||
B --> C["URL 变成 /resume/1"]
|
||
C --> D["JS 读取 URL"]
|
||
D --> E["渲染对应页面"]
|
||
style A fill:#1a365d,color:#e2e8f0
|
||
style B fill:#1a365d,color:#e2e8f0
|
||
style C fill:#1a365d,color:#e2e8f0
|
||
style D fill:#1a365d,color:#e2e8f0
|
||
style E fill:#1a365d,color:#e2e8f0
|
||
```
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
F["用户直接访问 /resume/1"] --> G["浏览器发送 HTTP 请求"]
|
||
G --> H["nginx 找文件 resume/1"]
|
||
H --> I["文件不存在 → 404"]
|
||
style F fill:#742a2a,color:#fed7d7
|
||
style G fill:#742a2a,color:#fed7d7
|
||
style H fill:#742a2a,color:#fed7d7
|
||
style I fill:#742a2a,color:#fed7d7
|
||
```
|
||
|
||
| 对比维度 | 首页点击跳转 | 直接访问子路径 |
|
||
|---------|------------|--------------|
|
||
| URL 变化谁引起的 | JavaScript (`pushState`) | 用户在地址栏输入或粘贴 |
|
||
| 是否向服务器发请求 | **否**（当前页面的 JS 执行） | **是**（全新 HTTP 请求） |
|
||
| nginx 是否参与 | 不参与 | 必须参与 |
|
||
| 结果 | ✅ 正常 | ❌ 404 |
|
||
|
||
> [!tip] 核心概念
|
||
>
|
||
> SPA 的"路由"是假的。URL 变化只是浏览器地址栏的视觉效果，真正的页面切换是 JavaScript 完成的。**只有用户刷新、直接输入 URL、或分享链接给他人时**，才会真正触发服务器请求。
|
||
|
||
### Nginx 的 location 匹配规则
|
||
|
||
Nginx 用 `location` 块定义「收到什么样的请求，怎么处理」。当多条规则都能匹配时，按优先级选择：
|
||
|
||
| 优先级 | 语法 | 示例 | 说明 |
|
||
|--------|------|------|------|
|
||
| 1（最高） | `= /path` | `location = /` | 精确匹配，路径必须完全一致 |
|
||
| 2 | `~ regex` | `location ~ ^/([^/]+)/` | 正则匹配，区分大小写 |
|
||
| 3 | `~* regex` | `location ~* \.(jpg)$` | 正则匹配，**不区分**大小写 |
|
||
| 4（最低） | `/path` | `location /` | 前缀匹配，最长前缀胜出 |
|
||
|
||
当请求 `/resume/1` 时：
|
||
|
||
- `= /` → 不匹配（不是精确的 `/`）
|
||
- `~ ^/([^/]+)/` → **匹配**（符合正则），被选中
|
||
- `/` → 也匹配（前缀），但优先级低于正则
|
||
|
||
所以 nginx 会选用正则那条规则来处理。
|
||
|
||
> [!note] 最长前缀优先原则
|
||
>
|
||
> 对于非正则的普通 location（前缀匹配和精确匹配），Nginx 先选精确匹配的（如果有），然后在所有普通前缀匹配中选出**最长的**。例如请求 `/resume/1` 同时匹配 `/` 和 `/api/`，如果存在这两条规则，就会选 `/api/`。
|
||
>
|
||
> 正则匹配的优先级高于所有普通 location，且**第一个匹配的正则就停**，不按长度择优。
|
||
|
||
### try_files 指令
|
||
|
||
`try_files` 是 Nginx 的核心指令之一，语法：
|
||
|
||
```nginx
|
||
try_files file1 file2 ... fallback;
|
||
```
|
||
|
||
Nginx 按顺序尝试每个文件，**第一个存在的就返回**，全部不存在才执行最后一个 fallback（通常是 `=404`）。
|
||
|
||
来看我们最终方案中的核心行：
|
||
|
||
```nginx
|
||
try_files $uri $uri/ /$1/index.html =404;
|
||
```
|
||
|
||
逐层拆解：
|
||
|
||
| 尝试项 | 含义 | 请求 `/resume/1` 时的表现 |
|
||
|--------|------|-------------------------|
|
||
| `$uri` | 请求的原始路径 | 检查文件 `/usr/share/nginx/html/resume/1` → **不存在** |
|
||
| `$uri/` | 路径末尾加 `/` | 检查目录 `/usr/share/nginx/html/resume/1/` → **不存在** |
|
||
| `/$1/index.html` | 用正则捕获组构造回退路径 | `$1` = `resume` → 检查 `/usr/share/nginx/html/resume/index.html` → **存在！返回它** |
|
||
| `=404` | 终极兜底 | 只有以上全失败才走这里 |
|
||
|
||
> [!example] try_files 的执行流程
|
||
>
|
||
> ```mermaid
|
||
> flowchart TD
|
||
> S["收到请求 /resume/1"] --> T1{"$uri 是文件?"}
|
||
> T1 -->|存在| R1["返回该文件 ✅"]
|
||
> T1 -->|不存在| T2{"$uri/ 是目录?"}
|
||
> T2 -->|存在| R2["返回目录下的 index ✅"]
|
||
> T2 -->|不存在| T3{"/$1/index.html 存在?"}
|
||
> T3 -->|存在| R3["返回 SPA 入口 index.html ✅"]
|
||
> T3 -->|不存在| R4["=404 ❌"]
|
||
> style S fill:#1a365d,color:#e2e8f0
|
||
> style T1 fill:#2a4365,color:#e2e8f0
|
||
> style T2 fill:#2a4365,color:#e2e8f0
|
||
> style T3 fill:#2a4365,color:#e2e8f0
|
||
> style R1 fill:#276749,color:#fff
|
||
> style R2 fill:#276749,color:#fff
|
||
> style R3 fill:#276749,color:#fff
|
||
> style R4 fill:#742a2a,color:#fff
|
||
> ```
|
||
|
||
### 最终的 Nginx 配置
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name _;
|
||
root /usr/share/nginx/html;
|
||
index index.html;
|
||
|
||
# 规则 1：首页，精确匹配
|
||
location = / {
|
||
try_files /index.html =404;
|
||
}
|
||
|
||
# 规则 2：带尾斜杠的路径，如 /resume/、/resume/1、/demo/assets/style.css
|
||
location ~ ^/([^/]+)/ {
|
||
try_files $uri $uri/ /$1/index.html =404;
|
||
}
|
||
|
||
# 规则 3：不带尾斜杠的路径，如 /resume
|
||
location ~ ^/([^/]+)$ {
|
||
try_files $uri $uri/ =404;
|
||
}
|
||
}
|
||
```
|
||
|
||
三条规则的分工：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
R["收到请求"] --> Q1{"路径是 / ?"}
|
||
Q1 -->|是| A1["规则 1\n返回首页 index.html"]
|
||
Q1 -->|否| Q2{"有尾部斜杠?"}
|
||
Q2 -->|是| A2["规则 2\n找真实文件 → 找不到返回 SPA 入口"]
|
||
Q2 -->|否| A3["规则 3\n找文件 → 找不到则 301 重定向"]
|
||
style R fill:#1a365d,color:#e2e8f0
|
||
style Q1 fill:#2a4365,color:#e2e8f0
|
||
style Q2 fill:#2a4365,color:#e2e8f0
|
||
style A1 fill:#276749,color:#fff
|
||
style A2 fill:#276749,color:#fff
|
||
style A3 fill:#276749,color:#fff
|
||
```
|
||
|
||
逐个请求验证：
|
||
|
||
| 请求 | 匹配规则 | try_files 执行过程 | 结果 |
|
||
|------|---------|-------------------|------|
|
||
| `/` | 规则 1 `= /` | 直接返回 `/index.html` | ✅ 首页 |
|
||
| `/resume/` | 规则 2 | `$uri/` 是目录 → 返回目录内 index.html | ✅ 幻灯片 |
|
||
| `/resume/1` | 规则 2 | `$uri` 不存在 → `$uri/` 不存在 → `/$1/index.html` = `/resume/index.html` | ✅ 幻灯片 |
|
||
| `/demo/assets/style.css` | 规则 2 | `$uri` 是真实文件 → 直接返回 | ✅ CSS 资源 |
|
||
| `/resume` | 规则 3 | `$uri` 是目录 → `$uri/` 存在 → nginx 自动 301 到 `/resume/` | 🔄 重定向 |
|
||
|
||
> [!important] 正则捕获组的妙用
|
||
>
|
||
> `^/([^/]+)/` 中 `()` 内的 `[^/]+` 匹配"一个或多个非斜杠字符"。对于 `/resume/1`，捕获组 `$1` 的值就是 `resume`。这样 `/$1/index.html` 就能动态拼出 `/resume/index.html`，把所有同目录的子路径都指向同一个 SPA 入口——这就是所谓的"catch-all"模式。
|
||
|
||
#### 为什么需要三条规则？
|
||
|
||
你可能会问：一条 `location / { try_files $uri $uri/ /index.html =404; }` 不就完了吗？
|
||
|
||
确实可以，但有隐患：
|
||
|
||
| 方案 | 优点 | 缺点 |
|
||
|------|------|------|
|
||
| 一条通用规则 | 简洁 | 会把 `/api/xxx`、`/admin/` 等后端路径也错误地返回 index.html |
|
||
| 分规则处理 | 精准控制，不影响其他服务 | 略复杂，需要理清每条的职责 |
|
||
|
||
对于只跑前端的静态站点，一条规则就够了。但如果 nginx 还要代理后端 API，就需要用更细粒度的规则来隔离前后端路径。这也解释了为什么我们要设计三条独立的规则而非一条通用的。
|
||
|
||
### 调试与常见问题
|
||
|
||
在配置 nginx 时遇到问题？以下是实用的排查思路：
|
||
|
||
```yaml
|
||
# CI 流水线中的配置验证（临时加入，确认部署成功后可移除）
|
||
- name: Verify nginx config
|
||
run: |
|
||
docker run -d --name slides-nginx-test -p 9080:80 nginx:alpine
|
||
docker cp nginx.conf slides-nginx-test:/etc/nginx/conf.d/default.conf
|
||
docker cp dist/. slides-nginx-test:/usr/share/nginx/html/
|
||
docker exec slides-nginx-test nginx -s reload
|
||
curl -s -o /dev/null -w "%{http_code}" http://localhost:9080/resume/1 && echo "OK" || echo "FAIL"
|
||
docker rm -f slides-nginx-test
|
||
```
|
||
|
||
常见陷阱：
|
||
|
||
1. **没重载配置**：改了 `.conf` 文件后，必须 `nginx -s reload` 或重启容器。否则旧的配置仍在生效。
|
||
2. **权限问题**：`docker cp` 后的文件属主可能是 root，而 nginx worker 以 `nginx` 用户运行，可能出现 Permission denied。确保 `root` 指向的目录对所有用户可读。
|
||
3. **`try_files` 最后必须是文件或 `=code`**：不能以目录名结尾（如 `try_files $uri $uri/ /index.html/` 是错的，应写 `try_files $uri $uri/ /index.html =404`）。
|
||
|
||
### 举一反三
|
||
|
||
这个配置模式适用于所有使用 HTML5 History 路由的前端项目：
|
||
|
||
| 框架/工具 | 路由方式 | 适用此方案 |
|
||
|----------|---------|-----------|
|
||
| React Router | `<BrowserRouter>` (History 模式) | ✅ |
|
||
| Vue Router | `mode: 'history'` | ✅ |
|
||
| VitePress / Docusaurus | 内置 History 模式 | ✅ |
|
||
| Slidev | 内置 History 模式 | ✅ |
|
||
| Angular Router | 默认 History 模式 | ✅ |
|
||
|
||
> [!tip] 一句话总结
|
||
>
|
||
> **Nginx 不认识的路径，统统交给前端的 `index.html`，让 JavaScript 去接管路由。**
|
||
|
||
## 关联笔记
|
||
|
||
- [[Slidev 项目结构与部署]]
|