从头开始构建 React 应用

深入研究

考虑使用框架

显示详情

¥Consider using a framework

从头开始是开始使用 React 的一种简单方法，但需要注意的一个主要权衡是，走这条路通常与构建自己的临时框架相同。随着你的需求不断发展，你可能需要解决更多类似框架的问题，而我们推荐的框架已经为这些问题提供了完善且支持的解决方案。

¥Starting from scratch is an easy way to get started using React, but a major tradeoff to be aware of is that going this route is often the same as building your own adhoc framework. As your requirements evolve, you may need to solve more framework-like problems that our recommended frameworks already have well developed and supported solutions for.

例如，如果将来你的应用需要支持服务器端渲染 (SSR)、静态站点生成 (SSG) 和/或 React 服务器组件 (RSC)，你将必须自行实现这些功能。同样，如果你想使用需要在框架级别集成的未来 React 功能，则必须自行实现。

¥For example, if in the future your app needs support for server-side rendering (SSR), static site generation (SSG), and/or React Server Components (RSC), you will have to implement those on your own. Similarly, future React features that require integrating at the framework level will have to be implemented on your own if you want to use them.

我们推荐的框架还可以帮助你构建性能更好的应用。例如，减少或消除网络请求的瀑布流可以带来更好的用户体验。当你构建玩具项目时，这可能不是高优先级，但如果你的应用获得用户，你可能希望提高其性能。

¥Our recommended frameworks also help you build better performing apps. For example, reducing or eliminating waterfalls from network requests makes for a better user experience. This might not be a high priority when you are building a toy project, but if your app gains users you may want to improve its performance.

走这条路也会使获得支持变得更加困难，因为你开发路由、数据获取和其他功能的方式将因你的情况而异。只有当你可以轻松地自己解决这些问题，或者你确信永远不需要这些功能时，才应选择此选项。

¥Going this route also makes it more difficult to get support, since the way you develop routing, data-fetching, and other features will be unique to your situation. You should only choose this option if you are comfortable tackling these problems on your own, or if you’re confident that you will never need these features.

有关推荐框架的列表，请查看 创建 React 应用。

¥For a list of recommended frameworks, check out Creating a React App.

步骤 1：安装构建工具

¥Step 1: Install a build tool

第一步是安装构建工具，如 vite、parcel 或 rsbuild。这些构建工具提供打包和运行源代码的功能，为本地开发提供开发服务器，并提供构建命令以将你的应用部署到生产服务器。

¥The first step is to install a build tool like vite, parcel, or rsbuild. These build tools provide features to package and run source code, provide a development server for local development and a build command to deploy your app to a production server.

Vite

Vite 是一个构建工具，旨在为现代 Web 项目提供更快、更精简的开发体验。

¥Vite is a build tool that aims to provide a faster and leaner development experience for modern web projects.

Vite 有自己的主见，并带有开箱即用的合理默认值。Vite 拥有丰富的插件生态系统，支持快速刷新、JSX、Babel/SWC 和其他常见功能。请参阅 Vite 的 React 插件 或 React SWC 插件 和 React SSR 示例项目 以开始使用。

¥Vite is opinionated and comes with sensible defaults out of the box. Vite has a rich ecosystem of plugins to support fast refresh, JSX, Babel/SWC, and other common features. See Vite’s React plugin or React SWC plugin and React SSR example project to get started.

Vite 已经在我们的 推荐的框架 之一中被用作构建工具：React Router。

¥Vite is already being used as a build tool in one of our recommended frameworks: React Router.

Parcel

Parcel 将出色的开箱即用开发体验与可扩展架构相结合，可将你的项目从入门级应用带入大规模生产应用。

¥Parcel combines a great out-of-the-box development experience with a scalable architecture that can take your project from just getting started to massive production applications.

Parcel 支持开箱即用的快速刷新、JSX、TypeScript、Flow 和样式。请参阅 Parcel 的 React 秘诀 以开始使用。

¥Parcel supports fast refresh, JSX, TypeScript, Flow, and styling out of the box. See Parcel’s React recipe to get started.

Rsbuild

Rsbuild 是一个由 Rspack 提供支持的构建工具，可为 React 应用提供无缝的开发体验。它带有精心调整的默认值和性能优化，可随时使用。

¥Rsbuild is an Rspack-powered build tool that provides a seamless development experience for React applications. It comes with carefully tuned defaults and performance optimizations ready to use.

Rsbuild 包含对 React 功能的内置支持，例如快速刷新、JSX、TypeScript 和样式。请参阅 Rsbuild 的 React 指南 以开始使用。

¥Rsbuild includes built-in support for React features like fast refresh, JSX, TypeScript, and styling. See Rsbuild’s React guide to get started.

步骤 2：构建常见应用模式

¥Step 2: Build Common Application Patterns

上面列出的构建工具从仅限客户端的单页应用 (SPA) 开始，但不包括针对路由、数据获取或样式等常见功能的任何进一步解决方案。

¥The build tools listed above start off with a client-only, single-page app (SPA), but don’t include any further solutions for common functionality like routing, data fetching, or styling.

React 生态系统包含许多针对这些问题的工具。我们列出了一些广泛用作起点的工具，但如果其他工具更适合你，请随意选择。

¥The React ecosystem includes many tools for these problems. We’ve listed a few that are widely used as a starting point, but feel free to choose other tools if those work better for you.

路由

¥Routing

路由决定了当用户访问特定 URL 时要显示哪些内容或页面。你需要设置路由以将 URL 映射到应用的不同部分。你还需要处理嵌套路由、路由参数和查询参数。路由可以在你的代码中配置，也可以根据你的组件文件夹和文件结构定义。

¥Routing determines what content or pages to display when a user visits a particular URL. You need to set up a router to map URLs to different parts of your app. You’ll also need to handle nested routes, route parameters, and query parameters. Routers can be configured within your code, or defined based on your component folder and file structures.

路由是现代应用的核心部分，通常与数据获取（包括预取整个页面的数据以加快加载速度）、代码拆分（以最小化客户端包大小）和页面渲染方法（决定如何生成每个页面）集成。

¥Routers are a core part of modern applications, and are usually integrated with data fetching (including prefetching data for a whole page for faster loading), code splitting (to minimize client bundle sizes), and page rendering approaches (to decide how each page gets generated).

我们建议使用：

¥We suggest using:

• React Router

• Tanstack Router

数据获取

¥Data Fetching

从服务器或其他数据源获取数据是大多数应用的关键部分。正确执行此操作需要处理加载状态、错误状态和缓存获取的数据，这可能很复杂。

¥Fetching data from a server or other data source is a key part of most applications. Doing this properly requires handling loading states, error states, and caching the fetched data, which can be complex.

专门构建的数据获取库为你完成获取和缓存数据的艰苦工作，让你专注于应用需要哪些数据以及如何显示它。这些库通常直接用于你的组件中，但也可以集成到路由加载器中以实现更快的预取和更好的性能，以及服务器渲染。

¥Purpose-built data fetching libraries do the hard work of fetching and caching the data for you, letting you focus on what data your app needs and how to display it. These libraries are typically used directly in your components, but can also be integrated into routing loaders for faster pre-fetching and better performance, and in server rendering as well.

请注意，直接在组件中获取数据可能会导致加载时间变慢，因为网络请求瀑布，因此我们建议尽可能在路由加载器或服务器上预取数据！这允许在显示页面时一次性获取页面的所有数据。

¥Note that fetching data directly in components can lead to slower loading times due to network request waterfalls, so we recommend prefetching data in router loaders or on the server as much as possible! This allows a page’s data to be fetched all at once as the page is being displayed.

如果你从大多数后端或 REST 样式 API 获取数据，我们建议使用：

¥If you’re fetching data from most backends or REST-style APIs, we suggest using:

• React 查询

  ¥React Query

• SWR

• RTK 查询

  ¥RTK Query

如果你从 GraphQL API 获取数据，我们建议使用：

¥If you’re fetching data from a GraphQL API, we suggest using:

• Apollo

• Relay

代码拆分

¥Code-splitting

代码拆分是将应用分解为可以按需加载的较小包的过程。随着每个新功能和额外依赖的增加，应用的代码大小都会增加。应用加载速度可能会变慢，因为需要先发送整个应用的所有代码才能使用。缓存、减少功能/依赖以及将一些代码移动到服务器上运行可以帮助缓解加载缓慢的问题，但它们是不完整的解决方案，如果过度使用可能会牺牲功能。

¥Code-splitting is the process of breaking your app into smaller bundles that can be loaded on demand. An app’s code size increases with every new feature and additional dependency. Apps can become slow to load because all of the code for the entire app needs to be sent before it can be used. Caching, reducing features/dependencies, and moving some code to run on the server can help mitigate slow loading but are incomplete solutions that can sacrifice functionality if overused.

同样，如果你依赖使用框架的应用来拆分代码，你可能会遇到加载速度比根本没有进行代码拆分时更慢的情况。例如，延迟加载 图表延迟发送渲染图表所需的代码，将图表代码与应用的其余部分分离。Parcel 支持使用 React.lazy 进行代码拆分。但是，如果图表在最初渲染后加载其数据，你现在需要等待两次。这是一个瀑布：而不是获取图表的数据并发送代码以同时渲染它，你必须等待每个步骤一个接一个地完成。

¥Similarly, if you rely on the apps using your framework to split the code, you might encounter situations where loading becomes slower than if no code splitting were happening at all. For example, lazily loading a chart delays sending the code needed to render the chart, splitting the chart code from the rest of the app. Parcel supports code splitting with React.lazy. However, if the chart loads its data after it has been initially rendered you are now waiting twice. This is a waterfall: rather than fetching the data for the chart and sending the code to render it simultaneously, you must wait for each step to complete one after the other.

按路由拆分代码，与打包和数据获取相结合，可以减少应用的初始加载时间以及应用最大可见内容的渲染时间（最大的 Contentful Paint）。

¥Splitting code by route, when integrated with bundling and data fetching, can reduce the initial load time of your app and the time it takes for the largest visible content of the app to render (Largest Contentful Paint).

有关代码拆分说明，请参阅你的构建工具文档：

¥For code-splitting instructions, see your build tool docs:

• Vite 构建优化

  ¥Vite build optimizations

• Parcel 代码拆分

  ¥Parcel code splitting

• Rsbuild 代码拆分

  ¥Rsbuild code splitting

提高应用性能

¥Improving Application Performance

由于你选择的构建工具仅支持单页应用 (SPA)，因此你需要实现其他 渲染模式，如服务器端渲染 (SSR)、静态站点生成 (SSG) 和/或 React 服务器组件 (RSC)。即使你最初不需要这些功能，将来也可能会有一些路由有益于 SSR、SSG 或 RSC。

¥Since the build tool you select only support single page apps (SPAs) you’ll need to implement other rendering patterns like server-side rendering (SSR), static site generation (SSG), and/or React Server Components (RSC). Even if you don’t need these features at first, in the future there may be some routes that would benefit SSR, SSG or RSC.

• 单页应用 (SPA) 加载单个 HTML 页面并在用户与应用交互时动态更新页面。SPA 更容易上手，但初始加载时间可能会更慢。SPA 是大多数构建工具的默认架构。

  ¥Single-page apps (SPA) load a single HTML page and dynamically updates the page as the user interacts with the app. SPAs are easier to get started with, but they can have slower initial load times. SPAs are the default architecture for most build tools.

• 流式服务器端渲染 (SSR) 在服务器上渲染页面并将完全渲染的页面发送到客户端。SSR 可以提高性能，但设置和维护起来可能比单页应用更复杂。随着流式传输的增加，SSR 的设置和维护会变得非常复杂。参见 Vite 的 SSR 指南。

  ¥Streaming Server-side rendering (SSR) renders a page on the server and sends the fully rendered page to the client. SSR can improve performance, but it can be more complex to set up and maintain than a single-page app. With the addition of streaming, SSR can be very complex to set up and maintain. See Vite’s SSR guide.

• 静态站点生成 (SSG) 在构建时为你的应用生成静态 HTML 文件。SSG 可以提高性能，但设置和维护起来可能比服务器端渲染更复杂。参见 Vite 的 SSG 指南。

  ¥Static site generation (SSG) generates static HTML files for your app at build time. SSG can improve performance, but it can be more complex to set up and maintain than server-side rendering. See Vite’s SSG guide.

• React Server Components (RSC) 允许你在单个 React 树中混合构建时、仅服务器和交互式组件。RSC 可以提高性能，但目前需要深厚的专业知识来设置和维护。参见 Parcel 的 RSC 示例。

  ¥React Server Components (RSC) lets you mix build-time, server-only, and interactive components in a single React tree. RSC can improve performance, but it currently requires deep expertise to set up and maintain. See Parcel’s RSC examples.

你的渲染策略需要与你的路由集成，以便使用你的框架构建的应用可以在每个路由级别选择渲染策略。这将启用不同的渲染策略，而无需重写整个应用。例如，你的应用的登录页面可能会受益于静态生成 (SSG)，而带有内容提要的页面可能在服务器端渲染时表现最佳。

¥Your rendering strategies need to integrate with your router so apps built with your framework can choose the rendering strategy on a per-route level. This will enable different rendering strategies without having to rewrite your whole app. For example, the landing page for your app might benefit from being statically generated (SSG), while a page with a content feed might perform best with server-side rendering.

对正确的路由使用正确的渲染策略可以减少加载第一个内容字节（第一个字节的时间）、渲染第一个内容（第一个 Contentful Paint）和渲染应用最大可见内容（最大的 Contentful Paint）所需的时间。

¥Using the right rendering strategy for the right routes can decrease the time it takes for the first byte of content to be loaded (Time to First Byte), the first piece of content to render (First Contentful Paint), and the largest visible content of the app to render (Largest Contentful Paint).

还有更多…

¥And more…

这些只是新应用从头开始构建时需要考虑的功能的几个示例。你会遇到的许多限制可能很难解决，因为每个问题都与其他问题相互关联，并且可能需要你在可能不熟悉的问题字段拥有深厚的专业知识。

¥These are just a few examples of the features a new app will need to consider when building from scratch. Many limitations you’ll hit can be difficult to solve as each problem is interconnected with the others and can require deep expertise in problem areas you may not be familiar with.

如果你不想自己解决这些问题，你可以使用提供这些开箱即用功能的 从框架开始。

¥If you don’t want to solve these problems on your own, you can get started with a framework that provides these features out of the box.