Docusaurus 3.8

2025年5月26日 ·11 分钟阅读

Sébastien Lorber

Docusaurus 维护者，《本周 React》编辑

我们很高兴地宣布 Docusaurus 3.8。

此版本提升了构建性能，包含了新功能，并引入了“未来标志”以帮助您的网站为 Docusaurus 4 做好准备。

升级很简单。我们遵循语义化版本控制，并且根据我们的发布流程，次要版本更新没有破坏性更改。

性能

此版本通过各种优化和两个新的 Docusaurus Faster 选项，持续提升我们的构建基础设施性能。

Docusaurus Faster

Docusaurus Faster 已在 Docusaurus v3.6 中引入，它允许你选择升级后的构建基础设施，并帮助你更快地构建站点。实验性标志可以单独开启，但我们建议使用此便捷快捷方式一次性全部开启：

const config = {
  future: {
    experimental_faster: true,
  },
};

提示

别忘了先安装 @docusaurus/faster 依赖！

持久缓存

在 #10931 中，我们启用了 Rspack 持久缓存。与 Webpack 持久缓存（已支持）类似，它可以在后续构建中大大加快 Docusaurus 应用程序的打包速度。

实际上，如果你第二次运行 docusaurus build，你的站点应该会构建得快得多。

此功能依赖于使用 Rspack 打包器，并且可以通过 rspackPersistentCache 标志开启：

const config = {
  future: {
    experimental_faster: {
      rspackBundler: true, // required flag
      rspackPersistentCache: true, // new flag
    },
  },
};

保留缓存

持久缓存需要跨构建保留 ./node_modules/.cache 文件夹。

Netlify 和 Vercel 等热门 CDN 会自动为你执行此操作。根据你的 CI 和部署管道，可能需要额外配置才能保留缓存。

结果：平均而言，你的站点在重新构建时的打包时间预计会快 ~2-5 倍 🔥。如果你禁用可选的 concatenateModule 优化，影响可能会更大。

工作线程

在 #10826 中，我们引入了一个 Node.js 工作线程池来运行静态站点生成代码。通过这种新策略，我们可以更好地利用所有可用的 CPU，减少静态站点生成时间，并遏制潜在的内存泄漏。

此功能可以通过 ssgWorkerThreads 标志开启，并且需要开启 v4.removeLegacyPostBuildHeadAttribute Future Flag。

const config = {
  future: {
    v4: {
      removeLegacyPostBuildHeadAttribute: true, // required
    },
    experimental_faster: {
      ssgWorkerThreads: true,
    },
  },
};

结果：平均而言，你的站点静态站点生成时间预计会快 ~2 倍 🔥。这是在 MacBook Pro M3 上测量的，结果可能因你的 CI 而异。

其他优化

我们发现并解决了几个主要瓶颈，包括：

在 #11007 中，我们优化了 macOS 用户的开发服务器启动时间。我们发现打开浏览器的代码使用了耗时的同步/阻塞调用，这阻止了打包器的工作。从现在开始，打包器和 macOS 浏览器打开将并行运行，从而为所有 macOS 用户带来更快的 docusaurus start 体验。
在 #11163 中，我们注意到文档的 showLastUpdateAuthor 和 showLastUpdateTime 成本相当高，需要为每个文档运行一个 git log 命令。在大型站点上，并行运行这些命令可能会耗尽系统并导致 Node.js EBADF 错误。我们实现了一个 Git 命令队列，以避免耗尽系统，这还略微提高了我们插件 loadContent() 生命周期方法的性能。
在 #10885 中，我们为外部链接图标实现了 SVG 精灵图。由于它在站点（导航栏、页脚、侧边栏等）的各个位置重复出现，使用 React SVG 组件会导致最终 HTML 中出现重复的 SVG 标记。使用精灵图允许只嵌入图标 SVG 一次，从而减少生成的 HTML 大小和静态生成时间。我们计划将来使用更多 SVG 精灵图。
在 #11176 中，我们微调了 webpack/Rspack 配置，以移除无用的优化。

提示

如果打包时间是一个问题，请考虑禁用可选的 concatenateModule 打包器优化。我们在这里解释了权衡和操作方法。它只节省了 3% 的 JS，对于一个非常大的站点来说，这项改变的影响是惊人的：冷构建快 4 倍，重新构建快 16 倍 🔥。

影响

我们已经将 React Native 网站升级到 Docusaurus v3.8。以下是显示 Docusaurus Faster 对一个拥有约 2000 页的站点的总构建时间影响的更新基准测试：

ReactNative.dev	冷构建	暖重新构建
🐢 Docusaurus 慢速	120秒 (基准)	33秒 (快 3.6 倍)
⚡️ Docusaurus 快速	31秒 (快 3.8 倍)	17秒 (快 7 倍)

我们在自己的网站上也测量到类似的结果：

Docusaurus.io	冷构建	暖重新构建
🐢️ Docusaurus 慢速	146秒 (基准)	45秒 (快 3.2 倍)
⚡️ Docusaurus 快速	42秒 (快 3.5 倍)	24秒 (快 6.1 倍)

你还可以期待内存使用方面的改进，以及更快的 docusaurus start 体验。

未来标志

Docusaurus v4 未来标志让你选择启用即将到来的 Docusaurus v4 破坏性更改，并帮助你逐步、一次一项地管理它们。启用所有未来标志将使你的站点在 Docusaurus v4 发布时更易于升级。

非原创

未来标志的概念并非我们发明。它在 Remix 社区中广受欢迎。你可以在这里阅读更多关于这种渐进式功能采用策略的信息：

开启所有 v4 未来标志

你可以通过以下快捷方式一次性开启所有 v4 未来标志：

const config = {
  future: {
    v4: true,
  },
};

这样，你就能确保你的站点始终为 Docusaurus v4 做好准备。请注意，我们将在接下来的次要版本中引入更多未来标志。升级时，请务必阅读我们的发布博客文章，以了解你所选择启用的新破坏性更改。

CSS 层叠层

在 Docusaurus v4 中，我们计划利用 CSS 层叠层。这种现代 CSS 功能得到了广泛支持，并允许将 CSS 规则分组到特定性层中。它对于让你更好地控制 CSS 层叠特别有用。它使 CSS 规则对其插入顺序的依赖性降低。你未分层的规则现在将始终覆盖我们提供的分层 CSS。

在 #11142 中，我们实现了一个新的实验性 @docusaurus/plugin-css-cascade-layers，如果你使用经典预设，可以通过 v4.useCssCascadeLayers 标志开启它。

export default {
  future: {
    v4: {
      useCssCascadeLayers: true,
    },
  },
};

我们认为此功能是一个破坏性更改，因为它可能会轻微改变自定义站点中 CSS 规则的应用顺序。这些问题通常是有限的，并且相对容易修复（例如，请参阅 React Native CSS 更改）。不提供自定义 CSS 且不修改任何组件的站点不应受到影响。

实际上，它允许自动将内置 CSS 层叠层应用于我们提供的所有 CSS，包括我们固有的 CSS 框架 Infima。

@layer docusaurus.infima {
  h1 {
    /* Infima css rules */
  }
  pre {
    /* Infima css rules */
  }
}

层可以帮助解决我们长期存在的全局 CSS 污染问题。我们内置的全局 CSS 规则可能会与你的规则冲突，使得使用 Docusaurus 创建与我们 CSS 隔离的操场、演示和嵌入式小部件变得更加困难。幸运的是，CSS 层叠层可以被还原，以创建不受该层 CSS 影响的 HTML 子树。

还原层

正如此问题和这篇博客文章所解释的，可以还原层以将 HTML 子树与来自该层的 CSS 隔离。

实际上，你可以创建一个 .my-playground 类来还原来自 Infima 的全局 CSS：

/* The "impossible" :not() selector helps increase the specificity */
.my-playground:not(#a#b) {
  &,
  * {
    @layer docusaurus.infima {
      all: revert-layer;
    }
  }
}

然后你可以将此类应用于任何 HTML 元素，这样 Infima 就不会应用于其任何子元素。HTML 子树将与我们的内置 CSS 隔离。

/tests/pages/style-isolation?docusaurus-data-navbar=false

`postBuild()` 更改

在 #10850 中，我们添加了一个新的 removeLegacyPostBuildHeadAttribute 未来标志，它稍微改变了 postBuild() 插件生命周期方法的签名，移除了 head 属性。

export default {
  future: {
    v4: {
      removeLegacyPostBuildHeadAttribute: true,
    },
  },
};

这个遗留数据结构来自我们的 react-helmet-async 依赖项，并且最初不应作为公共 API 公开。它不可序列化，这阻止了我们实现用于静态站点生成的工作线程。

虽然技术上是破坏性更改，但我们相信此更改不会影响任何人。我们找不到任何使用此方法接收的 head 参数的开源插件。如果开启此标志导致你的站点出现问题，请在此处告知我们。

系统颜色模式

在 #10987 中，经典主题现在允许你将颜色模式还原为系统/操作系统的默认值。

https://:3000

代码块重构

在 #11058、#11059、#11062 和 #11077 中，主题代码块组件已进行了重大重构，使其更易于定制和扩展。

根据我们的发布流程，这不是一个破坏性更改，但已修改这些组件的站点可能需要进行升级。

翻译

🇹🇷 #10893: 添加缺失的土耳其主题翻译。
🇵🇱 #10884: 添加缺失的波兰主题翻译。
🇨🇳 #10816: 添加缺失的中文主题翻译。
🇯🇵 #11030: 添加缺失的日文主题翻译。

维护

Docusaurus 3.8 已为 Node.js 24 和 TypeScript 5.8 做好准备。

我们还删除了无用的 npm 包，并内部化了未维护的包。

在 #11010 和 #11014 中，我们内部化了 @docusaurus/plugin-ideal-image 中使用的未维护的 react-ideal-image 和 react-waypoint 包，并使它们与 React 19 兼容。
在 #10956 中，我们移除了对未维护的 react-dev-utils 包（来自 Create-React-App）的依赖。
在 #10358 中，我们用 execa 替换了未维护的 shelljs 包。
在 #11138 中，我们移除了 reading-time 包，转而使用内置的 Intl.Segmenter 标准 API 来计算博客文章阅读时间。
在 #11037 中，我们移除了无用的 clean-webpack-plugin。

其他更改

其他值得注意的更改包括

在 #10852 中，主题的 docsVersionDropdown 导航栏项现在接受 versions 属性。
在 #10953 中，@docusaurus/remark-plugin-npm2yarn 插件现在默认支持 Bun 选项卡转换。
在 #10945 中，现在更稳定的 CSS 类应用于主要主题布局元素，以便你创建更可靠的 CSS 选择器。
在 #10846 中，Markdown 代码块的 showLineNumbers 元字符串现在可以接受一个数字来初始化行计数器的初始值。
在 #11090 中，我们简化了提供自定义页面标题格式器的方法。
在 #11088 中，页面插件现在支持 frontMatter.slug，就像文档和博客插件已经做的那样。
在 #10875 中，文档版本控制 CLI 现在还会复制本地化的文档 JSON 翻译文件。

查看3.8.0 更改日志条目以获取完整的更改列表。

性能​

Docusaurus Faster​

持久缓存​

工作线程​

其他优化​

影响​

未来标志​

CSS 层叠层​

postBuild() 更改​

系统颜色模式​

代码块重构​

翻译​

维护​

其他更改​

性能