升级到 Docusaurus v3
本文档将帮助您将站点从 Docusaurus v2 升级到 Docusaurus v3。
Docusaurus v3 是一个新的主要版本，包含破坏性变更，需要您相应地调整站点。我们将在此过程中指导您，并提及一些可选的建议。
这不是完全重写，破坏性变更相对容易处理。最简单的站点最终只需更新其 npm 依赖项即可升级。
主要的破坏性变更是从 MDX v1 升级到 MDX v3。请阅读 MDX v2 和 MDX v3 发布说明以了解详情。MDX 现在将更严格地编译您的 Markdown 内容，并存在细微的差异。
在升级之前，我们建议为 Docusaurus v3 准备您的站点。有一些更改可以在 Docusaurus v2 下逐步处理。这将有助于减少最终升级到 Docusaurus v3 所需的工作。
对于复杂的站点，我们还建议设置视觉回归测试，这是确保站点保持视觉一致性的好方法。Docusaurus v3 主要升级依赖项，预计不会产生任何视觉变化。
查看 Docusaurus v3.0.0 的发布说明，并浏览拉取请求以获取有关此处提到的每个更改的其他有用信息和动机。
升级依赖项
升级到 Docusaurus v3 需要升级核心 Docusaurus 依赖项（@docusaurus/name），以及其他相关包。
Docusaurus v3 现在使用以下依赖项：
- Node.js v18.0+
- React v18.0+
- MDX v3.0+
- TypeScript v5.1+
- prism-react-renderer v2.0+
- react-live v4.0+
- remark-emoji v4.0+
- mermaid v10.4+
如果您的站点使用第三方社区插件和主题，您可能需要升级它们。
在尝试升级之前，请确保这些插件与 Docusaurus v3 兼容。
一个典型的 package.json 依赖项升级示例：
{
"dependencies": {
// 升级到 Docusaurus v3
- "@docusaurus/core": "2.4.3",
- "@docusaurus/preset-classic": "2.4.3",
+ "@docusaurus/core": "3.0.0",
+ "@docusaurus/preset-classic": "3.0.0",
// 升级到 MDX v3
- "@mdx-js/react": "^1.6.22",
+ "@mdx-js/react": "^3.0.0",
// 升级到 prism-react-renderer v2.0+
- "prism-react-renderer": "^1.3.5",
+ "prism-react-renderer": "^2.1.0",
// 升级到 React v18.0+
- "react": "^17.0.2",
- "react-dom": "^17.0.2"
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
},
"devDependencies": {
// 升级 Docusaurus 开发依赖项到 v3
- "@docusaurus/module-type-aliases": "2.4.3",
- "@docusaurus/types": "2.4.3"
+ "@docusaurus/module-type-aliases": "3.0.0",
+ "@docusaurus/types": "3.0.0"
}
"engines": {
// 要求 Node.js 18.0+
- "node": ">=16.14"
+ "node": ">=18.0"
}
}
对于 TypeScript 用户：
{
"devDependencies": {
// 将外部 TypeScript 配置包替换为新的官方包
- "@tsconfig/docusaurus": "^1.0.7",
+ "@docusaurus/tsconfig": "3.0.0",
// 升级 React 类型到 v18.0+
- "@types/react": "^17.0.69",
+ "@types/react": "^18.2.29",
// 升级 TypeScript 到 v5.1+
- "typescript": "~4.7.4"
+ "typescript": "~5.2.2"
}
}
升级 MDX
MDX 是 Docusaurus 的主要依赖项，负责将您的 .md 和 .mdx 文件编译为 React 组件。
从 MDX v1 到 MDX v3 的过渡是 Docusaurus v3 采用的主要挑战。大多数破坏性变更来自 MDX v2，而 MDX v3 是一个相对较小的版本。
在 Docusaurus v2 下成功编译的某些文档可能现在在 Docusaurus v3 下无法编译。
在您的站点上运行 npx docusaurus-mdx-checker，获取在 Docusaurus v3 下将无法编译的文件列表。
这个命令也是估算需要完成的工作量的好方法。请记住，大部分工作可以通过为 Docusaurus v3 准备您的内容提前执行。
其他文档可能也会渲染不同。
对于手动审查所有页面很复杂的大型站点，我们建议您设置视觉回归测试。
升级 MDX 包含 MDX v2 和 MDX v3 发布博客上记录的所有破坏性变更。大多数破坏性变更来自 MDX v2，而 MDX v3 是一个相对较小的版本。MDX v2 迁移指南中有一节关于更新 MDX 文件的内容将特别相关。还要确保阅读 MDX 故障排除页面，它可以帮助您解释常见的 MDX 错误消息。
请务必阅读我们更新的 MDX 和 React 文档页面。
使用 MDX 游乐场
MDX 游乐场是您的新好帮手。它允许您了解内容如何编译为 React 组件，并在隔离环境中排查编译或渲染问题。
为 Docusaurus 配置 MDX 游乐场选项
并排使用两个 MDX 游乐场，您很快就会注意到某些内容在 v2 中编译或渲染方式不同。
目标是重构您有问题的内容，使其在 MDX 的两个版本中都能正常工作。这样，当您升级到 Docusaurus v3 时，这些内容将开箱即用。
使用 MDX 检查器 CLI
我们提供了一个 docusaurus-mdx-checker CLI，可以轻松发现有问题的内容。在您的站点上运行此命令，以获取在 MDX v3 下将无法编译的文件列表。
npx docusaurus-mdx-checker
对于每个编译问题，CLI 将记录文件路径和要查看的行号。
使用此 CLI 估算使内容与 MDX v3 兼容所需的工作量。
此 CLI 是尽最大努力，并且仅报告编译错误。
它不会报告不产生错误但可能影响内容显示的细微编译更改。要捕获这些问题，我们建议使用视觉回归测试。
常见 MDX 问题
Docusaurus 无法详尽地记录 MDX 带来的所有更改。这是 MDX v2 和 MDX v3 迁移指南的责任。
然而，通过升级一些 Docusaurus 站点，我们注意到大多数问题都归结为我们为您记录的几个案例。
错误使用 {
{ 字符用于打开 JavaScript 表达式。现在，如果您在 {expression} 中放置的不是有效表达式，MDX 将失败。
{/* 这不是有效的 JavaScript 表达式 */}
{文字}
这将导致编译错误。要修复此问题，请确保在 {} 中放置有效的 JavaScript 表达式：
{/* 这是有效的 JavaScript 表达式 */}
{`文字`}
{someVariable}
{1 + 2}
标点符号和字母的组合
MDX v3 对标点符号和字母的组合更加严格。例如：
文。**文**
这可能会导致编译错误。这是因为：
- 前一个字符是字母
- 下一个字符是标点符号
"标点符号"包括非 ASCII 字符、括号、引号和一些符号，如 % 和 @。更严格地说，其 Unicode 类别以 P 开头的字符被视为标点符号。
升级建议
- 对于
{表达式，确保它们是有效的 JavaScript 表达式。 - 检查文本中的标点符号和字母组合，必要时重新格式化。
弃用的警告类型
Docusaurus v3 弃用了 :::caution 警告类型。请将 :::caution（黄色）重构为 :::warning（黄色）或 :::danger（红色）。
如果您想保留标题"caution"，可以重构为 :::warning[caution]（黄色）。
- :::caution 警告
+ :::warning 警告
内容
其他常见问题
代码块和表达式
MDX v3 对代码块和表达式的处理更加严格。确保：
- 代码块使用正确的语言标记
- 表达式正确闭合
- 避免在代码块中使用未转义的 Markdown 语法
导入和导出
检查您的 MDX 文件中的导入和导出语句。MDX v3 可能对它们的语法有更严格的要求。
使用 MDX 游乐场进行调试
利用 MDX 游乐场 来调试和理解编译过程。通过比较 v2 和 v3 的编译结果，您可以发现并修复潜在问题。
性能和包大小
MDX v3 的编译过程可能会影响构建性能和最终包的大小。建议：
- 监控构建时间
- 检查生成的 JavaScript 文件大小
- 在生产环境中进行全面测试
社区资源和支持
如果遇到复杂的迁移问题，不要犹豫寻求社区帮助。
结论
升级到 Docusaurus v3 是一个相对直接的过程，但需要仔细检查和测试。通过遵循本指南并利用提供的工具，您可以顺利地将站点迁移到最新版本。
记住，大多数迁移工作可以在 Docusaurus v2 下逐步完成，这将大大简化最终升级过程。