包与结构

相关源文件

• .eslintignore
• .gitignore
• integration/package.json
• package.json
• packages/create-react-router/package.json
• packages/react-router-architect/package.json
• packages/react-router-cloudflare/package.json
• packages/react-router-dev/package.json
• packages/react-router-dom/CHANGELOG.md
• packages/react-router-dom/package.json
• packages/react-router-express/package.json
• packages/react-router-fs-routes/package.json
• packages/react-router-node/package.json
• packages/react-router-serve/package.json
• packages/react-router/CHANGELOG.md
• packages/react-router/__tests__/data-memory-router-test.tsx
• packages/react-router/index.ts
• packages/react-router/lib/components.tsx
• packages/react-router/lib/context.ts
• packages/react-router/lib/dom/lib.tsx
• packages/react-router/lib/hooks.tsx
• packages/react-router/package.json
• pnpm-lock.yaml

本文档提供了 React Router 包架构的概述，解释了生态系统中不同的包、它们之间的关系以及各自的用途。您将了解代码库的组织方式以及适用于不同环境的包。

有关核心路由概念的信息，请参阅 核心概念。

核心软件包

React Router 采用分层架构，其中两个主要包构成了该生态系统的基础。

react-router

react-router 包提供了核心的、与平台无关的路由功能。

• 路由匹配和导航逻辑
• 路由器状态管理
• 核心 hooks，如 useParams、useLocation、useNavigate
• 与路由相关的组件，如 Routes、Route 和 Outlet
• 数据加载/修改 API（loaders、actions、fetchers）

这是所有其他 React Router 包构建的基础。它被设计为与平台无关，因此可以跨不同的 JavaScript 环境使用。

来源：packages/react-router/package.json1-115 packages/react-router/index.ts1-366

react-router-dom

react-router-dom 包扩展了 react-router，提供了特定于 Web 浏览器的功能。

• 特定于 DOM 的路由器，如 BrowserRouter 和 HashRouter
• 特定于 DOM 的组件，如 Link、NavLink 和 Form
• 特定于 DOM 的 hooks，如 useLinkClickHandler 和 useSearchParams
• 支持 DOM 特定功能，如滚动恢复和视图转换

在大多数 Web 应用程序中，您将从 react-router-dom 导入，而不是直接从 react-router 导入。

来源：packages/react-router-dom/package.json1-82 packages/react-router/lib/dom/lib.tsx1-200

平台适配

React Router 为服务器端渲染在不同平台提供了多种特定于环境的适配器。

@react-router/node

Node.js 环境的基础适配器，提供：

• Node.js 特定请求/响应处理
• 服务器端渲染支持

来源：packages/react-router-node/package.json1-105

@react-router/express

Express 中间件集成，用于 React Router

• Express 特定的请求处理器
• 与 Express 路由集成

来源：packages/react-router-express/package.json1-84

@react-router/cloudflare

Cloudflare Workers 适配器

• Cloudflare Workers 请求处理
• Workers 运行时兼容性

来源：packages/react-router-cloudflare/package.json1-74

@react-router/architect

AWS Architect 集成

• AWS Lambda 函数处理器
• Architect 特定路由

来源：packages/react-router-architect/package.json1-87

@react-router/serve

生产应用服务器

• React Router 应用的独立服务器
• 基于 Express 构建

来源：packages/react-router-serve/package.json1-69

开发工具

React Router 还提供了一些开发工具，以帮助构建和维护应用程序。

@react-router/dev

开发工具和 Vite 插件

• 具有热模块重载的开发服务器
• 类型生成
• 路由编译和优化
• 支持预渲染静态路由

来源：packages/react-router-dev/package.json1-149

@react-router/fs-routes

基于文件系统的路由约定

• 根据文件结构约定生成路由
• 与 @react-router/dev 一起使用

来源：packages/react-router-fs-routes/package.json1-67

create-react-router

项目脚手架工具

• 创建新的 React Router 应用
• 设置项目结构和依赖项

来源：packages/create-react-router/package.json1-75

包依赖项和对等依赖项

React Router 包使用直接依赖项和对等依赖项的组合来管理关系。

包	依赖项	对等依赖项
react-router	cookie、set-cookie-parser、turbo-stream	react、react-dom (可选)
react-router-dom	react-router	react、react-dom
@react-router/node	@mjackson/node-fetch-server、source-map-support 等。	react-router、typescript (可选)
@react-router/express	@react-router/node	express、react-router、typescript (可选)
@react-router/dev	许多构建工具和 React Router 包	@react-router/serve (可选)、react-router、typescript (可选) 等。

请注意，许多包将 typescript 标记为可选的对等依赖项，这意味着 TypeScript 支持是可用的，但并非必需的。

来源：packages/react-router/package.json83-105 packages/react-router-dom/package.json60-74 packages/react-router-node/package.json71-92

react-router 的内部结构

核心的 react-router 包拥有一个组织良好的内部结构。

关键文件及其用途

• index.ts：集中并重新导出所有公共 API。
• lib/components.tsx：包含核心路由组件。
• lib/hooks.tsx：包含所有与路由相关的 React hooks。
• lib/context.ts：定义用于路由器状态的 React contexts。
• lib/router/：包含核心路由逻辑。
• lib/dom/：包含特定于 DOM 的实现。

来源：packages/react-router/index.ts1-366 packages/react-router/lib/context.ts1-204 packages/react-router/lib/hooks.tsx1-600 packages/react-router/lib/components.tsx1-500

包导出配置

React Router 包使用其 package.json 文件中的 exports 字段来定义模块的导入方式。此配置支持 CommonJS 和 ES 模块，以及 TypeScript 类型。

此配置使得

• 特定于 Node.js 的导入（带 module-sync 用于同步 ESM 导入）
• 标准 ESM 导入（带 .mjs 扩展名）
• CommonJS 导入（带 .js 扩展名）
• 每种格式的 TypeScript 类型定义

来源：packages/react-router/package.json21-64 packages/react-router-dom/package.json21-42 packages/react-router-node/package.json14-48

模块结构和导入流程

在 Web 应用程序中使用 React Router 时，导入流程通常如下所示：

这种结构允许你在 Web 应用程序中从 react-router-dom 导入所有内容，同时保持代码库中关注点的清晰分离。

来源：packages/react-router/index.ts1-100 packages/react-router-dom/CHANGELOG.md1-150

构建系统

React Router 使用现代构建系统，包括

• 用于 TypeScript 编译和打包的 tsup
• 用于高效增量构建的 wireit
• 输出包括：
  • CommonJS（.js）
  • ES 模块（.mjs）
  • TypeScript 声明文件（.d.ts 和 .d.mts）

每个包在其 package.json 的 wireit 字段中定义了构建配置。

根包还包含构建所有包的脚本。

来源：package.json1-130 packages/react-router/package.json65-82

选择合适的包

根据您的用例，您需要不同包的组合。

用例	必需的包
单页应用程序 (SPA)	react-router-dom
带 Node.js 的服务器端渲染 (SSR) 应用	react-router-dom, @react-router/node
Express.js SSR	react-router-dom, @react-router/express
Cloudflare Workers	react-router-dom, @react-router/cloudflare
使用 Vite 进行开发	react-router-dom, @react-router/dev

对于大多数 Web 应用程序，从 react-router-dom 开始就足够了，您可以根据需要添加平台适配器以进行服务器端渲染。

来源：packages/react-router-dom/package.json1-82 integration/package.json1-49

版本兼容性

React Router v7 要求：

• Node.js 20.0.0 或更高版本
• React 18 或更高版本

React Router 生态系统中的所有包都使用相同的版本号以确保兼容性。

来源：packages/react-router/package.json112-114 packages/react-router-dom/CHANGELOG.md100-134