跳到主要内容

Docusaurus 的一些常见问题

提示

本段为在使用Docusaurus时可能会出现的一些问题，由deepseek回答。

为 Docusaurus 的帖子（包括博客和文档）增加创建时间与最后修改时间，有完全不同的实现方式。下面我为你拆解这两种场景的具体做法。

如何将博客设置为主页​

在 Docusaurus 中，将博客页设为网站主页需要通过修改路由配置来实现。这本质上是改变了博客插件和页面插件默认的访问路径。主要有两种方法，你可以根据需求选择。

方法一：直接让博客"占用"根路径（推荐）​

这个方法的思路是，将博客插件的路由基础路径（routeBasePath）设置为根路径 /，这样当用户访问网站首页时，就会直接看到博客列表。这也是文档中所提到的 "仅博客模式" 的实现方式。

操作步骤如下：

  1. 修改配置文件：打开项目根目录下的 docusaurus.config.js 文件。
  2. 调整博客插件路径：在 presets 中找到 @docusaurus/preset-classic 的 blog 配置项，将 routeBasePath 设置为 '/'。
  3. （可选）处理原有首页：为了让改动更彻底，你可以直接删除或重命名默认的首页文件 src/pages/index.js（或 index.tsx）。如果不删除，访问根路径时可能会因为路由冲突而出现意想不到的问题。

配置代码示例如下：

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ... 其他配置
        blog: {
          routeBasePath: '/', // 关键配置：将博客的访问路径设置为网站根目录
          // ... 其他博客配置
        },
      },
    ],
  ],
};

完成配置并重启开发服务器后，访问 http://localhost:3000/ 就会直接显示你的博客文章列表了。

方法二：使用客户端重定向​

如果你不想改变博客原有的 /blog 路径，而是希望在用户访问首页时，自动跳转到博客页。这可以通过一个简单的重定向组件实现。

操作步骤如下：

  1. 创建重定向组件：在 src/pages/index.js（或 index.tsx）文件中，编写一个执行重定向的 React 组件。
  2. 指定目标路径：使用 @docusaurus/router 提供的 <Redirect> 组件，将流量指向 /blog。

代码示例如下：

import React from 'react';
import { Redirect } from '@docusaurus/router';

export default function Home() {
  return <Redirect to="/blog" />;
}

这种方法实现简单，但请注意它是一个客户端重定向，可能会对首次加载速度和 SEO 有一点影响。

💎 总结与建议​

特性方法一：修改博客根路径方法二：客户端重定向
最终效果根路径/ 直接显示博客内容访问根路径/ 会跳转到 /blog
复杂度较低，仅修改配置较低，创建单文件组件
SEO 影响博客内容直接作为首页，URL简洁存在一次客户端跳转，URL是/blog
推荐场景更推荐。希望博客成为网站真正意义上的首页。希望保留/blog 路径作为博客入口，但用户访问主页时引导至博客。

选择方法一能够更彻底地将博客内容作为网站的核心入口，实现你想要的效果。

_category_.json有什么作用？该如何配置​

_category_.json 是 Docusaurus 自动生成侧边栏时的“指挥中心”，它让你不用手动编辑 sidebars.js，就能直接通过文件夹来精细控制文档的分类展示。简单说，把哪个文件夹变成什么分类、放在哪里、怎么显示，都由这个文件说了算。

📁 核心作用：定义与控制分类​

_category_.json 必须放在需要管理的文件夹根目录下，它的核心作用是定义该文件夹在侧边栏中作为一个分类（Category）的展示方式。

你可以通过它来控制：

  • 分类名称 (label)：在侧边栏里显示给用户看的名字，比如 "入门指南"。
  • 分类排序 (position)：决定这个文件夹（分类）在它所属的“上一级侧边栏切片”（即同级菜单中）的排列顺序，数字越小越靠前。
  • 展开行为 (collapsible/collapsed)：控制侧边栏里的这个分类是否可折叠，以及默认是展开还是折叠状态。
  • 生成索引页 (link)：这是很实用的功能。它可以为这个分类自动生成一个“索引页”，用来展示该分类下的所有文档摘要，让你的文档结构像一本书的目录一样清晰。

⚙️ 配置示例解读​

一个最基础的 _category_.json 文件内容通常是这样：

{
  "label": "入门指南",  // 侧边栏显示的名称
  "position": 1,        // 在上级侧边栏中的排序，数字越小越靠前
  "link": {
    "type": "generated-index", // 为此分类自动生成一个索引页面
    "title": "入门指南",       // 索引页面的标题
    "description": "从这里开始你的Docusaurus之旅" // 索引页面的描述
  }
}

💎 最佳实践与注意事项​

  1. 适用场景：最适合与你sidebars.js中的 { type: 'autogenerated', dirName: '...' } 配置配合使用。
  2. 不宜混用：不要试图在 _category_.json 里通过 items 字段来手动指定该分类下包含哪些文档。这个操作不被支持，强行添加会导致构建错误。自动生成侧边栏会根据文件夹内的实际文件自动生成列表。
  3. 索引页的作用：当配置了 link 指向一个索引页（如 generated-index）后，侧边栏中该分类的标签（label）会变为可点击的链接，方便用户快速查看该分类的概览。

在blog中能否增加coming soon的帖子？​

可以的，Docusaurus 原生就支持为博客文章添加类似“Coming Soon”的草稿状态。

这个功能的核心是通过在文章的前置信息（Front Matter）中添加一个简单的字段来实现的。具体有两种方式，你可以根据你的发布计划来选择。

使用 draft: true 制作草稿（推荐）​

这是最直接的方法。当你在博客文章里设置 draft: true 时，这篇文章会变成一个只有你自己能看到的“草稿”。

  • 它的行为是：
    • 本地开发时 (docusaurus start)：这篇文章会正常显示在博客列表里，你可以随时预览和编辑它。
    • 生产构建时 (docusaurus build)：这篇文章不会被包含在最终的静态网站里，也不会出现在侧边栏、搜索索引和站点地图中，确保不会对外发布。
    • 这个功能在 Docusaurus v1 中就已经存在，并在 v2 及之后版本中得到延续和支持。

配置示例：在你的博客文章文件顶部，添加 draft: true 即可。

---
title: 即将推出的重磅功能
authors: [your_author_id]
draft: true  # 关键配置，标记为草稿
---

这篇内容正在准备中，只有你能在本地看到它。

使用 unlisted: true 实现“未公开”效果​

如果你希望文章在最终发布时，能通过直接链接分享给特定的人（比如给团队成员或早期用户预览），但又不想让它出现在博客列表、标签归档或搜索结果中，那么 unlisted: true 是更合适的选择。

它的行为是：

  • 生产构建中：文章页面会被生成，但不会列在博客首页、侧边栏或RSS订阅中，搜索引擎也不会索引到它。
  • 访问方式：只有知道这篇文章确切URL的人才能访问。

配置示例：

---
title: 即将推出的重磅功能
authors: [your_author_id]
unlisted: true  # 不公开列出，但可通过链接访问
---

你可以把这个链接分享给团队做内部预览。

📝 总结：如何选择​

简单来说，这两个字段的区别在于：

字段是否对外可见是否出现在列表最佳场景
draft: true完全不可见仅在本地开发环境可见自己还在写作中的“Coming Soon”内容
unlisted: true通过直接链接可见生产环境不可见可以分享给特定用户预览，但尚未准备好公开发布

所以，如果只是你自己在写还没打算对外公开的新文章预告，使用 draft: true 就已经足够实现“Coming Soon”的效果了。

如何配置隐藏的网页？​

在 Docusaurus 中配置“隐藏的网页”，可以根据你的具体需求选择不同的方法。这主要取决于你想要的“隐藏”效果：是完全不公开发布，还是仅从导航中移除但保留链接。

以下是几种最常用和有效的方法。

🌿 草稿模式：完全隐藏，用于未完成内容​

如果你想把正在编写的页面藏起来，不让它在线上公开，draft: true 是最佳选择。

  • 效果：在 docusaurus build 生产构建时，该页面完全不会被生成，因此不会出现在任何地方，包括侧边栏、搜索和站点地图中。但在 docusaurus start 开发模式下，你仍然可以预览它。
  • 配置方法：在你的 Markdown 或 MDX 文件（无论是文档还是博客）的开头 Front Matter 中添加 draft: true。
---
title: 我的草稿页面
draft: true
---

🕶️ 未列出模式：可链接访问，但不公开可见​

如果你的页面已经完成，但只想通过直接链接分享给特定人员（比如内部预览），而不希望它出现在公开的导航或搜索结果中，可以使用 unlisted: true。

  • 效果：在生产构建中，页面会被生成，并且可以通过 URL 直接访问。但它不会出现在侧边栏、搜索索引、站点地图或博客列表中。
  • 配置方法：同样是在 Front Matter 中添加 unlisted: true。
---
title: 内部预览页面
unlisted: true
---

🗺️ 从导航中移除但页面依然存在​

如果你希望页面公开，但只是不想让它出现在侧边栏或导航栏中，可以单独控制导航的显示。

  • 从侧边栏隐藏：
    • 推荐方法：在你的侧边栏配置文件（通常是 sidebars.js）中，直接移除或注释掉该页面的条目。
    • 备选方法：在文档的 Front Matter 中添加 hide_in_sidebar: true，这只会将其从侧边栏移除，但页面本身仍然可被搜索引擎索引和通过搜索找到。
  • 从导航栏隐藏：编辑 docusaurus.config.js 文件中的 themeConfig.navbar.items 数组，移除对应的导航项链接即可。

💡 进阶技巧​

  • 使用 slug 自定义路径：可以通过 slug 字段为页面设置一个和文件路径无关的、简洁的永久链接，让 URL 更可控。
  • 隐藏整个文件夹：如果在 docs 目录下，想保留文件但不生成对应页面，可以在文件名前加下划线 _，例如 _my-hidden-file.md。Docusaurus 将不会为这个文件创建页面。

根据你的需求，选择最适合的方法即可。如果你能补充说明更具体的使用场景，比如是博客还是文档，也许还能提供更针对性的建议。

如何将最近blog换成所有blog​

要把博客列表从"最近"的几篇改成显示"所有"博客，只需要修改一个配置项。这个功能在 Docusaurus v2 中就已经支持了。

⚙️ 修改配置​

在 docusaurus.config.js 文件中，找到博客插件的配置部分，将 postsPerPage 的值改为 'ALL'。

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          // ... 你的其他博客配置
          postsPerPage: 'ALL', // 关键：显示所有博客，取消分页
        },
      },
    ],
  ],
};

💡 效果与建议​

设置成 'ALL' 之后，你的博客首页会一次性加载所有文章。这样一来：

  • 优点：所有文章一目了然，方便访客浏览你的全部内容。
  • 注意：如果文章数量非常多（比如超过几十上百篇），可能会影响页面加载速度。如果你的文章数量适中，这个设置会让体验更流畅。

如果你希望保留分页，但将每页显示的数量从默认的 10 篇调大一些，也可以把 'ALL' 替换成一个具体的数字，比如 postsPerPage: 20。

为帖子增加创建时间和最后修改时间​

📝 为博客（Blog）增加时间​

博客天生就带创建日期，主要需求是补充最后修改时间。Docusaurus 从 v3.6.0 版本开始，为博客插件原生支持了这项功能。

你只需要在 docusaurus.config.js 的博客插件配置中开启两个选项即可：

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          // ... 你的其他博客配置
          showLastUpdateTime: true, // 显示最后修改时间
          showLastUpdateAuthor: true, // 显示最后修改作者
        },
      },
    ],
  ],
};

开启后，Docusaurus 会自动读取 Git 提交历史，在每篇博客文章下方显示最后修改时间和作者。如果文章从未修改，则不会显示此信息。这个特性让读者能快速了解内容的时效性。

📚 为文档（Docs）增加时间​

官方在 @docusaurus/plugin-content-docs 插件中为文档页面提供了更灵活的支持。

1. 显示最后更新时间​

你可以像博客一样，在文档插件配置中开启基于 Git 的最后更新显示，这是一种通用的便捷方式：

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // ... 你的其他文档配置
          showLastUpdateTime: true,
          showLastUpdateAuthor: true,
        },
      },
    ],
  ],
};

2. 自定义创建和更新时间​

如果你需要精确控制，比如从旧站点迁移时需要保留原始的创建时间，可以使用 Front Matter（前言）中的 created 和 last_update 字段来手动指定日期。这让你完全掌控时间的显示，而无需依赖 Git 提交记录。

---
created: 2024-01-15       # 自定义创建日期
last_update:
  date: 2024-06-20        # 自定义最后更新日期
  author: 你的名字
---

这种方式的优先级最高，会覆盖基于 Git 自动生成的信息。启用后，Docusaurus 会自动将这些日期解析并应用到页面元数据中。

💎 总结与对比​

内容类型创建时间最后修改时间配置方式
博客 (Blog)由文件命名或 Front Matter 中的date 字段决定通过showLastUpdateTime 选项启用，基于 Git 历史在博客插件配置中设置
文档 (Docs)可通过 Front Matter 的created 字段自定义通过showLastUpdateTime 选项启用，或用 last_update 字段手动指定在文档插件配置中设置，或在文件 Front Matter 中声明

两种内容类型都内置了对 Git 最后修改时间的支持。如果需要更精细的控制，特别是为文档页面保留原始的创建日期，可以充分利用 Front Matter 中提供的 created 和 last_update 字段。

如何对docs中的一个.md做到仅展示到##的标题，而不展示###标题​

要让某个 .md 文档的目录只展示到 ## 级别，隐藏所有 ### 标题，最标准的方法是在该文件的 Front Matter 中设置 toc_max_heading_level。

⚙️ 配置方法​

在你需要修改的那个 .md 文件顶部的 Front Matter 中添加以下配置：

---
title: 你的文档标题
toc_max_heading_level: 2
---

这样设置后，该页面右上角的目录就只会显示 ##（h2）标题，### 及更深层级的标题都会被隐藏。

💡 补充说明​

  • 默认行为：Docusaurus 默认会显示 h2 和 h3 标题。通过将 toc_max_heading_level 设为 2，你就是在告诉它“最大只解析到二级标题”。
  • 仅影响当前页面：这种 Front Matter 方式的设置只对当前这一个文档生效，不会影响其他页面。如果你需要全局修改所有文档的目录层级，可以在 docusaurus.config.js 的 themeConfig.tableOfContents 中进行配置。
  • 内容不受影响：这个配置只改变目录侧边栏的显示，文章正文中的 ### 标题依然会正常渲染和显示，不会消失。

部署到cloudflare上的work&pages时，如何升级cloudflare上的node.js和docuraurus版本​

[INFO] You are using Node.js v18.17.1, Requirement: Node.js >=20.0.
2026-08-07T06:38:41.429703Z	[ERROR] Minimum Node.js version not met :(

这个错误是因为 Cloudflare Pages 默认的 Node.js 版本是 18，而你的 Docusaurus 项目要求 20 或更高版本。你不需要也不能在 Cloudflare 上升级“系统”的 Node.js，你需要做的是覆盖构建环境使用的 Node.js 版本。

💡 为什么会出现这个错误？​

Cloudflare Pages 的构建环境有固定的“构建镜像”，v2 版本默认使用 Node.js 18。你的 Docusaurus 项目（以及越来越多个框架）要求 Node.js 20+，所以构建会失败。好在，Cloudflare 允许你通过几种简单的方式指定构建时使用的 Node.js 版本。

✅ 解决方案：指定 Node.js 版本​

要解决这个问题，有三种推荐的方法，你只需要选择其中一种。

方法一：升级 Pages 构建系统版本到 v3（推荐）​

Cloudflare Pages 最新的 v3 构建系统默认已经包含了 Node.js 22。

  1. 登录 Cloudflare Dashboard。
  2. 进入 Workers & Pages，选择你的 Pages 项目。
  3. 在项目设置中，找到 Builds & deployments 部分。
  4. 在 Build system version 选项中，选择 v3 并保存。

这样，下次构建时就会默认使用 Node.js 22，满足 Docusaurus 的要求。

方法二：通过环境变量指定版本（最灵活）​

如果你不想升级构建系统，可以设置 NODE_VERSION 环境变量来明确指定版本。

  1. 在你的 Pages 项目仪表盘，进入 Settings > Environment variables。
  2. 点击 Add variable，添加一个名为 NODE_VERSION，值为 20 或 22 的环境变量。

方法三：在项目中添加版本配置文件（推荐与代码同步）​

你也可以在项目根目录下添加一个文件，Cloudflare Pages 会自动读取它来指定 Node.js 版本。

  • 创建 .nvmrc 或 .node-version 文件：在项目根目录下创建该文件，并在文件内容中写入你需要的 Node.js 版本号（例如 20 或 22）。
  • 将这个文件提交到你的代码仓库，这样版本要求就和代码绑定在一起了。

📌 关于 Docusaurus 版本升级​

你提到的“升级 Docusaurus 版本”这件事，并不在 Cloudflare 上进行。Docusaurus 是你项目代码的一部分，在 package.json 文件中管理。升级步骤和你本地开发时一样：

  1. 在你的本地项目目录中，运行 npm update @docusaurus/core@latest @docusaurus/preset-classic@latest（或用 yarn/pnpm）。
  2. 测试本地构建 (npm run build) 确保一切正常。
  3. 将更新后的 package.json 和 package-lock.json 提交并推送到 GitHub。
  4. Cloudflare Pages 检测到代码变更后，会使用你指定的 Node.js 版本自动重新构建和部署。

💎 总结​

你遇到的问题是 Node.js 版本不匹配，而不是 Cloudflare 系统版本老旧。最简单的修复方法是设置 NODE_VERSION 环境变量为 20 或 22，或者将 Pages 项目的 Build system version 切换到 v3。

📖 额外参考​

Cloudflare 官方文档中详细说明了如何覆盖构建语言和工具的默认版本，以及 Docusaurus 的部署流程。