Docusaurus 3.6
我们很高兴地宣布 Docusaurus 3.6 现已发布。
Docusaurus 现在可以⚡️⚡️⚡️: 更快的 构建你的网站。
Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
精彩内容
该版本主要专注于通过 Docusaurus Faster 项目构建性能。
Docusaurus Faster
Docusaurus Faster项目的目标是减少构建时间和内存消耗。
我们致力于多个优化和使我们的基础设施现代化，以便更快地使用基于Rus的工具，特别是：
- 🦀 Rspack: 基于Rust的快速网页打包工具, 几乎是可以作为 webpack的完全替代品
- 🦀 SWC: 快速的网页编辑器，基于Rust的网页平台(HTML, CS, JS)
- 🦀 Lightning CSS: 一个极为快速的 CSS 解析器、翻译器、打包工具和压缩器。
影响
采用新的基础设施可能会产生各种影响。 由于不可能将所有问题全部列举出来，因此我们将重点关注主要的几个。
为了帮助您轻松地使用它，我们在预期的静态站点输出和浏览器支持 方面相当保守。
构建时间
社区网站上的基准测试显示，您可以期待您的生产网站构建速度 ⚡️ 提高 2 到 4 倍！ 🔥:
- React Native website: 速度提升了 3.04x 倍 🔥
- Babel website: 速度提升了 3.27x 倍 🔥
- Lexical website: 速度提升了 2x 倍 🔥
Rspack 目前尚不支持持久缓存，但它在开发路线图上，预计很快会实现。 我们认为，这对 Rspack 的采用并不是一个问题，因为冷启动的 Rspack 构建通常与使用持久缓存的热 Webpack 构建一样快。
内存消耗
您还应该注意到内存消耗的改进：
- 新基础设施消耗总内存减少
- 我们修复了一个重要的内存泄漏，它特别影响到i18n 站点
- 我们添加了CI检查，以确保我们不会出现回归问题，并且我们的站点和初始化模版都能在内存受限的环境中构建。
- 我们添加了内部工具以更好地理解构建的哪一步消耗内存
- 我们移除了一个
process.exit(0)，该代码可能会掩盖您自己代码和第三方插件中的内存泄漏问题。
其他影响
- HTML 压缩器现在可以在出现无效的 HTML markup时发出警告
- 静态 HTML 输出 减少了~5%的大小
- 一些错误被新的基础结构自动修复
采用策略
这种新的基础设施是一种突破性的变化，但它是选择性的，不需要新版本的Docusaurus。
在使用 Docusaurus 更快之前，添加这个新包：
- npm
- Yarn
- pnpm
npm install @docusaurus/faster
yarn add @docusaurus/faster
pnpm add @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,
},
},
};
swcJsLoader: 使用 SWC 转换JS(而不是 Babel)swcJsLoader: 使用 SWC 转换JS(而不是 Babel)swcHtmlMinimizer: 使用 SWC 来挖掘HTML和嵌入式JS/CSS(而不是 html-minifier-terser)lightningCssMinimizer：使用 Lightning CSSS 来缩小CSS (而不是 cssnano 和 clean-css)rspackBundler：使用 Rspack 打包您的应用程序(而不是 webpack)mdxCrossCompilerCache：一次同时为浏览器/Node.js环境编译MDX文件，而不是两次。
不要害怕打开此功能。 配置选项是实验性的。
新的基础设施是牢固的，我们的综合基础设施管道对其进行了很好的考验。 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 包，然后在你的配置中使用插件：
export default {
plugins: [
[
'rsdoctor',
{
/* options */
},
],
],
};
基于环境变量有条件地启用它：
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 diagrams 依赖范围以允许较新的主要版本的Mermaid。 我们现在支持 Mermaid 10 和 11，并预计即将发布的版本也将兼容，让您可以根据自己的需求进行升级。
解锁了新的图表类型，例如 架构图：
Translations
其他改变：
Other notable changes include:
- #10586: 博客支持
frontMatter.title_meta以基于SEO 的理由覆盖frontMatter.title。 - #10600:
docusaurus buildanddocusaurus depl现在支持多个--localeCLI args. - #10454:
docusaurus-mot-plugin-npm2yarn升级到 [npmto-yarnv3](https://github.com/nebrelbug/npm-to yarn/releases/tag/v3.0.0.0) 并可以转换npx命令。 - #10612：Canary releases will used
3.5.2-canary-<number>而不是0.0.0-canary-<number>for respect pluginspeerDependency。 - #10547:
@docusaurus/tsconfig升级到 `target: 'es2022' - #10514：从Docusaurus init 模板中删除
babel.config.js，以阻止定制Babel。
查看 3.6.0 changelog entry 以获取更详细的变更列表
