从 React 到 Next.js 15 的迁移笔记

Published on: February 10, 2026
Reading time: 3 min read

为什么迁移

之前的个人网站是纯 React SPA，用 Vite 构建。迁移到 Next.js 15 的原因很简单：

SSG/SSR 混合渲染: 个人展示页面需要 SEO，交易仪表盘需要 CSR
App Router: 基于文件系统的路由 + Layout 嵌套，完美匹配三层架构
Server Components: 减少客户端 JS 体积，提升首屏性能

迁移中的关键变化

1. App Router vs Pages Router

App Router 的 layout 嵌套机制太适合三层架构了：

app/
  (public)/        → Layer 1 布局
    layout.tsx     → 宣纸主题
    page.tsx       → 首页
  (dashboard)/     → Layer 2 布局
    layout.tsx     → 灰色走廊主题
    launchpad/
  app/trader/      → Layer 3 布局
    layout.tsx     → 琥珀控制台主题

每一层有独立的 layout，主题切换零开销。

2. Server Components 默认化

Next.js 15 中组件默认是 Server Component，需要交互时手动添加 'use client'。这个思维转变很重要：

静态展示组件: 保持 Server Component（零客户端 JS）
交互组件: 如动画、表单、状态管理，标记为 'use client'
混合使用: Server Component 包裹 Client Component

3. 数据获取模式

告别 getStaticProps 和 getServerSideProps。现在在 Server Component 中直接 async/await：

typescript

// 直接在组件中获取数据 — 无需特殊 API
export default async function ProjectPage({ params }) {
  const project = await getProjectBySlug(params.slug);
  // ...
}

简洁到令人愉悦。

4. Tailwind CSS v4

与 Next.js 15 同步升级了 Tailwind v4。最大变化是配置移入 CSS：

不再需要 tailwind.config.js
主题变量直接在 globals.css 中用 @theme 定义
JIT 引擎性能显著提升

踩过的坑

Framer Motion 兼容性

Framer Motion 在 Server Component 中会报错。解决方案是把所有动画组件标记为 'use client'，或者封装一个通用的 ScrollReveal 组件统一处理。

Auth.js v5 Beta

Auth.js v5 还在 Beta 阶段，API 经常变动。建议锁定版本号，不要随意升级。

总结

Next.js 15 的 App Router 是一次质的飞跃。虽然迁移过程中有不少坑，但最终的架构清晰度和开发体验都远超之前。如果你还在用 Pages Router，强烈建议尝试迁移。