2026-03-19

742 字

3 分钟

Rspress 1.x 迁移到 2.x 注意事项

本文记录了将个人博客从 Rspress 1.x 迁移到 Rspress 2.x 的注意事项

一、依赖变更

1.1 核心包替换

Rspress 2 将多个包整合到 @rspress/core 中：

// 迁移前
{
  "dependencies": {
    "rspress": "^1.x",
    "@rspress/shared": "^1.x"
  }
}

// 迁移后
{
  "dependencies": {
    "@rspress/core": "^2.0.0"
  }
}

1.2 插件的 peerDependencies 更新

所有自定义插件的 package.json 需要更新：

{
  "peerDependencies": {
    "@rspress/core": "^2.0.0"
  }
}

1.3 添加 ESM 支持

Rspress 2 默认使用 ESM，需要在 package.json 中添加：

{
  "type": "module"
}

二、导入路径变更

2.1 运行时 API

// 迁移前
import { usePageData, useDark } from 'rspress/runtime'

// 迁移后
import { usePageData, useDark } from '@rspress/core/runtime'

2.2 主题组件

// 迁移前 (theme 目录下)
import Theme from 'rspress/theme'
import { Link } from '@rspress/theme-default'

// 迁移后 (theme 目录下)
import { Layout as BasicLayout } from '@rspress/core/theme-original'
import { Link } from '@rspress/core/theme-original'

2.3 配置定义

// 迁移前
import { defineConfig } from 'rspress/config'

// 迁移后
import { defineConfig } from '@rspress/core'

2.4 类型定义

// 迁移前
import type { RspressPlugin } from '@rspress/shared'
import { BaseRuntimePageInfo } from '@rspress/shared'

// 迁移后 - RspressPlugin 仍在 @rspress/core
import type { RspressPlugin } from '@rspress/core'
// BaseRuntimePageInfo 仍在 @rspress/shared
import { BaseRuntimePageInfo } from '@rspress/shared'

三、主题导出方式修改

3.1 默认导出改为命名导出

// 迁移前
import Theme from 'rspress/theme'

const Layout = () => <Theme.Layout {...props} />

export default {
  ...Theme,
  Layout,
  HomeLayout,
}

export * from 'rspress/theme'

// 迁移后
import { Layout as BasicLayout } from '@rspress/core/theme-original'

const Layout = () => <BasicLayout {...props} />

export { Layout, HomeLayout }

export * from '@rspress/core/theme-original'

四、配置变更

4.1 移除 themeConfig 中的文本配置

Rspress 2 内置了多语言支持，移除了 themeConfig 中的文本配置：

// 迁移前
themeConfig: {
  outlineTitle: '目录',
  prevPageText: '旧一篇',
  nextPageText: '新一篇',
  lastUpdatedText: '最后编辑于',
  // ... 其他文本配置
}

// 迁移后 - 使用 i18nSource
themeConfig: {
  // 不再需要这些配置
},
i18nSource: {
  outlineTitle: {
    zh: '目录',
    en: 'On This Page',
  },
  prevPageText: {
    zh: '旧一篇',
    en: 'Previous',
  },
  // ... 其他文本配置
}

4.2 移除的选项

markdown.mdxRs - 不再支持，直接移除
builderPlugins - 移至 builderConfig.plugins

五、组件 API 变更

5.1 Helmet 改为 Head/Meta

Rspress 2 使用 @unhead/react 的 Head 和 Meta 组件：

// 迁移前
import { Helmet } from '@rspress/core/runtime'

<Helmet>
  <meta name="referrer" content="no-referrer-when-downgrade" />
</Helmet>

// 迁移后
import { Head } from '@rspress/core/runtime'

<Head>
  <meta name="referrer" content="no-referrer-when-downgrade" />
</Head>

5.2 usePageData 被弃用

拆分了 Hook usePageData, Rspress 2 推荐使用 useSite, usePage 和 useSite 替代 usePageData：

// 迁移前
import { usePageData } from '@rspress/core/runtime'
const { siteData, page } = usePageData()

// 迁移后
import { usePage, useSite } from '@rspress/core/runtime'
const page = usePage()
const { site: siteData } = useSite()

六、代码高亮变更

6.1 Prism 改为 Shiki

Rspress 2 默认使用 Shiki 进行代码高亮：

// 迁移前
markdown: {
  highlightLanguages: [['ejs', 'javascript']],
}

// 迁移后
markdown: {
  shiki: {
    langAlias: {
      ejs: 'javascript',
    },
  },
}

6.2 行高亮语法

V2 不再默认支持 {1,3-4} 行高亮语法，需要配置 transformer：

import { transformerCompatibleMetaHighlight } from '@rspress/core/shiki-transformers'

markdown: {
  shiki: {
    transformers: [transformerCompatibleMetaHighlight()],
  },
}

6.3 不支持的代码块语言

Shiki 不支持某些语言（如 math），需要使用 KaTeX 插件：

 $|A_1 \cup A_2|=|A_1|+|A_2|-|A_1 \cap A_2|$

$|A_1 \cup A_2|=|A_1|+|A_2|-|A_1 \cap A_2|$

七、插件

7.1 rspress-plugin-katex

原插件使用了 require，在 ESM 环境下会报错：

ReferenceError: require is not defined

临时解决方案：修改插件根目录/dist/index.js, 使用 createRequire：

import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
import { visit } from 'unist-util-visit';
import { createRequire } from 'module';
// ...
export default function rspressPluginKatex(options = {}) {
    const require = createRequire(import.meta.url);
    const katexCss = require.resolve('katex/dist/katex.min.css');
    // ...
}

7.2 使用 rsbuild-plugin-virtual-module

Rspress 2 推荐使用 rsbuild-plugin-virtual-module 替代原生的 addRuntimeModules：

import { pluginVirtualModule } from 'rsbuild-plugin-virtual-module'

export function pluginResolver(options: PluginOptions): RspressPlugin {
  return {
    name: 'plugin-resolver',
    beforeBuild(config, isProd) {
      config.builderConfig = config.builderConfig || {}
      config.builderConfig.plugins = [
        ...(config.builderConfig.plugins || []),
        pluginVirtualModule({
          virtualModules: {
            'virtual-post-data': () => `export const postInfos = ${JSON.stringify(postInfos)}`,
            'virtual-post-categories': () => `export const postCategories = ${JSON.stringify(getCategoriesArray())}`,
          },
        }),
      ]
    },
  }
}

参考资源

容斥原理的组合证明

#Rspress 1.x 迁移到 2.x 注意事项

#一、依赖变更

#1.1 核心包替换

#1.2 插件的 peerDependencies 更新

#1.3 添加 ESM 支持

#二、导入路径变更

#2.1 运行时 API

#2.2 主题组件

#2.3 配置定义

#2.4 类型定义

#三、主题导出方式修改

#3.1 默认导出改为命名导出

#四、配置变更

#4.1 移除 themeConfig 中的文本配置

#4.2 移除的选项

#五、组件 API 变更

#5.1 Helmet 改为 Head/Meta

#5.2 usePageData 被弃用

#六、代码高亮变更

#6.1 Prism 改为 Shiki

#6.2 行高亮语法

#6.3 不支持的代码块语言

#七、插件

#7.1 rspress-plugin-katex

#7.2 使用 rsbuild-plugin-virtual-module

#参考资源