Docusaurus 3.10 发布：v3 系列收官之作，助你为 v4 做好准备

我们很高兴地宣布 Docusaurus 3.10 正式发布。

这是 v3.x 系列的最后一个版本，旨在帮助你 为 Docusaurus v4 做好准备。

升级非常简单。我们遵循 Semantic Versioning，根据我们的发布流程，minor 版本更新不会有破坏性变更。

不过，如果你已通过 future.v4: true 全局启用了 Docusaurus v4 的破坏性变更，请务必查看下文专门章节。

v4 Future Flags​

Docusaurus v4 Future Flags 让你可以逐步启用 Docusaurus v4 即将到来的破坏性变更，提前为 v4 做好准备。通过 future.v4: true 可以一次性全部启用。

本次发布引入了新的 flag 和破坏性变更——如果你在启用 future.v4: true 的情况下升级，站点可能会受影响：

• future.v4.siteStorageNamespacing：在 Docusaurus v4 中，localStorage 的 key 默认会自动加命名空间（theme => theme-<hash>），以避免 key 冲突。如果不把旧数据迁移到新的 key，站点的访客存储数据很可能会被重置。详见下文Site Storage 章节。
• future.v4.fasterByDefault：Docusaurus Faster 现已稳定，并将在 Docusaurus v4 中默认启用。详见下文 Docusaurus Faster 章节。
• future.v4.mdx1CompatDisabledByDefault：在 Docusaurus v4 中，MDX v1 兼容选项将默认关闭，你可能需要相应调整文档。详见下文 Strict MDX 章节。

安全​

npm 供应链攻击 近期频发。一个被入侵的维护者或包可能在整个生态系统中产生连锁反应，影响成千上万的下游用户，axios 被入侵事件 便是典型例子。

我们已采取措施加强供应链安全，并建议你也通过额外手段加固自己的站点。

可信发布​

我们为 稳定版 和 Canary 版 采用了 npm 可信发布 机制。

现在，发布流程通过单一的 publish.yml GitHub Actions 工作流完成，并使用短时效的 OIDC 令牌。每次发布都有可验证的来源信息，附带透明度日志，记录其发布时间和方式。

安全工作流​

在 #11874 中，我们引入了一个新的安全工作流，每天运行一次，并在每次 Pull Request 时触发。它会扫描针对官方包及其传递依赖的可疑依赖更新：

• 通过 Socket Firewall 安装 Docusaurus 站点模板，以检测依赖图中的已知恶意软件
• 使用 pnpm strictDepBuilds 检查意外的 preinstall 和 postinstall 生命周期脚本
• 使用 pnpm blockExoticSubdeps 检查 GitHub 仓库和 tarball URL 依赖
• 使用 pnpm trustPolicy: no-downgrade 检查降低信任级别的包
• 在自家 monorepo 上运行类似的检查，保护 Docusaurus 的维护者和贡献者

安全限制

此安全工作流不会保护你的站点。它旨在尽可能早地检测影响 Docusaurus 生态系统的严重漏洞，以便我们快速响应并通知你。

使用 semver 依赖范围时，无法保证 100% 安全的供应链，因为依赖图中的任何新 npm 版本都可能引入漏洞。最终，保障站点安全是你的责任。至少，应依赖锁文件（lockfile），并谨慎、有意识地升级依赖项。

保护你的站点​

阅读 npm 安全最佳实践 指南，学习如何保护你的站点——乃至所有 npm 应用——免受被篡改的依赖项影响。

不同的包管理器提供不同的安全选项。根据我们的经验，pnpm 提供的选项最好。我们不会记录所有可能性，但这里有一个与 Docusaurus 配合良好的 pnpm 配置示例：

pnpm-workspace.yaml

minimumReleaseAge: 10080

blockExoticSubdeps: true

strictDepBuilds: true
allowBuilds:
  '@swc/core': true
  core-js-pure: true
  core-js: true

trustPolicy: no-downgrade
trustPolicyExclude:
  - '[email protected]'
  - '[email protected]'

使用发布冷却期

当热门 npm 包被篡改时，社区通常能迅速发现并将其下架。使用发布冷却期是降低暴露窗口期间风险的有效方法。

现代包管理器现在提供了一种延迟 npm 更新的方法，为安全扫描器报告漏洞留出时间。

# npm v11.10+ - .npmrc
min-release-age=7

# pnpm v10.16+ - pnpm-workspace.yaml
minimumReleaseAge: 10080

# Yarn v4.10+ - .yarnrc.yml
npmMinimalAgeGate: "7d"

# Bun v1.3+ - bunfig.toml
[install]
minimumReleaseAge = 604800

Docusaurus Faster - 稳定版​

Docusaurus Faster 允许你选择启用我们现代化的构建基础设施，包括 Rspack、SWC、LightningCSS 以及其他多项优化。

本次发布为 Docusaurus Faster 新增了 gitEagerVcs 配置项，并完整支持 Yarn PnP。

在 #11802 中，我们将 Docusaurus Faster 标记为稳定版，现在需要相应地更新你的配置：

docusaurus.config.js

const config = {
  future: {
-   experimental_faster: true,
+   faster: true,
  },
};

v4 默认开启 Faster

在 Docusaurus v4 中，Docusaurus Faster 将默认启用，并且所有新建的 v3 站点已经在使用它。它现在已成为 v4 future flags 的一部分（future.v4.fasterByDefault: true），以便社区提前为 Docusaurus v4 做准备。如果你还没开启，现在是好时机！

Site Storage - 稳定版​

在 #11797 中，我们将 config.storage API 标记为稳定版，现在需要相应地更新你的配置：

docusaurus.config.js

 const config = {
+  storage: {
+    type: 'localStorage',
+    namespace: true,
+  },
-  future: {
-    experimental_storage: {
-      type: 'localStorage',
-      namespace: true,
-    },
-  },
 };

v4 中的自动命名空间

Docusaurus v4 将默认自动为你的 storage key 添加命名空间，避免 localStorage 的 key 冲突，这已纳入 v4 future flags（future.v4.siteStorageNamespacing: true）。例如 theme key 会变成 theme-<hash>。

这类 key 冲突通常发生在同时运行多个 http://localhost:3000 应用时，或在同一域名下运行多个应用时（如 https://example.com/app 和 https://example.com/docs）。

Strict MDX​

本次发布引入了新的 MDX 配置项，鼓励更严格地使用原生 MDX 语法，而不是依赖 Docusaurus 在 MDX 之上的私有语法。

长期以来，Docusaurus 使用 MDX v1 编译你的文件，其规则相当宽松。如今，生态已广泛转向更严格的 MDX v3。Docusaurus v3.0 引入了 markdown.mdx1Compat，以帮助你逐步完成升级。

在 Docusaurus v4 中，我们计划默认关闭 markdown.mdx1Compat 选项。这一即将到来的变更已成为 v4 未来特性的一部分（future.v4.mdx1CompatDisabledByDefault: true）。

我们希望通过以下几点理由，推动社区采纳更严格的原生 MDX 语法：

• 提升文档的便携性：Prettier、ESLint、TypeScript、VS Code 和 GitHub 等外部工具都能正确理解。
• Docusaurus 无需在 MDX 编译前使用正则表达式预处理文档。
• 改善与 Unified 生态系统（Remark、MDX）及 MDX Playground 的兼容性。

严格扩展名​

我们的观点是：

• .md 应作为 CommonMark 解析
• .mdx 应作为 MDX 解析

实际上，Docusaurus 一直以来只支持 MDX，我们本应一开始就使用 .mdx 扩展名。新初始化的站点现在默认使用 .mdx（#11897）。我们也建议你重命名现有文件为 .mdx，以便外部工具能识别你的内容属于 MDX。

关于 CommonMark 支持

尽管我们也提供 CommonMark 的实验性支持，但目前尚未具备与 MDX 完全一致的功能（issue）。待功能完全对齐后，我们将默认启用 markdown.format: 'detect'，以确保 .md 文件作为 CommonMark 而非 MDX 解析。

严格 Admonitions​

过去，我们支持使用 :::type 我的标题 语法来定义带标题的 Admonitions。虽然方便，但这属于 Docusaurus 的专有语法。

Markdown 指令语法更通用、可复用性更强。虽然该语法尚未标准化，但已被包括 remark-directive 包在内的多个生态系统广泛采用。建议将现有的提示框（admonitions）迁移至 :::type[标题] 语法：

-:::warning Pay Attention
+:::warning[Pay Attention]

 Content

 :::

严格注释​

MDX v3 不支持 HTML 注释 <!-- comment -->，仅支持 JSX 注释表达式 {/* comment */}。

如果你正在使用 HTML 注释，建议迁移至 JSX 注释。例如，可使用 JSX 注释来截断博客文章：

blog/my-post.mdx

 # My Blog Post

-<!-- truncate -->
+{/* truncate */}

 blog post content

严格标题 ID​

我们过往使用的标题 ID 语法 {#my-id} 属于 Docusaurus 私有语法，导致了与生态系统的兼容性问题。

在 #11755 中，我们引入了基于原生 MDX 注释的新标题 ID 语法，并建议采用该格式：

-## My Heading {#my-id}
+## My Heading {/* #my-id */}

在 #11777 中，我们还为 write-heading-ids CLI 新增了一个选项，用于生成并迁移至新语法：

docusaurus write-heading-ids --syntax mdx-comment --migrate

VCS API - 实验性​

在 #11512 中，我们新增了一个实验性的 VCS（版本控制系统）API，并实现了读取 Git 历史记录时的内置性能优化。

过去，Docusaurus 仅集成 Git，通过读取提交历史来实现以下功能：

• 在使用 showLastUpdateAuthor 或 showLastUpdateTime 选项时，在文档、博客和页面插件中显示最后更新时间/作者
• 在博客插件中显示文章创建日期
• 在 sitemap 插件中计算 <lastmod> 值

这个新 API 可以让 Docusaurus 接入其他版本控制系统（VCS），比如 SVN、Mercurial、CMS 或任何外部系统。

下面是一个使用硬编码数据的示例实现：

docusaurus.config.ts

export default {
  future: {
    experimental_vcs: {
      initialize: ({siteDir}) => {
        // 如有需要，可以在这里初始化并缓存 VCS 数据
      },
      getFileCreationInfo: async (filePath: string) => {
        return {timestamp: 1490997600000, author: 'Slash'};
      },
      getFileLastUpdateInfo: async (filePath: string) => {
        return {timestamp: 1490997600000, author: 'Slash'};
      },
    },
  },
};

我们还发现，过去从 Git 历史读取信息的策略，对大型 Docusaurus 站点来说可能成为严重的构建性能瓶颈——为每个 MDX 文件单独执行一次 git log <filepath>，扩展性很差。

为了解决这个瓶颈，我们实现了一种新策略：只用一次 git log 调用就把整个 Git 仓库数据预读进来，性能提升非常明显。该策略已纳入 Docusaurus Faster（future.faster.gitEagerVcs: true），并将在 Docusaurus v4 中成为默认值。

我们还提供了内置的 VCS 预设策略，包括：

• git-ad-hoc：历史上的旧策略，基于 git log <filename> 调用
• git-eager：新的 Git 策略，一次性预读整个仓库
• hardcoded：返回硬编码值，在开发/测试中可用于提升开发体验
• disabled：对所有文件返回 null，视为未被跟踪
• default-v1：过去的默认策略（动态：生产环境用 git-ad-hoc，开发环境用 hardcoded）
• default-v2：Docusaurus v4 将采用的默认策略（动态：生产环境用 git-eager，开发环境用 hardcoded）

docusaurus.config.ts

export default {
  future: {
    experimental_vcs: 'default-v2',
  },
};

试验性 VCS API 为试验性接口，其设计可能随时调整。欢迎试用并参与社区讨论反馈意见。尽管 API 尚不稳定，但内置的 Git Eager 策略在简单 Git 仓库中已较为稳定；若仓库嵌套多个 Git 仓库或使用子模块，可能出现边缘情况。

翻译​

• 🇵🇰 #11632：新增乌尔都语 ur 主题翻译。
• 🇧🇷 #11533：补全巴西葡萄牙语 pt-BR 缺失的主题翻译。

其他变更​

其他值得关注的新变化包括：

• #11843：新初始化站点默认使用 TypeScript 6.0，目前需配置 "ignoreDeprecations": "6.0"。
• #11571：siteConfig.headTags API 现支持自定义 HTML 元素。
• #11675：Live code block 主题新增重置 Playground 的按钮。
• #11734：拆分 <DocCard> 组件，更便于扩展或 Swizzle，生成文档索引页时也更容易设置自定义表情符号。
• #11733：<Tabs> 组件改用 React Context 而非 Props，可据此创建自定义 <TabItem> 组件。
• #11696：新初始化的 TypeScript 站点默认启用 "strict: true"。
• #11611：支持在当前目录 . 中直接创建新的 Docusaurus 站点。
• #11666：pages 插件现支持 Markdown 文件路径链接（如 [text](./other-page.md)），与 docs 和 blog 插件保持一致。

在#11642中，admonitions（提示框）现支持 class/id 简写，例如:::note{.my-class #my-id}。

在#11541和#11683中，我们确保了 Docusaurus 与最新版 Algolia DocSearch 4.x 的兼容性，从而解锁了 AskAI Suggested Questions 等新功能。

在#11684和#11653中，我们从create-docusaurus CLI 中移除了大量第三方依赖，加快了新建站点的速度。

在#11794中，我们修复了一个长期存在的 Bug，此前分页链接中的分类索引页标题无法被翻译。

在#11784中，我们更改了推荐的数学公式语法，以提高文档的可移植性，更倾向于使用常规的 Markdown 代码块而非$$。

在#11753中，我们添加了一个基本的AGENTS.md文件。再次提醒，在 Docusaurus 贡献中任何 AI 的使用都必须披露。

在#11698中，我们将 monorepo 升级到了 React 19。我们将在 Docusaurus v4 中放弃对 React 18 的支持。

有关完整的更改列表，请查看3.10.0 更新日志条目。