快速入门

本指南将帮助您尽快熟悉运行 React Router 应用所需的基本配置。虽然有许多带有不同运行时、部署目标和数据库的入门模板，但我们将从零开始创建一个最基本的项目。

安装

如果您更喜欢初始化一个功能齐全的 React Router 项目，可以使用 create-react-router CLI 开始，并选择我们的任何一个模板。

npx create-react-router@latest

然而，本指南将解释 CLI 为设置您的项目所做的一切。您可以按照这些步骤操作，而不是使用 CLI。如果您是 React Router 的新手，我们建议您按照本指南来理解构成 React Router 应用的所有不同部分。

mkdir my-react-router-app
cd my-react-router-app
npm init -y

# install runtime dependencies
npm i react-router @react-router/node @react-router/serve isbot react react-dom

# install dev dependencies
npm i -D @react-router/dev vite

Vite 配置

touch vite.config.js

由于 React Router 使用 Vite，您需要提供一个带有 React Router Vite 插件的 Vite 配置。这是您需要的基本配置：

import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [reactRouter()],
});

根路由

mkdir app
touch app/root.jsx

app/root.jsx 是我们所说的“根路由”。它是您整个应用的根布局。以下是任何项目所需的基本元素集合：

import { Outlet, Scripts } from "react-router";

export default function App() {
  return (
    <html>
      <head>
        <link
          rel="icon"
          href="data:image/x-icon;base64,AA"
        />
      </head>
      <body>
        <h1>Hello world!</h1>
        <Outlet />
        <Scripts />
      </body>
    </html>
  );
}

附加路由

touch app/routes.js

app/routes.js 是您定义路由的地方。本指南侧重于让 React Router 应用运行起来的最小化设置，所以我们不需要定义任何路由，只需导出一个空数组即可。

export default [];

构建 React Router 应用需要 routes.js 文件的存在；如果您正在使用 React Router，我们假设您最终会需要进行一些路由操作。您可以在我们的路由指南中阅读有关定义路由的更多信息。

构建和运行

首先，您需要在 package.json 中将类型指定为 module，以满足 react-router 和未来 Vite 版本的 ES 模块要求。

npm pkg set type="module"

接下来为生产环境构建应用：

npx react-router build

现在您应该会看到一个 build 文件夹，其中包含一个 server 文件夹（您的应用的服务器版本）和一个 client 文件夹（浏览器版本），里面有一些构建产物。（这一切都是可配置的。）

👉 使用 react-router-serve 运行应用

现在您可以使用 react-router-serve 来运行您的应用：

npx react-router-serve build/server/index.js

您应该能够打开 https://:3000 并看到“hello world”页面。

除了 node_modules 中大量的代码外，我们的 React Router 应用只有四个文件：

├── app/
│   ├── root.jsx
│   └── routes.js
├── package.json
└── vite.config.js

自带服务器

由 react-router build 创建的 build/server 目录只是一个模块，您可以在 Express、Cloudflare Workers、Netlify、Vercel、Fastly、AWS、Deno、Azure、Fastify、Firebase 等任何服务器中运行它。

您也可以将 React Router 用作一个没有服务器的单页面应用。更多信息，请参阅我们的单页面应用指南。

如果您不关心设置自己的服务器，可以使用 react-router-serve。它是一个由 React Router 维护者维护的简单的基于 express 的服务器。然而，React Router 被特别设计为可以在任何 JavaScript 环境中运行，以便您掌控自己的技术栈。我们预计许多——如果不是大多数——生产应用都会有自己的服务器。

为了好玩，让我们停止使用 react-router-serve，改用 express。

👉 安装 Express、React Router Express 适配器和用于在生产模式下运行的 cross-env

npm i express @react-router/express cross-env

# not going to use this anymore
npm uninstall @react-router/serve

👉 创建一个 Express 服务器

touch server.js

import { createRequestHandler } from "@react-router/express";
import express from "express";

const app = express();
app.use(express.static("build/client"));

// notice that your app is "just a request handler"
app.use(
  createRequestHandler({
    // and the result of `react-router build` is "just a module"
    build: await import("./build/server/index.js"),
  }),
);

app.listen(3000, () => {
  console.log("App listening on https://:3000");
});

👉 使用 express 运行您的应用

node server.js

现在您拥有了自己的服务器，您可以使用服务器的任何工具来调试您的应用。例如，您可以使用 Node.js inspect 标志通过 Chrome DevTools 来检查您的应用。

node --inspect server.js

开发工作流

与其一直停止、重建和启动服务器，您可以在开发中使用Vite 的中间件模式来运行 React Router。这能让您通过 React Refresh (热模块替换) 和 React Router 热数据重载，即时反馈您应用中的更改。

首先，为了方便起见，在 package.json 中添加 dev 和 start 命令，它们将分别在开发和生产模式下运行您的服务器。

👉 在 package.json 中添加一个 "scripts" 条目

{
  "scripts": {
    "dev": "node ./server.js",
    "start": "cross-env NODE_ENV=production node ./server.js",
  },
  // ...
}

👉 将 Vite 开发中间件添加到您的服务器中

如果 process.env.NODE_ENV 设置为 "production"，Vite 中间件将不会被应用，在这种情况下，您仍然会像之前一样运行常规的构建输出。

import { createRequestHandler } from "@react-router/express";
import express from "express";

const app = express();

if (process.env.NODE_ENV === "production") {
  app.use(express.static("build/client"));
  app.use(
    createRequestHandler({
      build: await import("./build/server/index.js"),
    }),
  );
} else {
  const viteDevServer = await import("vite").then((vite) =>
    vite.createServer({
      server: { middlewareMode: true },
    }),
  );
  app.use(viteDevServer.middlewares);
  app.use(
    createRequestHandler({
      build: () =>
        viteDevServer.ssrLoadModule(
          "virtual:react-router/server-build",
        ),
    }),
  );
}

app.listen(3000, () => {
  console.log(`Server is running on https://:3000`);
});

👉 启动开发服务器

npm run dev

现在您可以即时反馈地开发您的应用。试着更改 root.jsx 中的文本，并观察更改立即出现！

控制服务器和浏览器入口

React Router 使用了一些默认的魔法文件，大多数应用不需要去管它们，但如果您想自定义 React Router 的服务器和浏览器入口点，您可以运行 react-router reveal，它们将被导出到您的项目中。

npx react-router reveal

Entry file entry.client created at app/entry.client.tsx.
Entry file entry.server created at app/entry.server.tsx.

摘要

恭喜，您可以将 React Router 添加到您的简历中了！总结一下，我们学到了：

React Router 框架模式将您的应用编译成两样东西：
- 一个请求处理器，您可以将其添加到您自己的 JavaScript 服务器中
- 一堆用于浏览器的静态资源，存放在您的公共目录中
您可以使用适配器自带服务器，部署到任何地方
您可以设置一个内置 HMR 的开发工作流

总的来说，React Router 有点“内脏外露”。它需要几分钟的样板代码，但现在您掌控了自己的技术栈。

接下来呢？

地址簿教程