Vercel部署带自定义rewrites的Next.js应用出现全路由404错误

修复步骤 #

1. 调整配置文件位置
   将根目录下的vercel.json移动到frontend目录内——因为你已在Vercel项目设置中指定部署根目录为frontend，Vercel只会读取该目录下的配置文件，根目录的配置不会生效。

2. 修正vercel.json配置
   根据你的Next.js部署模式选择对应配置：

   模式1：静态导出（next.config.js含output: "export"）

   若你采用纯静态部署，需配置路由重写让所有请求指向index.html，确保客户端路由能接管URL：

   {
     "version": 2,
     "cleanUrls": false,
     "trailingSlash": false,
     "rewrites": [
       {
         "source": "/(.*)",
         "destination": "/index.html"
       }
     ]
   }
   

   模式2：Vercel原生托管（默认，非静态导出）

   若未设置静态导出，Vercel会自动处理App Router的所有路由，无需额外重写规则，直接简化配置（甚至可删除vercel.json）：

   {
     "version": 2
   }
   

3. 验证路由文件结构
   确保App Router的路由文件路径完全匹配请求URL：

   • /search → frontend/app/search/page.tsx
   • /favorites → frontend/app/favorites/page.tsx
   • /books/harry-potter → frontend/app/books/[slug]/page.tsx

疑问解答 #

1. 非根路由404的原因

   • 配置文件位置错误：根目录的vercel.json未被Vercel读取，导致路由规则失效。
   • 原重写规则错误：destination: "/"会将所有请求硬定向到根页面，而非让Next.js客户端路由处理URL，直接触发Vercel的404。
   • 静态导出未配置正确重写：纯静态部署时，Vercel无法找到对应路由的静态文件，必须重写指向index.html。

2. monorepo子目录的vercel.json配置

   • 配置文件必须放在前端子目录（frontend）中。
   • 无需手动配置builds：Vercel会自动识别子目录中的Next.js项目，只需在项目设置中指定部署根目录为frontend。
   • 根据部署模式调整重写规则，参考上述修复步骤。

3. App Router与Pages Router的Vercel部署要求

   • App Router：Vercel原生支持，默认自动处理路由；静态导出时必须配置重写指向index.html以支持刷新。
   • Pages Router：同样自动支持，静态导出时需类似重写配置或使用exportPathMap生成静态文件。
   • 两者核心差异仅在路由文件结构，Vercel对部署的支持无本质区别，遵循各自路由规范即可。

4. 客户端路由的最优处理方式

   • 优先使用Vercel原生托管模式：无需额外配置即可支持SSR/SSG/ISR，刷新非根URL不会404，兼顾性能与SEO。
   • 若必须静态导出，确保vercel.json重写规则正确，同时使用Next.js的useRouter进行客户端导航，减少直接刷新场景（配置后刷新也可正常工作）。
   • 避免手动配置不必要的重写规则，依赖Vercel对Next.js的原生支持即可。

内容的提问来源于stack exchange，提问作者Alu