cra-to-next-migration

CRA 到 Next.js 迁移指南

全面的迁移指南，介绍如何将 Create React App 项目转换为 Next.js，涵盖路由、数据获取、组件、样式和部署。包含 17 个类别中的 148 条规则，并按迁移影响优先级排序。迁移成功后，应用的运行效果应与迁移前相同。

适用场景

在以下情况下参考这些指南：

• 将现有 CRA 应用迁移到 Next.js
• 将 React Router 路由转换为基于文件的路由
• 在客户端渲染占比较高的应用中采用 Server Components
• 从客户端渲染转向 SSR/SSG
• 更新 Next.js 环境变量
• 使用 Next.js 内置功能优化图像和字体

版本策略

使用 Next.js 16.x 或更高版本。请勿使用 Next.js 14.x 或 15.x。

开始迁移前，请检查当前最新版本：

npm info next version

在 package.json 中使用最新版本，并为次版本和补丁版本更新添加插入符号。此迁移指南支持的最低版本为 ^16.0.0。

按优先级划分的规则类别

优先级	类别	影响	前缀	规则数
1	项目设置	严重	setup-	6
2	依赖项	严重	deps-	1
3	路由	严重	routing-	17
4	数据获取	严重	data-	11
5	组件	高	components-	9
6	环境变量	高	env-	6
7	样式	高	styling-	12
8	公共资源	中	assets-	5
9	图像	中	images-	8
10	字体	中	fonts-	6
11	SEO 与元数据	中	seo-	9
12	API 路由	中	api-	9
13	状态管理	中	state-	8
14	集成	中	integrations-	1
15	测试	低	testing-	9
16	构建与部署	低	build-	7
17	常见问题	高	gotchas-	24

快速参考

1. 项目设置（严重）

• setup-initial-structure - 将 CRA 文件夹结构转换为 Next.js App Router
• setup-package-json - 更新依赖项和脚本
• setup-next-config - 创建并配置 next.config.js
• setup-typescript - 迁移 TypeScript 配置
• setup-eslint - 更新 Next.js 的 ESLint 配置
• setup-gitignore - 更新 Next.js 的 .gitignore

2. 依赖项（严重）

• deps-react19-compatibility - 升级依赖项以兼容 React 19

3. 路由（关键）

• routing-basic-pages - 将组件转换为基于文件的路由
• routing-dynamic-routes - 使用 [param] 语法表示动态片段
• routing-catch-all-routes - 使用 [...slug] 表示全捕获路由
• routing-optional-catch-all - 使用 [[...slug]] 表示可选的全捕获路由
• routing-route-groups - 使用 (group) 文件夹进行组织
• routing-parallel-routes - 使用 @slot 实现并行路由
• routing-intercepting-routes - 使用 (..) 实现拦截路由
• routing-link-component - 将 react-router Link 替换为 next/link
• routing-programmatic-navigation - 将 useNavigate 替换为 useRouter
• routing-use-params - 将 useParams 替换为 Next.js params
• routing-use-search-params - 正确替换 useSearchParams
• routing-nested-layouts - 将嵌套路由转换为布局
• routing-loading-states - 添加 loading.tsx 以支持 suspense
• routing-error-boundaries - 添加 error.tsx 以处理错误
• routing-not-found - 添加 not-found.tsx 以创建 404 页面
• routing-hash-based - 为仅客户端应用处理基于哈希的路由
• routing-protected-routes - 实现受保护路由模式

4. 数据获取（关键）

• data-useeffect-to-rsc - 将 useEffect 数据获取转换为 Server Components
• data-useeffect-to-ssr - 将 useEffect 转换为 getServerSideProps
• data-useeffect-to-ssg - 将 useEffect 转换为 getStaticProps
• data-client-fetch - 按照正确的模式保留客户端数据获取
• data-server-actions - 使用 Server Actions 执行变更
• data-revalidation - 配置数据重新验证策略
• data-streaming - 使用 Suspense 流式传输数据
• data-parallel-fetching - 在服务端并行获取数据
• data-sequential-fetching - 处理顺序数据依赖
• data-caching - 配置 fetch 缓存行为
• data-client-library-init - 在 useEffect 中初始化仅客户端库

5. 组件（高）

• components-use-client - 为客户端组件添加 'use client' 指令
• components-server-default - 了解服务端组件是默认组件
• components-boundary-placement - 策略性地放置客户端边界
• components-composition - 使用组合来尽量减少客户端 JS
• components-interleaving - 交错使用服务端和客户端组件
• components-props-serialization - 确保 props 可序列化
• components-children-pattern - 将服务端组件作为 children 传递
• components-context-providers - 正确处理 Context 提供程序
• components-third-party - 包装第三方客户端组件

6. 环境变量（高）

• env-prefix-change - 将 REACTAPP 改为 NEXTPUBLIC
• env-server-only - 服务端专用变量使用无前缀名称
• env-runtime-config - 根据需要使用运行时配置
• env-local-files - 了解 .env 文件的加载顺序
• env-build-time - 了解构建时与运行时环境变量的区别
• env-validation - 验证必需的环境变量

7. 样式（高）

• styling-global-css - 将全局 CSS 移至 app/layout.tsx
• styling-css-modules - CSS Modules 只需少量修改即可使用
• styling-sass - 配置 Sass 支持
• styling-tailwind - 配置 Tailwind CSS
• styling-css-in-js - 处理 CSS-in-JS 库
• styling-styled-components - 配置 styled-components 以支持 SSR
• styling-emotion - 配置 Emotion 以支持 SSR
• styling-component-styles - 正确导入组件样式
• styling-postcss - 配置 PostCSS
• styling-scss-global-syntax - 仅在 CSS Modules 中使用 :global
• styling-css-import-order - 控制布局中的 CSS 导入顺序
• styling-dark-mode-hydration - 处理深色模式，避免水合不匹配

8. 公共资源（中）

• assets-public-folder - Public 文件夹的工作方式不变
• assets-static-imports - 使用静态导入来引入资源
• assets-absolute-urls - 引用资源时无需添加 public 前缀
• assets-favicon - 将 favicon 放在 app 目录中
• assets-manifest - 配置 Web 应用清单

9. 图像（中）

• images-next-image - 使用 next/image 替换 img
• images-required-dimensions - 指定宽度和高度
• images-fill-prop - 使用 fill 实现响应式图像
• images-priority - 为 LCP 图像设置 priority
• images-placeholder - 配置模糊占位符
• images-remote-patterns - 配置远程图像域名
• images-loader - 配置自定义图像加载器
• images-optimization - 了解自动优化

10. 字体（中）

• fonts-next-font - 使用 next/font 进行优化
• fonts-google-fonts - 正确加载 Google Fonts
• fonts-local-fonts - 加载本地字体文件
• fonts-variable-fonts - 配置可变字体
• fonts-font-display - 配置 font-display 策略
• fonts-preload - 了解自动字体预加载

11. SEO 与元数据（中）

• seo-metadata-api - 使用 Metadata API 替代 react-helmet
• seo-dynamic-metadata - 生成动态元数据
• seo-opengraph - 配置 Open Graph 元数据
• seo-twitter-cards - 配置 Twitter Card 元数据
• seo-json-ld - 添加结构化数据（JSON-LD）
• seo-canonical - 设置规范 URL
• seo-robots - 配置 robots 元标签
• seo-sitemap - 生成 sitemap.xml
• seo-head-component - 从 next/head 迁移到 Metadata

12. API 路由（中）

• api-route-handlers - 在 app/api 中创建 Route Handlers
• api-http-methods - 为 HTTP 方法导出具名函数
• api-request-body - 正确解析请求正文
• api-query-params - 访问查询参数
• api-headers-cookies - 访问标头和 Cookie
• api-response-types - 返回适当的响应类型
• api-middleware - 实现中间件模式
• api-cors - 正确配置 CORS
• api-rate-limiting - 实现速率限制

13. 状态管理（中）

• state-context-client - Context 需要 'use client'
• state-zustand - 使用 Zustand 时需谨慎处理水合
• state-redux - 使用 Next.js 配置 Redux
• state-jotai - 正确配置 Jotai
• state-recoil - 正确配置 Recoil
• state-url-state - 使用 URL 存储可共享状态
• state-server-state - 使用 RSC 尽量减少客户端状态
• state-persistence - 处理状态持久化

14. 集成（中）

• integrations-sentry - 迁移 Sentry 错误监控

15. 测试（低）

• testing-jest-config - 更新 Jest 配置
• testing-react-testing-library - RTL 的工作方式不变
• testing-server-components - 测试 Server Components
• testing-client-components - 测试 Client Components
• testing-async-components - 测试异步组件
• testing-mocking - 模拟 Next.js 模块
• testing-e2e-cypress - 为 Next.js 配置 Cypress
• testing-e2e-playwright - 为 Next.js 配置 Playwright
• testing-api-routes - 测试 API Route Handlers

16. 构建与部署（低）

• build-scripts - 更新构建脚本
• build-output - 了解构建输出
• build-standalone - 配置独立输出
• build-static-export - 配置静态导出
• build-bundle-analysis - 分析包大小
• build-vercel - 部署到 Vercel
• build-docker - 配置 Docker 部署

17. 常见陷阱（高优先级）

• gotchas-window-undefined - 在 SSR 中处理 window/document
• gotchas-hydration-mismatch - 修复水合不匹配问题
• gotchas-use-effect-timing - 理解 Next.js 中的 useEffect
• gotchas-router-ready - 检查 router.isReady，以获取查询参数
• gotchas-dynamic-imports - 正确使用 next/dynamic
• gotchas-api-routes-edge - Edge 与 Node.js 运行时的区别
• gotchas-middleware - 中间件在 edge 上运行
• gotchas-static-generation - 静态渲染与动态渲染
• gotchas-redirect - 正确处理重定向
• gotchas-headers - 设置响应头
• gotchas-cookies - 在 RSC 中处理 Cookie
• gotchas-turbopack - 处理 Turbopack 兼容性问题
• gotchas-empty-modules - 修复 isolatedModules 的空模块导出问题
• gotchas-nullish-coalescing - 修复空值合并运算符的运行时错误
• gotchas-react19-class-components - 修复 React 19 类组件的 this 绑定
• gotchas-react19-ref-prop - 处理 React 19 ref 属性变更
• gotchas-websocket-optional-deps - 处理 WebSocket 原生依赖打包
• gotchas-auth-race-conditions - 防范身份验证/API 竞态条件
• gotchas-auth-state-gating - 检查角色前等待身份验证状态
• gotchas-configuration-idempotency - 使用 useRef 确保配置具有幂等性
• gotchas-hydration-nested-interactive - 避免嵌套交互元素
• gotchas-router-push-timing - 绝不要在渲染期间调用 router.push
• gotchas-infinite-rerender - 防止无限重新渲染循环
• gotchas-provider-hierarchy - 正确配置 Provider 层级

迁移前检查清单

开始迁移前，扫描代码库，查找需要特殊处理的模式：

# Check for WebSocket libraries (needs webpack fallback config)
grep -E "(socket\.io|\"ws\")" package.json

# Check for SCSS :export syntax (may need --webpack flag)
grep -r ":export" --include="*.scss" src/

# Check for SVG ReactComponent imports (needs SVGR config)
grep -r "ReactComponent" --include="*.ts" --include="*.tsx" src/

# List all REACT_APP_ environment variables
grep -roh "REACT_APP_[A-Z_]*" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" src/ | sort -u

# Check for Redux extraReducers using object notation (must convert to builder pattern for RTK v2)
grep -r "extraReducers:" --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" src/

# Check for /app/ paths that need updating if using (app) route group
grep -rE "(href|to|push|replace|redirect).*['\"]\/app\/" --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" src/

扫描结果与规则映射：

扫描结果	要阅读的规则
package.json 中包含 socket.io 或 ws	gotchas-websocket-optional-deps, setup-next-config
SCSS 文件中包含 :export	gotchas-turbopack
ReactComponent SVG 导入	assets-static-imports
找到 REACT_APP_ 变量	env-prefix-change
找到 extraReducers:	state-redux（需要 RTK v2 builder 回调）
导航中包含 /app/ 路径	routing-route-groups（更新路由组路径）

使用方法

阅读各个规则文件，了解详细说明和代码示例：

rules/setup-initial-structure.md
rules/routing-basic-pages.md
rules/data-useeffect-to-rsc.md

每个规则文件都包含：

• 迁移步骤的简要说明
• CRA 的“迁移前”代码示例
• Next.js 的“迁移后”代码示例
• 补充背景信息和常见陷阱

迁移顺序

为获得最佳效果，请按以下顺序迁移：

1. 设置 - 初始化 Next.js 项目结构
2. 路由 - 将 React Router 转换为基于文件的路由
3. 环境变量 - 更新环境变量前缀
4. 组件 - 在需要的位置添加 'use client' 指令
5. 数据获取 - 将 useEffect 转换为服务端模式
6. 样式 - 移动全局 CSS，配置 CSS-in-JS
7. 图像和字体 - 采用 Next.js 优化
8. SEO - 迁移到 Metadata API
9. API 路由 - 创建 Route Handlers
10. 测试 - 更新测试配置

迁移后验证清单

迁移后，请验证应用是否正常运行：

核心功能：

• npm run dev 无错误地启动 Next.js 开发服务器
• npm run build 成功完成
• npm start 运行生产构建
• 主应用正确渲染
• 所有路由均可访问

客户端功能：

• localStorage/sessionStorage 持久化正常
• 深色模式或主题切换正常，且设置会持久保存
• 客户端交互（表单、按钮、模态框）正常
• 浏览器前进/后退导航正常

路由（如适用）：

• 基于哈希的路由正常（例如，#room=abc,key=xyz）
• 可正确读取查询参数
• 动态路由使用正确的参数进行渲染
• 无效路由会显示 404 页面

实时功能（如适用）：

• WebSocket 连接成功建立
• 实时协作或更新功能正常
• 断开连接后可正常重新连接

集成（如适用）：

• 错误监控（Sentry）能够捕获错误
• 分析跟踪正常触发
• 第三方身份验证（OAuth、Firebase）正常
• 文件上传正常

PWA（如适用）：

• 服务工作线程成功注册（生产构建）
• 应用可安装
• 离线功能符合预期

性能：

• 控制台中没有水合不匹配警告
• 图片可正常加载并经过优化
• 字体加载时没有 FOUT/FOIT 问题
• 没有意外的控制台错误或警告