静态页面路由重写时 Nginx URL 重写如何配

静态页面路由重写用于SPA部署时的前端路由fallback，核心是Nginx内部重写而非重定向，推荐用try_files实现最简可靠兜底，或用rewrite+last处理子路径场景，需优先配置静态资源规则避免误捕获。

静态页面路由重写，常见于单页应用（SPA）如 Vue、React 项目部署时的前端路由 fallback 场景——用户直接访问 /user/profile 这类非真实文件路径，Nginx 需“兜底”返回 index.html，由前端 JS 路由接管。这不是传统意义上的“重定向”，而是内部重写（URI 变换但浏览器地址栏不变），核心靠 try_files 或 rewrite + last 实现。

用 try_files 实现最简可靠的 fallback

这是推荐首选方式，语义清晰、性能高、无隐式跳转风险。

1. 原理：按顺序检查请求路径是否对应真实文件或目录，都不存在时，回退到指定路径（通常是 /index.html）
2. 典型配置：

   location / {root /var/www/dist;try_files $uri $uri/ /index.html;}

3. 说明：
   1. $uri 查找精确匹配的文件（如 /about.html）
   2. $uri/ 查找同名目录（如请求 /blog/，则找 /blog/index.html）
   3. /index.html 是兜底项，所有未命中路径都返回它（注意是相对于 root 的路径）

用 rewrite + last 处理带前缀的 SPA 路由

当项目部署在子路径下（如 https://example.com/app/），且前端路由 base 设为 /app/，需确保所有非资源请求都重写到 /app/index.html。

1. 关键点：避免和静态资源规则冲突，rewrite 必须放在静态资源 location 之后，且加 last 触发新一轮 location 匹配
2. 示例：

   location ^~ /app/static/ {alias /var/www/dist/static/;}
   location ^~ /app/ { root /var/www/dist;
   先排除已知静态后缀，再 fallback
   if (!-e $request_filename) {rewrite ^/app/(.*)$ /app/index.html last;}
   }

3. 注意：if 在 location 内使用是安全的，但仅限于 -e、-f 等文件系统判断；不要在 if 中嵌套 rewrite 以外的指令

区分静态资源与路由，避免误重写

图片、CSS、JS 等真实存在的文件不能被 fallback 规则捕获，否则会返回 HTML 导致解析失败。

1. 必须优先声明静态资源 location，用 ^~ 确保不被后续正则或通用规则干扰：

   location ^~ /app/static/ {alias /var/www/dist/static/;}location ^~ /app/assets/ {alias /var/www/dist/assets/;}location ~*.(js|css|png|jpg|gif|woff2?)$ {expires 1y;add_header Cache-Control "public, immutable";}

2. 所有静态规则必须放在通用路由规则之前，否则 location / 或 location ^~ /app/ 可能提前匹配，导致静态文件也走 fallback

特殊场景：精确路径重写与跳转

除 SPA fallback 外，有时需显式重写旧 URL 到新路径（如 SEO 迁移）或强制跳转（HTTP→HTTPS、www→非 www）。

1. 内部重写（浏览器地址不变）：

   rewrite ^/old-product/(d+)$ /product/$1 last;

2. 外部重定向（301/302，地址栏变化）：

   rewrite ^/old-blog/(.*)$ https://blog.example.com/$1 permanent;

3. 禁止直接访问 index.html（强制用根路径）：

   location = /index.html {return 301 /;}