约定式路由

Rspress 采用基于文件系统的路由机制，您的目录结构直接映射到 URL 路由。这种"约定优于配置"的方法消除了手动路由配置的需要，使项目结构直观且易于维护。

基本路由原则

文件到路由的映射

路由系统非常直观 - docs 目录中的每个 .md 或 .mdx 文件都会自动成为一个路由:

docs/
├── index.md                    -> /
├── getting-started.md          -> /getting-started
├── guide/
│   ├── index.md               -> /guide
│   ├── installation.md        -> /guide/installation
│   └── configuration.md       -> /guide/configuration
└── api/
    ├── index.md               -> /api
    ├── cli.md                 -> /api/cli
    └── config-options.md      -> /api/config-options

索引文件

名为 index.md 的文件作为目录索引页面,类似于 Web 服务器中的 index.html:

docs/
└── products/
    ├── index.md               -> /products (落地页)
    ├── laptop.md              -> /products/laptop
    └── phone.md               -> /products/phone

当用户访问 /products 时,他们将看到 products/index.md 的内容。

嵌套路由

创建深层次结构

您可以通过在子目录中组织文件来创建任意嵌套的路由结构:

docs/
└── documentation/
    ├── index.md               -> /documentation
    ├── basic/
    │   ├── index.md          -> /documentation/basic
    │   ├── syntax.md         -> /documentation/basic/syntax
    │   └── features.md       -> /documentation/basic/features
    └── advanced/
        ├── index.md          -> /documentation/advanced
        ├── customization.md  -> /documentation/advanced/customization
        └── plugins.md        -> /documentation/advanced/plugins

嵌套最佳实践

保持浅层: 限制嵌套到 3-4 层以获得更好的用户体验
逻辑分组: 将相关内容组织在一起
一致命名: 使用清晰、描述性的文件夹和文件名

✅ 好的做法:
docs/
└── guides/
    ├── getting-started.md
    ├── configuration.md
    └── deployment.md

❌ 过深:
docs/
└── guides/
    └── web/
        └── frontend/
            └── react/
                └── hooks/
                    └── use-effect.md

动态路由

基于参数的路由

虽然 Rspress 主要关注静态文档,但您可以使用查询参数和哈希片段处理类似动态的路由:

markdown

<!-- docs/user.md -->
# 用户资料

通过以下方式访问用户资料: `/user?id=123`
或使用哈希路由: `/user#john-doe`

自定义路由处理器

对于更复杂的路由需求,您可以使用带路由参数的 React 组件:

typescript

// rspress.config.ts
export default defineConfig({
  route: {
    // 自定义路由配置
    exclude: ['**/fragments/**', '**/_components/**'],
  },
});

路由配置

从路由中排除文件

有时您希望 docs 目录中的文件不成为路由:

typescript

// rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  root: 'docs',
  route: {
    // 从路由中排除特定模式
    exclude: [
      '**/fragments/**',      // 排除 fragments 目录
      '**/_*.md',             // 排除以 _ 开头的文件
      '**/README.md',         // 排除 README 文件
      '**/.temp/**',          // 排除临时文件
    ],
  },
});

包含特定扩展名

默认情况下,Rspress 处理 .md 和 .mdx 文件。您可以自定义:

typescript

// rspress.config.ts
export default defineConfig({
  route: {
    extensions: ['.md', '.mdx', '.jsx', '.tsx'],
  },
});

URL Slug 化

自动 Slug 生成

Rspress 自动将文件名转换为 URL 友好的 slug:

文件名                          → URL 路径
getting-started.md            → /getting-started
API Reference.md              → /api-reference
User Guide (2024).md          → /user-guide-2024
配置指南.md                    → /pei-zhi-zhi-nan

通过 Frontmatter 自定义 Slug

使用 frontmatter 覆盖自动 slug 生成:

markdown

---
slug: /custom-url-path
---

# 页面标题

此页面将在 `/custom-url-path` 而不是默认路径访问。

基于斜杠的路由

无论文件位置如何,创建自定义路由层次结构:

markdown

---
slug: /api/v2/authentication
---

# 认证指南

文件位置: `docs/auth-guide.md`
访问路径: `/api/v2/authentication`

链接导航

内部链接

使用相对或绝对路径进行内部导航:

markdown

<!-- 相对链接 -->
[配置指南](./configuration.md)
[返回上级](../index.md)

<!-- 绝对链接 -->
[首页](/)
[API 参考](/api)
[快速开始](/guide/getting-started)

<!-- 带哈希锚点 -->
[跳转到安装部分](/guide/getting-started#installation)

链接验证

Rspress 在构建期间验证内部链接:

bash

# 构建会警告断开的链接
npm run build

⚠ 警告: 检测到断开的链接
  源: /guide/getting-started.md
  目标: /guide/nonexistent-page.md

特殊路由行为

404 页面

通过添加 404.md 文件创建自定义 404 页面:

markdown

<!-- docs/404.md -->
---
title: 页面未找到
---

# 404 - 页面未找到

您要查找的页面不存在。

[返回首页](/)

重定向处理

在配置文件中配置重定向:

typescript

// rspress.config.ts
export default defineConfig({
  builderConfig: {
    html: {
      meta: {
        'http-equiv': 'refresh',
        content: '0; url=/new-location',
      },
    },
  },
});

或使用专用插件:

typescript

// rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  plugins: [
    // 自定义重定向插件
    {
      name: 'redirect-plugin',
      async routeGenerated(routes) {
        // 添加重定向逻辑
        routes.push({
          path: '/old-path',
          redirect: '/new-path',
        });
      },
    },
  ],
});

路由元数据

Frontmatter 配置

使用 frontmatter 控制路由行为:

markdown

---
title: 自定义页面标题
description: SEO 友好的描述
keywords: [rspress, routing, documentation]
slug: /custom-path
sidebar_position: 2
sidebar_label: 简短标签
---

# 页面内容

访问路由信息

在 MDX 组件中使用路由数据:

mdx

import { usePageData } from 'rspress/runtime';

export function RouteInfo() {
  const { page } = usePageData();

  return (
    <div>
      <p>当前路径: {page.routePath}</p>
      <p>页面标题: {page.title}</p>
    </div>
  );
}

<RouteInfo />

实践示例

示例 1: 文档网站结构

docs/
├── index.md                           # 首页: /
├── introduction.md                    # /introduction
├── quick-start.md                     # /quick-start
├── guides/
│   ├── index.md                      # /guides
│   ├── installation.md               # /guides/installation
│   ├── basic-usage.md                # /guides/basic-usage
│   └── advanced-features.md          # /guides/advanced-features
├── api-reference/
│   ├── index.md                      # /api-reference
│   ├── cli.md                        # /api-reference/cli
│   └── configuration.md              # /api-reference/configuration
└── examples/
    ├── index.md                      # /examples
    ├── basic-example.md              # /examples/basic-example
    └── advanced-example.md           # /examples/advanced-example

示例 2: 多版本文档

docs/
├── index.md                           # 最新版本首页
├── v1/
│   ├── index.md                      # /v1
│   ├── guide.md                      # /v1/guide
│   └── api.md                        # /v1/api
├── v2/
│   ├── index.md                      # /v2
│   ├── guide.md                      # /v2/guide
│   └── api.md                        # /v2/api
└── latest/                           # 当前版本的符号链接或副本
    ├── index.md                      # /latest
    ├── guide.md                      # /latest/guide
    └── api.md                        # /latest/api

示例 3: 博客风格结构

docs/
├── index.md                           # 博客首页
├── posts/
│   ├── 2024-01-15-first-post.md     # /posts/2024-01-15-first-post
│   ├── 2024-02-20-second-post.md    # /posts/2024-02-20-second-post
│   └── 2024-03-10-third-post.md     # /posts/2024-03-10-third-post
└── categories/
    ├── tutorials/
    │   └── index.md                  # /categories/tutorials
    └── updates/
        └── index.md                  # /categories/updates

故障排除

常见问题

路由未找到
- 检查文件扩展名 (.md 或 .mdx)
- 验证文件未在配置中排除
- 确保文件在 root 目录内
路由冲突
- 避免同一级别的同名文件
- 检查 frontmatter 中的重复自定义 slug
链接不工作
- 使用一致的路径格式 (带或不带尾部斜杠)
- 为清晰起见,优先使用绝对路径
- 在相对链接中包含文件扩展名

调试技巧

bash

# 启用详细日志
npm run dev -- --debug

# 检查生成的路由
# 路由在构建期间记录
npm run build

# 验证路由结构
tree docs/ -I 'node_modules|doc_build'

性能考虑

路由加载策略

Rspress 使用代码分割高效加载路由:

typescript

// 路由自动分割
// 每个页面只加载所需内容
- 首页:     homepage.js (50KB)
- 指南页面: guide.js (30KB 每个)
- API 页面: api.js (40KB)
- 共享代码: vendor.js (100KB)

优化大型路由树

对于拥有许多路由(100+)的站点:

使用排除模式减少路由生成时间
利用懒加载处理重型组件
考虑分页处理大列表

typescript

// rspress.config.ts
export default defineConfig({
  route: {
    exclude: ['**/old-versions/**', '**/deprecated/**'],
  },
});

下一步

现在您已经了解了 Rspress 的路由系统,您可以:

学习导航栏与侧边栏配置
探索自动导航生成
了解MDX 及 React 组件以创建动态内容

最佳实践

保持 URL 简短且具有描述性
使用 kebab-case 命名文件
保持一致的目录结构
在部署前测试所有内部链接

了解更多

约定式路由 ​

基本路由原则 ​

文件到路由的映射 ​

索引文件 ​

嵌套路由 ​

创建深层次结构 ​

嵌套最佳实践 ​

动态路由 ​

基于参数的路由 ​

自定义路由处理器 ​

路由配置 ​

从路由中排除文件 ​

包含特定扩展名 ​

URL Slug 化 ​

自动 Slug 生成 ​

通过 Frontmatter 自定义 Slug ​

基于斜杠的路由 ​

链接导航 ​

内部链接 ​

链接验证 ​

特殊路由行为 ​

404 页面 ​

重定向处理 ​

路由元数据 ​

Frontmatter 配置 ​

访问路由信息 ​

实践示例 ​

示例 1: 文档网站结构 ​

示例 2: 多版本文档 ​

示例 3: 博客风格结构 ​

故障排除 ​

常见问题 ​

调试技巧 ​

性能考虑 ​

路由加载策略 ​

优化大型路由树 ​

下一步 ​

约定式路由

基本路由原则

文件到路由的映射

索引文件

嵌套路由

创建深层次结构

嵌套最佳实践

动态路由

基于参数的路由

自定义路由处理器

路由配置

从路由中排除文件

包含特定扩展名

URL Slug 化

自动 Slug 生成

通过 Frontmatter 自定义 Slug

基于斜杠的路由

链接导航

内部链接

链接验证

特殊路由行为

404 页面

重定向处理

路由元数据

Frontmatter 配置

访问路由信息

实践示例

示例 1: 文档网站结构

示例 2: 多版本文档

示例 3: 博客风格结构

故障排除

常见问题

调试技巧

性能考虑

路由加载策略

优化大型路由树

下一步