Vercel平台部署React Router 7应用的路由配置实践

背景介绍

在Vercel平台上部署基于React Router 7（简称RR7）的应用时，开发者可能会遇到路由配置的特殊情况。特别是当应用采用路径无布局（pathless layouts）结构时，Vercel预设的路由解析机制可能会出现404错误。本文将深入分析这一问题，并提供完整的解决方案。

核心问题分析

React Router 7引入了一种新的路由组织方式，允许开发者使用下划线前缀（如_marketing）来定义布局组件，而无需在URL路径中体现。这种设计模式在本地开发环境中运行良好，但在部署到Vercel平台时可能会遇到路由解析问题。

典型的问题场景包括：

1. 路径无布局组件的索引路由（如_marketing._index）无法被正确识别
2. 嵌套路由结构（如auth.sign-in._index）返回404错误
3. Vercel预设配置与RR7的路由约定不完全兼容

解决方案详解

1. 调整Remix配置文件

在remix.config.js中明确指定路由映射关系是解决问题的第一步。关键配置项包括：

/** @type {import('@remix-run/dev').AppConfig} */
export default {
  ignoredRouteFiles: ["**/.*"],
  serverModuleFormat: "esm",
  future: {
    v2_routeConvention: true  // 启用RR7路由约定
  },
  routes(defineRoutes) {
    return defineRoutes((route) => {
      route("_marketing", "routes/_marketing._index.tsx");
      route("auth/sign-in", "routes/auth.sign-in._index.tsx");
    });
  }
};

2. 规范项目目录结构

正确的文件组织结构对于路由解析至关重要。推荐采用以下结构：

app/
 ├── routes/
 │    ├── _marketing._index.tsx
 │    ├── _marketing.blog.tsx
 │    ├── auth/
 │    │    ├── sign-in/
 │    │    │   ├── _index.tsx
 │    │    │   ├── route.tsx

3. 配置Vercel重写规则

在项目根目录下的vercel.json中添加路由重写规则：

{
  "rewrites": [
    { "source": "/marketing", "destination": "/_marketing._index" },
    { "source": "/auth/sign-in", "destination": "/auth.sign-in._index" }
  ]
}

4. 可选：自定义服务器配置

对于更复杂的场景，可以创建自定义服务器文件server.ts：

import { createRequestHandler } from "@remix-run/vercel";
import * as build from "@remix-run/dev/server-build";

export default createRequestHandler({ build });

并在package.json中更新启动脚本：

"scripts": {
  "start": "node server.ts"
}

部署验证与最佳实践

完成上述配置后，建议按照以下步骤验证部署效果：

1. 本地测试：确保所有路由在开发环境中正常工作
2. 预发布验证：使用vercel deploy命令进行预发布测试
3. 生产部署：确认无误后执行vercel deploy --prod

最佳实践建议：

• 保持路由命名的清晰和一致性
• 对于大型项目，考虑分阶段迁移路由配置
• 定期检查Vercel平台的路由预设更新

总结

通过合理配置Remix路由和Vercel平台设置，开发者可以充分利用React Router 7的先进路由特性，同时确保在Vercel平台上获得稳定的部署效果。本文提供的解决方案涵盖了从基础配置到高级自定义的完整流程，适用于各种规模的项目部署需求。