跳到主要内容

Docusaurus 3.6

· 阅读需 10 分钟
Sébastien Lorber
Sébastien Lorber
Docusaurus maintainer, This Week In React editor

我们很高兴地宣布 Docusaurus 3.6 发布。

Docusaurus 现在构建网站的速度 ⚡️⚡️⚡️ 快得多 了。

升级应该很容易。我们的 发布流程 遵循 语义化版本 。次要版本不包含任何重大更改。

Docusaurus 博客文章社交卡片

亮点​

此版本主要关注通过 Docusaurus Faster 项目提升构建性能。

Docusaurus Faster​

Docusaurus Faster 项目的目标是减少构建时间和内存消耗。

我们对多个方面进行了优化，并对我们的基础架构进行了现代化改造，以使用更快的基于 Rust 的工具，尤其包括：

  • 🦀 Rspack ：快速基于 Rust 的 Web 打包器，几乎可以替代 webpack
  • 🦀 SWC ：快速的 Web 编译器，基于 Rust 的 Web 平台 (HTML、CSS、JS)
  • 🦀 Lightning CSS ：一个极快的 CSS 解析器、转换器、打包器和压缩器

影响​

采用新的基础架构可能会产生各种影响。不可能详尽列出所有影响，因此让我们关注主要影响。

为了帮助您轻松采用它，我们在预期的静态站点输出和 浏览器支持 方面相当保守。

构建时间​

社区网站的基准测试表明，您可以预期您的生产站点构建速度加快 ⚡️ 2 到 4 倍 ！🔥：

如何进行基准测试

关于重新构建

Rspack 还不支持持久缓存，但这在路线图上，很快就会实现。考虑到冷 Rspack 构建通常与使用持久缓存的热 Webpack 构建一样快，我们认为这不会影响 Rspack 的采用。

内存消耗​

您还应该注意到内存消耗有所改善：

  • 新的基础架构总体上消耗更少的内存
  • 我们修复了一个重要的 内存泄漏 ，它尤其会影响 i18n 站点
  • 我们添加了 CI 检查 以确保我们不会倒退，并且我们的站点和初始化模板都可以在内存受限的环境中构建
  • 我们添加了 内部工具 以更好地了解构建的哪个步骤会消耗内存
  • 我们 删除了一个 process.exit(0) ，它可能会隐藏您自己代码和第三方插件中的内存泄漏

其他影响​

采用策略​

这个新的基础架构是一个重大更改，但是它是可选的，不需要新的 Docusaurus 主要版本。

在使用 Docusaurus Faster 之前，请添加这个新包：

npm install @docusaurus/faster

为了帮助您 在 Docusaurus v3 下逐步采用它 ，我们引入了一组您可以逐步激活的功能标志。

我们建议使用这个简单的布尔快捷方式一次性全部打开它们：

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

如果其中一个标志不适用于您的站点，则可以独立打开功能标志：

const config = {
  future: {
    experimental_faster: {
      swcJsLoader: true,
      swcJsMinimizer: true,
      swcHtmlMinimizer: true,
      lightningCssMinimizer: true,
      rspackBundler: true,
      mdxCrossCompilerCache: true,
    },
  },
};
实验性但安全

不要害怕打开此功能。实验性的是配置选项。

新的基础架构由我们的 CI 管道进行了全面测试和验证。 Docusaurus 网站 已经在生产环境中使用它，我们也计划将其用于其他 Meta 文档站点。

插件​

新的基础架构使用 Rspack 。碰巧的是，Rspack 与 webpack 几乎 100% 兼容，Rspack 不应该破坏我们的插件生态系统。

大多数 Docusaurus 插件应该可以直接与 Rspack 一起使用，即使是那些实现 configureWebpack 的插件。

但是，其中一些插件需要进行小的修改才能与 Rspack 兼容。总体思路是避免直接导入 webpack，而是使用“动态提供的”webpack 实例：

-import webpack from 'webpack';

export default function (context, options) {
  return {
    name: 'custom-docusaurus-plugin',
-   configureWebpack(config, isServer) {
+   configureWebpack(config, isServer, {currentBundler}) {
      return {
        plugins: [
-         new webpack.DefinePlugin({}),
+         new currentBundler.instance.DefinePlugin({}),
        ]
      };
    },
  };
}
对于插件作者

查看 专用问题 以获取指南和支持。

下一步​

这仅仅是个开始：我们将继续致力于 Docusaurus Faster 项目，并且已经计划了更多性能改进。

根据 您的反馈 ，我们计划在即将发布的 Docusaurus 主要版本中将此新基础架构设为默认值。

🙏 我们要感谢所有这些优秀工具的作者，他们帮助我们使 Docusaurus 比以前快得多。特别是 Rspack 团队 一直支持我们，非常迅速地处理了我们的反馈，并实现了我们使其成为现实所需的所有缺失功能。👏

Rsdoctor 插件​

在 #10588 中，我们为 Rsdoctor 创建了一个 Docusaurus 插件。它分析 Docusaurus 的打包阶段，并帮助您找出在加载器、插件和压缩器方面减慢打包器速度的原因。它适用于 webpack 和 Rspack。

加载器时间线示例

要使用它，请安装新的 @docusaurus/plugin-rsdoctor 包，然后在您的配置中使用该插件：

docusaurus.config.js
export default {
  plugins: [
    [
      'rsdoctor',
      {
        /* options */
      },
    ],
  ],
};
提示

根据环境变量有条件地打开它：

docusaurus.config.js
export default {
  plugins: [
    process.env.RSDOCTOR === 'true' && [
      'rsdoctor',
      {
        /* options */
      },
    ],
  ],
};
# 在没有 Rsdoctor 的情况下构建
npm run build

# 使用 Rsdoctor 构建
RSDOCTOR=true npm run build

Mermaid​

在 #10510 中，我们放宽了对 Mermaid 图表 依赖项范围的限制，以允许使用更新的主要版本的 Mermaid。我们现在支持 Mermaid 10/11，并预期即将发布的版本将兼容，让您能够按照自己的条件进行升级。

这解锁了新的图表类型，例如 架构图 ：

翻译​

  • 🇸🇮 #10551 ：改进斯洛文尼亚语主题翻译。
  • 🇻🇳 #10507 ：改进越南语主题翻译。
  • 🇪🇸 #10413 ：改进西班牙语主题翻译。

其他更改​

其他值得注意的更改包括：

  • #10586 ：博客支持 frontMatter.title_meta 以出于 SEO 原因覆盖 frontMatter.title。
  • #10600 ：docusaurus build 和 docusaurus deploy 现在支持多个 --locale CLI 参数。
  • #10454 ：docusaurus-remark-plugin-npm2yarn 升级到 npm-to-yarn v3 并可以转换 npx 命令。
  • #10612 ：金丝雀版本将使用 3.5.2-canary-<number> 而不是 0.0.0-canary-<number> 来尊重插件的 peerDependency 约束。
  • #10547 ：@docusaurus/tsconfig 升级到 target: 'es2022'。
  • #10514 ：从 Docusaurus 初始化模板中删除 babel.config.js 以阻止自定义 Babel。

查看 3.6.0 更新日志 以获取所有更改的详尽列表。