跳到主要内容

Docusaurus 3.6

·8 分钟阅读
Sébastien Lorber
Sébastien Lorber
Docusaurus 维护者，《本周 React》编辑

我们很高兴地宣布 Docusaurus 3.6。

Docusaurus 现在构建您的网站 ⚡️⚡️⚡️ 快得多。

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

Docusaurus blog post social card

亮点​

此版本主要通过 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 来说不是问题。

内存消耗​

您还应该注意到内存消耗的改善

  • 新的基础设施整体内存消耗更少
  • 我们修复了一个重要的内存泄漏问题，该问题尤其影响国际化站点
  • 我们增加了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。

Loader timeline example

要使用它，请安装新的 @docusaurus/plugin-rsdoctor 包，然后将其作为插件添加到您的配置中

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

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

docusaurus.config.js
export default {
  plugins: [
    process.env.RSDOCTOR === 'true' && [
      'rsdoctor',
      {
        /* options */
      },
    ],
  ],
};
# Build without Rsdoctor
npm run build

# Build with 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: Canary 版本将使用 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 更新日志条目以获取完整的更改列表。