React 19发布已经有一段时间了，带来了很多令人兴奋的新特性，比如Actions、use() hook、useOptimistic、useFormStatus、文档元数据API、资源预加载等。这些新特性能大大提升开发体验和应用性能。

但很多开发者在升级到React 19或者新建React 19项目的时候，会遇到各种配置问题。比如构建工具怎么选，TypeScript怎么配置，ESLint和Prettier怎么搭，状态管理用什么，路由怎么配，性能怎么优化等等。

这篇文章，我想详细讲解一下React 19项目的完整配置方案。从项目初始化、构建工具配置、代码规范、状态管理、路由配置到性能优化、测试配置、部署上线，帮你搭建一个规范、高效、可维护的React 19项目。不管你是刚开始学React的新手，还是有经验的开发者，都能从这篇文章中找到有用的内容。

项目初始化：选对构建工具

第一步是项目初始化，选对构建工具是关键。

在React 19时代，最推荐的构建工具是Vite。Vite是新一代的前端构建工具，基于原生ES模块，开发服务器启动极快，热更新也很快，比Create React App（CRA）体验好很多。而且Vite对React 19的支持很好，配置简单，插件丰富。

用Vite创建React 19项目很简单，运行以下命令：

npm create vite@latest my-react-app -- --template react-ts

这个命令会创建一个基于Vite + React 19 + TypeScript的项目。如果你不用TypeScript，把react-ts改成react就可以了。但我强烈推荐用TypeScript，类型安全能大大提升代码质量和开发体验。

除了Vite，还有其他选择。比如Next.js，如果你需要服务端渲染（SSR）、静态站点生成（SSG）、API路由等功能，Next.js是很好的选择。Next.js 15已经支持React 19，而且配置更简单，很多功能开箱即用。如果你做的是需要SEO的内容站点或者复杂的全栈应用，推荐用Next.js。

还有Remix，也是一个不错的全栈React框架，对Web标准的支持很好，嵌套路由、表单处理等功能很强大。不过Remix现在已经和React Router合并了，未来的发展值得关注。

如果你是做组件库或者工具库，可以用Rollup或者tsup来构建，它们对库的构建支持更好，能输出多种模块格式。

总结一下：普通单页应用用Vite，需要SSR/SSG用Next.js，做库用Rollup或tsup。

TypeScript配置：类型安全是基础

创建好项目之后，接下来是TypeScript配置。React 19对TypeScript的支持很好，推荐用严格模式。

Vite创建的项目已经自带了tsconfig.json，但默认的配置可能不够严格。建议做以下调整：

第一，开启严格模式。把strict设为true，这会启用所有严格类型检查，包括noImplicitAny、strictNullChecks、strictFunctionTypes等。严格模式能帮你在编译阶段发现很多潜在的bug，大大提升代码质量。

第二，配置路径别名。在大型项目中，相对路径会很深，比如../../../../components，很不优雅。可以配置路径别名，比如@指向src目录，这样导入组件就可以写成import Button from '@/components/Button'。配置方法是在tsconfig.json的compilerOptions里加baseUrl和paths：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

同时，Vite那边也要配置对应的resolve.alias，否则构建的时候会找不到路径。

第三，配置jsx为react-jsx。React 17之后，JSX转换不需要导入React了，用新的JSX转换即可。在tsconfig.json里设置"jsx": "react-jsx"，这样就不用在每个文件里写import React from 'react'了。

第四，配置moduleResolution为bundler。这是TypeScript 5.0新增的模块解析策略，专门针对Vite、Webpack等打包工具优化，能更好地支持package.json的exports字段，类型解析更准确。

第五，配置noUnusedLocals和noUnusedParameters。这两个选项会检查未使用的变量和参数，帮你清理无用代码，保持代码整洁。

一个比较完善的tsconfig.json大概是这样的：

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

代码规范：ESLint + Prettier

代码规范是项目可维护性的基础。React 19项目推荐用ESLint做代码检查，Prettier做代码格式化。

Vite创建的项目已经自带了ESLint配置，但比较基础。建议做以下增强：

第一，安装必要的ESLint插件。包括eslint-plugin-react（React规则）、eslint-plugin-react-hooks（Hooks规则）、eslint-plugin-react-refresh（React Refresh规则）、@typescript-eslint/eslint-plugin（TypeScript规则）等。

第二，配置React 19的新规则。React 19有一些新的最佳实践，比如不要在effect里直接写异步函数，要用use() hook处理Promise等。ESLint插件会检查这些，帮你写出更符合React 19风格的代码。

第三，配置Prettier。Prettier负责代码格式化，比如缩进、引号、分号、换行等。和ESLint配合使用，ESLint负责代码质量检查，Prettier负责格式统一。要注意解决两者的冲突，用eslint-config-prettier关闭ESLint中与Prettier冲突的规则。

第四，配置保存时自动格式化。在VS Code里安装ESLint和Prettier插件，配置保存时自动修复和格式化，这样写代码的时候就能自动规范格式，不用手动调整。

第五，配置pre-commit钩子。用husky和lint-staged，在提交代码的时候自动运行ESLint和Prettier，确保提交的代码都是符合规范的。这样即使团队里有人不注意代码规范，提交的时候也会被自动修复。

一个完善的代码规范配置，能让团队的代码风格统一，减少code review的时间，提升代码质量和开发效率。

状态管理：选择适合你的方案

状态管理是React项目的核心问题之一。React 19时代，状态管理的选择很多，要根据项目的复杂度来选。

对于简单的项目，React自带的useState和useReducer就够了。不需要引入额外的状态管理库，保持项目简单。React 19的useReducer也有一些改进，用起来更方便。

对于中等复杂度的项目，推荐用Zustand。Zustand是一个轻量级的状态管理库，API简洁，学习成本低，性能好，没有Redux那么多样板代码。而且Zustand对React 19的支持很好，配合新特性使用很顺畅。

Zustand的用法很简单：

import { create } from 'zustand'

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}))

然后在组件里用：

const count = useStore((state) => state.count)
const increment = useStore((state) => state.increment)

对于大型复杂项目，Redux Toolkit还是一个不错的选择。Redux Toolkit是Redux的官方推荐写法，大大简化了Redux的使用，解决了传统Redux样板代码多的问题。而且Redux的生态很完善，中间件丰富，适合大型团队协作。

还有Jotai，原子化的状态管理库，思路和Recoil类似，但更轻量，性能更好。Jotai的原子化模型很适合复杂的状态依赖场景。

对于服务端状态，推荐用React Query（TanStack Query）。React Query专门处理服务端状态，比如数据获取、缓存、重试、失效等，能大大减少数据获取的样板代码，提升用户体验。React 19的use() hook也可以和React Query配合使用，处理异步数据更优雅。

总结一下：简单项目用useState/useReducer，中等项目用Zustand，大型项目用Redux Toolkit，服务端状态用React Query。不要盲目追求复杂的状态管理方案，适合项目的才是最好的。

路由配置：React Router v7

路由是单页应用的核心。React 19时代，推荐用React Router v7。

React Router v7是React Router和Remix合并后的新版本，带来了很多改进。比如嵌套路由、加载器、动作、表单处理等，功能更强大，也更符合Web标准。

React Router v7的配置方式有两种：基于配置的路由和基于组件的路由。

基于配置的路由，用createBrowserRouter创建路由表，然后用RouterProvider渲染。这种方式更清晰，适合大型项目，路由结构一目了然：

const router = createBrowserRouter([
  {
    path: '/',
    element: <Layout />,
    children: [
      { index: true, element: <Home /> },
      { path: 'about', element: <About /> },
      { path: 'users/:id', element: <User /> },
    ],
  },
])

基于组件的路由，用BrowserRouter、Routes、Route组件来配置，更符合React的声明式风格，适合中小型项目：

<BrowserRouter>
  <Routes>
    <Route path="/" element={<Layout />}>
      <Route index element={<Home />} />
      <Route path="about" element={<About />} />
    </Route>
  </Routes>
</BrowserRouter>

React Router v7的加载器（loader）和动作（action）是很强大的功能。加载器在路由渲染之前获取数据，动作处理表单提交和数据变更，这样数据获取和表单处理就不再需要在useEffect里写了，代码更清晰，用户体验也更好。这和React 19的Actions特性是契合的。

还有一个选择是TanStack Router，类型安全做得很好，路由参数、搜索参数都有完整的类型提示，适合TypeScript项目。不过生态还不如React Router成熟。

样式方案：CSS-in-JS还是CSS Modules

样式方案也是React项目需要考虑的问题。React 19时代，有几种主流选择。

第一种是CSS Modules。CSS Modules是Vite默认支持的，简单直接，样式局部作用域，不会冲突。写法就是普通的CSS，学习成本低，性能也好。对于大多数项目，CSS Modules就够了。

第二种是Tailwind CSS。这几年特别流行的原子化CSS框架，用工具类来写样式，不用写自定义CSS，开发速度快，样式一致性好。而且Tailwind v4对构建工具的支持更好，和Vite配合很顺畅。如果团队接受原子化CSS的写法，Tailwind是很好的选择。

第三种是CSS-in-JS，比如styled-components、Emotion。CSS-in-JS把样式写在JS里，样式和组件在一起，动态样式处理方便。但CSS-in-JS有运行时开销，性能不如纯CSS，而且React 19的服务端组件对CSS-in-JS的支持不太好。如果不是特别需要动态样式，不太推荐用CSS-in-JS。

第四种是原生CSS变量。现在浏览器对CSS变量的支持很好，可以用CSS变量来实现主题切换、动态样式等功能，性能好，没有运行时开销。

我的建议是：普通项目用CSS Modules，追求开发速度用Tailwind CSS，需要复杂动态样式再考虑CSS-in-JS。不要为了用而用，选择最适合项目和团队的方案。

性能优化：让应用跑得更快

性能优化是React项目永恒的话题。React 19带来了很多性能优化的新特性，要善加利用。

第一，善用React 19的新特性。比如useOptimistic，可以在异步操作完成之前乐观地更新UI，提升用户体验。useFormStatus可以获取表单提交的状态，方便显示加载状态。use() hook可以在渲染中读取Promise和Context，处理异步数据更优雅，减少loading状态。

第二，代码分割。用React.lazy和Suspense做路由级别的代码分割，只加载当前路由需要的代码，减少首屏加载时间。Vite会自动把分割的代码打包成单独的chunk，按需加载。

第三，组件懒加载。对于不常用的组件，比如弹窗、抽屉、复杂的图表，可以用React.lazy懒加载，需要的时候再加载，减少首屏的JS体积。

第四，虚拟列表。对于长列表，比如聊天记录、数据表格，用虚拟列表（react-window或react-virtuoso）只渲染可视区域的元素，大大减少DOM节点数量，提升渲染性能。

第五，记忆化。用useMemo和useCallback缓存计算结果和函数引用，避免不必要的重渲染。但不要滥用记忆化，因为记忆化本身也有开销，只在确实有性能问题的时候用。React 19的编译器（React Compiler）未来会自动处理记忆化，到时候就不用手动写useMemo和useCallback了。

第六，图片优化。用next/image或者vite-plugin-image-optimizer等工具，对图片进行压缩、格式转换、懒加载，减少图片的加载时间。React 19也内置了图片预加载的API，可以提前加载关键图片。

第七，分析打包体积。用rollup-plugin-visualizer分析打包后的chunk体积，找出大的依赖，考虑替换成更轻量的库，或者按需加载。比如lodash可以用lodash-es按需导入，moment.js可以用dayjs替代。

测试配置：保证代码质量

测试是项目质量的保障。React 19项目推荐用Vitest做单元测试，Testing Library做组件测试，Playwright做端到端测试。

Vitest是Vite生态的测试框架，和Vite的配置复用，启动快，支持HMR，比Jest体验更好。而且对React 19的支持很好。

Testing Library是React组件测试的标准库，鼓励从用户的角度测试组件，而不是测试实现细节，这样测试更稳定，更有价值。

Playwright是微软出的端到端测试框架，支持多浏览器，API简洁，自动等待，测试稳定。比Cypress更现代，更适合现代Web应用。

测试配置的建议：单元测试覆盖工具函数和hooks，组件测试覆盖关键组件的交互，端到端测试覆盖核心业务流程。不要追求100%的测试覆盖率，重点测试关键路径和容易出bug的地方。

部署上线：让用户访问到

最后是部署上线。React 19项目部署有几种方式。

第一种是静态部署。把Vite构建出来的dist目录部署到静态托管服务，比如Vercel、Netlify、阿里云OSS、腾讯云COS等。静态部署简单、便宜、性能好，适合纯前端的单页应用。需要注意配置SPA的回退路由，所有路径都回退到index.html，否则刷新页面会404。

第二种是Node.js服务部署。如果用了Next.js或者有SSR需求，需要部署到Node.js服务器上。可以用Docker容器化部署，或者用PM2管理进程。Vercel和Netlify也支持Next.js的部署，配置很简单。

第三种是Docker部署。把应用打包成Docker镜像，部署到Kubernetes或者其他容器平台，适合大型项目和企业级应用，扩展性好，运维规范。

部署的时候要注意：配置gzip或brotli压缩，减少传输体积；配置CDN加速静态资源；配置缓存策略，合理利用浏览器缓存；配置环境变量，区分开发、测试、生产环境。

写在最后

React 19带来了很多新特性和改进，配置一个完善的React 19项目需要考虑很多方面。从构建工具、TypeScript、代码规范、状态管理、路由、样式到性能优化、测试、部署，每一个环节都很重要。

但也不要追求一步到位，项目是慢慢演进的。刚开始可以用最简单的配置，随着项目复杂度增加，再逐步引入更完善的方案。重要的是理解每个配置的作用和适用场景，根据项目的实际需求来选择，而不是盲目跟风。

React的生态很丰富，选择很多，这既是好事也是坏事。好事是总能找到适合你的方案，坏事是选择太多容易纠结。我的建议是：保持简单，只在需要的时候引入复杂度。能用React自带功能解决的，就不要引入额外的库；能用简单方案解决的，就不要用复杂方案。

最后用一句话来结束这篇文章："好的配置不是最复杂的，而是最适合项目的。"

愿每一个React开发者，都能搭建出高效、规范、可维护的项目。