网站Logo
    首页 / 详情
Site icon

Docusaurus

基本信息

文档手册 知识库
访问
Docusaurus 网站截图预览

工具详情

Docusaurus 全指南

官网： https://docusaurus.io/zh-CN/

定义： Meta（原 Facebook）开源、基于 React 的静态文档站点生成器，主打内容建站、快速搭建文档/博客官网。

一、平台介绍

Docusaurus 是 Meta 开源、MIT 开源协议的现代化静态站点生成工具。2017 年首发，当前主流为 V3 版本。

  • 核心设计： 文档即代码，只用 Markdown/MDX 写内容，自动生成 SPA（单页应用）静态网站。
  • 底层技术： 基于 React + Webpack，构建后输出纯静态 HTML/CSS/JS，可部署至任意静态服务器。
  • 设计初衷： 解决开源项目重复搭建文档站、重复造轮子的问题。Redux、React Native、Testing Library、IOTA、Temporal 等知名项目官方文档均使用本框架。
  • 定位： 不止用于技术文档，还能制作产品官网、知识库、个人博客、教程站点。

二、主要核心功能

1. MDX 文档引擎（核心）

  • 内容支持： 原生支持 Markdown 和 MDX。MDX 可在文档内嵌入 React 组件、交互式代码块。
  • 渲染体验： 普通 md 文档直接渲染网页，无需手写 HTML。
  • 扩展语法： 内置文档提示块、代码高亮、Mermaid 流程图、目录锚点（右侧 TOC）等。

2. 文档版本化

  • 功能： 一键生成多版本文档，适配软件迭代。
  • 操作： 执行 docusaurus docs:version 2.0，用户可在顶部下拉菜单切换 V1/V2/V3 历史文档，文档发版与产品版本一一对应。

3. 多语言国际化（i18n）

  • 功能： 开箱即用本地化，支持 Crowdin/Git 批量翻译。
  • 实现： 文档按语种存放，网站一键切换中英文或多语言，支持独立部署不同语言站点。

4. 内置全文搜索（Algolia）

  • 搜索： 原生集成 Algolia DocSearch，开源项目免费申请搜索索引，实现全站内容秒搜。
  • 私有化： 私有项目可付费升级 Algolia 商业版。

5. 博客 + 官网一体化

  • 博客模块： classic 模板自带博客功能，/blog 目录写 md 自动生成博文列表。
  • 独立页面： src/pages 可自定义独立页面，快速制作产品首页、关于页。

6. 主题与暗黑模式

  • 外观： 默认主题自带亮色/暗黑一键切换，支持自定义 CSS。
  • 深度定制： 通过 Swizzle 机制修改 React 组件，深度定制页面布局、导航、侧边栏。

7. 插件扩展生态

  • 插件架构： 评论、统计、图片优化、API 文档生成、RSS 订阅等均可通过第三方插件接入。
  • 数据复用： 支持复用已有插件数据。

8. 自动化部署

  • 产物： 构建产物为 build 纯静态文件夹。
  • 部署： 支持一键部署至 GitHub Pages、Vercel、Netlify 或 Nginx 服务器。

三、适用人群

  1. 开源项目开发者： 开源库、组件、框架维护者，快速搭建开源官方文档（如 Redux、React 生态通用选型）。
  2. 企业产品/研发团队： 产品帮助文档、API 手册、内部知识库、运维手册。
  3. 个人博主/技术作者： 技术博客、读书笔记、个人知识库站点。
  4. 内容运营/培训机构： 在线教程、课程文档、产品官网。
⚠️ 不适合人群： 需要纯在线协作编辑文档的用户（如石墨/飞书文档模式）。Docusaurus 采用源码 +Markdown 离线编写、静态部署模式。

四、免费与付费详情

✅ Docusaurus 框架本体：永久 100% 免费

  • 协议： MIT 开源协议，无任何软件授权费。
  • 限制： 无项目数量限制，无商用收费。个人/企业/商业项目可随便商用、二次修改源码。
  • 自带功能： 基础主题、文档/博客/版本/多语言/搜索（开源版）全功能免费。
  • 搜索： 开源项目可申请 Algolia DocSearch 免费索引；私有商业站点 Algolia 按需付费升级。

⚠️ 潜在自费项（非框架收费）

  • 服务器与域名：免费部署： GitHub Pages（公开仓库）、Vercel 免费套餐、Netlify 免费套餐。
  • 付费： 自有云服务器、独立域名、Vercel/Netlify 企业套餐（针对大流量站点）。
  1. 定制开发： 深度定制页面、自研插件需前端人力成本。
  2. 第三方增值服务： Algolia 商业搜索、付费主题、评论服务（Giscus 免费，Disqus 付费）。

五、完整使用步骤（快速上手，5 分钟建站）

前置环境

  • 安装 Node.js ≥ 16.14（建议官网下载 LTS 版本）。

1. 初始化新项目（终端执行）

bash

# 经典模板（含文档 + 博客，推荐）
npx create-docusaurus@latest my-doc-site classic

# TS 版本项目（可选）
npx create-docusaurus@latest my-doc-site classic --typescript
# 经典模板（含文档 + 博客，推荐）
npx create-docusaurus@latest my-doc-site classic

# TS 版本项目（可选）
npx create-docusaurus@latest my-doc-site classic --typescript

注：my-doc-site 为项目文件夹名，可自定义。

2. 本地预览调试

bash

cd my-doc-site
npm start # 启动本地服务，访问 http://localhost:3000，修改 md 实时刷新
cd my-doc-site
npm start # 启动本地服务，访问 http://localhost:3000，修改 md 实时刷新

3. 核心目录结构（写文档只需关注 2 个文件夹）

├── docs/        # 存放所有技术文档（新建 xxx.md 自动生成页面）
├── blog/        # 博客文章目录，md 文件自动生成博文
├── src/
│   ├── css/
│   │   └── custom.css # 全局自定义样式
│   └── pages/ # 自定义独立页面
├── docusaurus.config.js # 网站全局配置（标题、导航、logo、域名）
├── sidebars.js        # 侧边栏目录配置
├── static/      # 图片、图标等静态资源
├── docs/        # 存放所有技术文档（新建 xxx.md 自动生成页面）
├── blog/        # 博客文章目录，md 文件自动生成博文
├── src/
│   ├── css/
│   │   └── custom.css # 全局自定义样式
│   └── pages/ # 自定义独立页面
├── docusaurus.config.js # 网站全局配置（标题、导航、logo、域名）
├── sidebars.js        # 侧边栏目录配置
├── static/      # 图片、图标等静态资源
  • 新增文档： 在 docs 新建 安装指南.md，重启服务自动生成页面。
  • 修改导航： 在 docusaurus.config.js → themeConfig.navbar 配置菜单。

4. 打包静态文件

bash

npm run build # 生成 build 文件夹（最终上线文件）
npm run build # 生成 build 文件夹（最终上线文件）

5. 部署上线（3 种主流方案）

  1. GitHub Pages（免费）： 配置 config 后执行 npm run deploy 一键推送部署。
  2. Vercel/Netlify（免费）： 绑定 GitHub 仓库，提交代码自动打包部署。
  3. 自建 Nginx 服务器： 将 build 内所有文件上传至网站根目录，配置 Nginx 静态站点。

6. 进阶配置

  • 开启版本： npm run docs:version 1.0.0 生成 V1 文档。
  • 多语言： 使用官方 i18n 命令提取翻译模板，翻译后切换语言。
  • 搜索： 前往 Algolia 官网申请 DocSearch，将 key 填入 config。

六、高频避坑指南（新手必看）

1. 环境相关坑

  1. Node 版本过低： 必须 ≥ 16.14，Node 14 及以下会出现依赖报错、启动失败。建议用 nvm/fnm 切换 Node 版本。
  2. 依赖错乱： 遇到依赖报错，先执行 rm -rf node_modules package-lock.json && npm install 重装依赖。

2. MDX 语法坑（V3 采用 MDX3）

  1. 大括号报错： {} 在文档中被识别为 JS 表达式。写 {key:value} 代码示例时，改用反引号代码块，或转义 {。
  2. 旧版本不兼容： 从 V2 升级 V3 时，用 npx docusaurus-mdx-checker 一键检查所有文档语法错误。

3. 侧边栏&链接报错

  1. 侧边栏 undefined： 文件夹缺少 _category_.json 分类配置文件，或文件名、路径拼写和 sidebars 配置不一致。
  2. 链接失效警告： 构建提示 brokenLinks 时，config 中 onBrokenLinks 临时改为 warn，修正文档内失效链接后改回 error 校验。

4. 部署&访问坑

  1. 本地访问限制： 默认只能 localhost 访问。需要局域网 IP 访问执行 npm start -- --host 0.0.0.0。
  2. 部署后页面空白： 检查 config 的 baseUrl，子域名部署需配置对应路径（如 baseUrl:"/doc/"）。
  3. 国内访问问题： 国内 Vercel 域名可能被墙，建议绑定自有备案域名，或改用 Cloudflare/国内静态托管。

5. 定制开发坑

  1. 不要修改 node_modules： 自定义组件用 swizzle 命令弹出源码修改，升级版本不会覆盖自定义代码。
  2. 暗黑模式样式： 自定义 CSS 写在 src/css/custom.css，避免覆盖框架原生变量。

6. 搜索相关坑

  • 审核周期： Algolia 免费索引审核周期 1~3 天，上线前先关闭搜索，审核通过再填入配置。
  • 私有站点： 私有站点无法免费申请 Algolia，建议改用本地 lunr 离线搜索插件。

七、补充：同类选型对比

  • GitBook： 以 SaaS 付费为主，支持在线编辑；Docusaurus 为源码本地编写、全免费。
  • VitePress： 基于 Vue 技术栈；Docusaurus 基于 React，自定义组件更灵活，版本/国际化功能更强。
  • MkDocs： 基于 Python 栈，定制能力较弱；Docusaurus 前端生态丰富、插件更多。


评论

暂无评论