最佳实践

快速决策

栈选择指南

React 应用在进入生产阶段通常会在「全栈框架」与「前端优先」两类方案之间抉择：

• Next.js Stack 借助 App Router 与 RSC 打通服务端与客户端的数据流，适合强调 BFF、SEO、全局缓存的团队。
• Vite + TanStack Stack 聚焦于极致的开发体验与客户端渲染，凭借 Vite 构建链得到更快的启动与按需扩展能力。

React Server Components 支持

• Next.js：原生支持 RSC，可在下列场景发挥优势：
  • 页面需要依赖敏感后端凭证读取数据，且不希望在客户端暴露。
  • 页面结构复杂、组件层级深，希望利用服务器端渲染减少客户端 bundle 大小。
  • 需要 ISR/SSG/SSR 混合策略，或借助 cache(), revalidatePath() 等能力管理数据失效。
• Vite + TanStack：暂不支持 RSC，更适合以下场景：
  • 业务核心在客户端交互，对 SEO 要求不高。
  • 数据请求可通过 edge function / BFF 服务自行封装。
  • 团队希望保持完全的客户端状态管理模型（TanStack Query、zustand 等）。

性能与扩展性

全面对比

共通能力对照

无论选择 Next.js 还是 Vite + TanStack Start，团队都可以复用大量一致的工程能力，并依据项目需求挑选最合适的实现形式：

• 文件路由与动态段：Next.js App Router 的 app/**/[slug]/page.tsx 与 TanStack Start 的 createFileRoute('/:slug') 都支持动态与捕获式路由组织。¹
• 数据获取与预渲染：Next.js 借助 Server Components、fetch 缓存与 ISR；TanStack Start 提供 Loader、Selective SSR 与 SPA 模式开关，均可在渲染前获取数据并控制缓存策略。¹²
• 服务函数 & 中间层：Next.js 的 Server Actions、Route Handlers、Middleware，可对应到 TanStack Start 的 createServerFn()、Server Routes 以及 Middleware 管线，满足鉴权、日志与 API 代理等需求。¹
• SEO 与 Head 管理：Next.js generateMetadata 支持异步生成 meta 信息；TanStack Start 通过 Loader + Head 配置同样可以动态注入 SEO 数据。¹
• 脚手架与模板生态：Next.js 有 create-next-app 与丰富的官方示例；TanStack Start CLI 也提供一键脚手架与多种示例（React Query、Auth、Convex 等），并可直连 Netlify 等平台快速部署。²
• Tailwind 等周边集成：两者都原生支持 Tailwind CSS、环境变量体系、代码拆分与懒加载，Registry 的 Theme、UI、Hook、Item 也可在两种栈中无缝复用。¹²

选择栈时先确认是否需要 RSC 与一体化部署；若主要诉求是快速迭代与轻量构建，则可优先考虑 Vite + TanStack 方案。

场景决策树

选 Next.js 的场景 ▲

选 TanStack Start 的场景 ⚡

都可以的场景 🤝

• 中后台 + 少量 C 端页面混合
• API 驱动的 CRUD 应用
• 内部工具平台

安全风险 🔐

SSR/RSC 相关

// ❌ 危险：整个 user 对象可能包含敏感字段
const user = await db.user.findUnique({ where: { id } })
return <Profile user={user} />

// ✅ 安全：显式选择暴露的字段
const user = await db.user.findUnique({
  where: { id },
  select: { name: true, avatar: true }
})
return <Profile user={user} />

Server Actions / Server Functions

• 🛡️ CSRF 防护：Next.js Server Actions 内置 CSRF token；TanStack createServerFn 需自行配置
• ✅ 输入验证：始终使用 Zod 等库验证输入，不信任客户端数据
• 🔑 权限检查：每个 Action/Function 内部独立验证用户权限

// ✅ 始终验证
export async function updateProfile(input: unknown) {
  const session = await getSession()
  if (!session) throw new Error('Unauthorized')

  const data = profileSchema.parse(input) // Zod 验证
  // ...
}

环境变量

案例入口