2026 年 11 月 2 日

Rspress 2.1.0 发布公告

Rspress 2.1.0 已正式发布，主要更新包括：

SSG-MD 默认启用：默认生成 llms.txt 和页面 Markdown，无需单独配置。
新增 WebMCP 工具：浏览器智能体可以直接查询、读取和导航文档。
内置 sitemap，默认启用 cleanUrls 和锚点检查。
路由迁移到 React Router Data 模式，支持滚动位置恢复，新增页面加载错误页。

SSG-MD 默认启用

SSG-MD 可以将 MDX 和 React 组件渲染为 Markdown，供 Agent 读取。

Rspress 官网已在 AFDocs 评测中获得 100/100 满分。从 Rspress 2.1.0 开始，SSG-MD 默认启用，无需再单独设置 llms: true。

执行生产构建后，除了 HTML 页面，还会生成：

doc_build/
├── llms.txt           # 文档索引，供 Agent 按需查阅
├── llms-full.txt      # 完整文档内容
└── guide/
    ├── getting-started.html
    └── getting-started.md

在怎样构建一个 Agent-friendly 的网站一文中，我们介绍了如何结合 SSG-MD、llms.txt 和 Markdown 内容协商，让 Agent 发现和读取文档。

内置 WebMCP 工具

WebMCP 允许网站向浏览器智能体提供工具。Rspress 2.1.0 默认启用以下六个文档工具：

工具	用途
`rspress_get_site_info`	获取站点信息、语言、版本、导航和当前侧边栏
`rspress_list_pages`	按语言、版本和关键词筛选页面列表
`rspress_get_page`	无需跳转，读取指定页面的信息、目录和 SSG-MD 文档（随 SSG-MD 一同启用）
`rspress_get_current_page`	读取当前页面的信息、目录和 SSG-MD 文档（随 SSG-MD 一同启用）
`rspress_search_docs`	搜索当前语言和版本的本地文档索引
`rspress_navigate`	跳转到站内页面，加载完成后返回页面信息

你也可以通过新增的 useWebMcp Hook，为自己的组件注册工具：

import { usePage, useWebMcp } from '@rspress/core/runtime';

export function PageTitleTool() {
  const { page } = usePage();

  useWebMcp({
    name: 'my_site_page_title',
    description: 'Get the current page title',
    annotations: { readOnlyHint: true },
    execute: () => ({ title: page.title }),
  });

  return null;
}

工具在组件挂载时注册，卸载时移除。全站工具可以注册在布局组件中，页面专属工具则注册在对应页面中。

WebMCP 仍是实验性浏览器 API，需要浏览器启用 document.modelContext，并通过 HTTPS 或 localhost 访问站点。不支持 WebMCP 的浏览器可正常阅读文档。

设置 webMcp: false 可以关闭内置工具，不影响 useWebMcp 注册的自定义工具。

内置 sitemap

Rspress 2.1.0 内置 sitemap 生成功能，生产构建默认生成 sitemap.xml，无需安装 @rspress/plugin-sitemap。

通过 siteOrigin 设置部署域名，base 设置部署子路径，生成的 sitemap 将包含完整 URL：

rspress.config.ts

import { defineConfig } from '@rspress/core';

export default defineConfig({
  siteOrigin: 'https://example.com',
  base: '/docs/',
});

通过顶层 sitemap 配置，可以设置页面优先级、更新频率和单页条目。已有项目可以用它替换 @rspress/plugin-sitemap。

即使设置了 ssg: false，仍会生成 sitemap。如果站点通过其他方式生成 sitemap，可设置 sitemap: false 关闭内置生成。

cleanUrls 默认启用

route.cleanUrls 的默认值从 false 改为 true。站内生成的普通页面链接将省略 .html 后缀，例如从 /guide/getting-started.html 改为 /guide/getting-started。

托管平台需要支持访问 /foo 时直接返回 /foo.html。如果不支持，或需要保留 .html 后缀，可设置 route.cleanUrls: false。

锚点检查默认启用

markdown.link.checkAnchors 的默认值从 false 改为 true。Rspress 会检查站内链接指向的章节是否存在，帮助发现修改标题后遗留的无效链接，例如 /guide/config#old-heading。

检查范围包括当前页面、相对路径和绝对路径的站内 Markdown / MDX 链接，不检查外部 URL。动态生成等无法静态识别的锚点可通过 markdown.link.checkAnchors.excludes 排除，也可设置 checkAnchors: false 关闭检查。

路由迁移到 React Router data 模式

Rspress 现在使用 React Router Data 模式。点击默认主题链接或调用 useNavigate() 时，会先加载目标页面的数据和代码，再切换地址和页面内容。加载期间保留当前页面。

在 React Router 7 下，useNavigate() 和 useLinkNavigate() 返回的导航函数都支持 await，可以等待导航完成。

新增 ErrorLayout 错误页。页面加载或渲染失败时，读者可以重新加载或返回首页，开发环境下还会显示错误详情。自定义主题可以替换 ErrorLayout。

支持滚动位置恢复

浏览器前进、后退或刷新页面时，Rspress 会恢复之前的滚动位置。例如，读到长文中部，跳转到另一页后再返回，可以继续从原来的位置阅读。锚点跳转也由 React Router 处理。

升级检查清单

将 @rspress/core 和项目中使用的官方插件一并升级，例如：

package.json

{
  "devDependencies": {
    "@rspress/core": "~2.1.0",
    "@rspress/plugin-preview": "~2.1.0",
    "@rspress/plugin-twoslash": "~2.1.0"
  }
}

检查 SSG-MD 的服务端渲染兼容性。需要浏览器环境的内容可用 BrowserOnly 包裹。ssg: false 不会关闭 SSG-MD；完全不支持服务端渲染的站点，需要同时设置 ssg: false 和 llms: false。
检查 sitemap 配置。已有项目可用内置 sitemap 替换 @rspress/plugin-sitemap；如果通过其他方式生成站点地图，可设置 sitemap: false。
确认部署平台支持无 .html 后缀的 URL，例如访问 /foo 时直接返回 /foo.html。如需保留原有链接格式，可设置 route.cleanUrls: false。
执行生产构建，修复发现的无效锚点。动态生成的锚点可通过 markdown.link.checkAnchors.excludes 排除，也可设置 checkAnchors: false 关闭检查。

完整更新见 v2.1.0 Release Notes。

感谢所有参与这个版本的贡献者！欢迎通过 GitHub 分享反馈，也欢迎在 Discord 与我们交流。

#Rspress 2.1.0 发布公告

#SSG-MD 默认启用

#内置 WebMCP 工具

#内置 sitemap

#cleanUrls 默认启用

#锚点检查默认启用

#路由迁移到 React Router data 模式

#支持滚动位置恢复

#升级检查清单