illegalCreed

中文

English

中文

English

Appearance

Docusaurus ​

由 Meta（Facebook） 开源、最早服务于 React 文档站的「React-based 静态文档站生成器」，目前是 React 生态文档圈的事实标准——React / React Native / Jest / Babel / Redux / Prettier 等自家项目以及大量开源库都使用它（如 Algolia DocSearch、Supabase、Hasura、CodeSandbox 等）。Docusaurus 把「文档站」这件事拆成三个一等公民：docs（多版本文档） / blog（博客系统含 RSS / 作者 / 标签） / pages（独立 React 页面），全部基于 MDX——所以你既可以写纯 Markdown，也可以在 Markdown 里直接 import React 组件、写 JSX 表达式、嵌入 <Tabs> / <CodeBlock> 等丰富组件。配套的「versioning」是它最差异化的特性：一条 docusaurus docs:version 1.0 命令就能把当前 docs/ 快照成 versioned_docs/version-1.0/ + versioned_sidebars/，未来发新版本时旧版本继续可访问（/docs/1.0/...），这是 VitePress / Starlight / Nextra 都没有的开箱即用能力。Docusaurus 3.x（最新主线）已经升级到 MDX 3 + React 18 + Node.js 20+ + TypeScript 5.1+，并通过 future.faster 配置项实验性接入 Rspack / SWC / Lightning CSS 等下一代工具链，构建速度有显著提升。整套体系由 classic preset 统一交付——一行 presets: ['classic'] 同时启用 docs / blog / pages / theme / sitemap / Google Analytics 等十多个插件，开箱即用。

评价 ​

优点

  • 多版本文档开箱即用：docusaurus docs:version 一行命令快照当前文档为新版本，旧版本继续可访问（/docs/1.0/... / /docs/2.0/...），是 React Native / Jest 等大型项目首选 Docusaurus 的关键原因
  • i18n 国际化完善：docusaurus write-translations 提取所有可翻译字符串，i18n/{locale}/ 目录组织翻译文件，支持 RTL（阿拉伯语 / 希伯来语），自带 locale switcher
  • MDX 3 一等公民：Markdown 中直接 import React 组件、写 JSX 表达式、export 变量，文档可交互（Tabs / Live CodeBlock / 自定义组件）
  • 生态最成熟：React 生态文档圈的事实标准，Algolia DocSearch 集成开箱即用（免费申请），插件市场丰富
  • Swizzling 机制：docusaurus swizzle 命令可 wrap（包装增强）或 eject（完全替换）任何主题组件，定制深度无上限
  • 三件套统一：docs（多版本文档）/ blog（含 RSS / 作者 / 标签）/ pages（自由 React 页面）由 classic preset 一并交付——任何场景都覆盖
  • 部署支持广：docusaurus deploy 一行命令推 GitHub Pages，Vercel / Netlify 也自动识别，GitHub Actions 工作流官方提供
  • Meta 长期维护：自 2017 年开源至今 8+ 年，团队稳定，3.x 持续优化
  • TypeScript 支持：docusaurus.config.ts + sidebars.ts 完整类型推断，@docusaurus/tsconfig + @docusaurus/module-type-aliases 一站式

缺点

  • 构建偏重：Webpack 5 + React SSR + MDX 编译，大型站点冷启动 / 构建明显慢于 VitePress（中大型站可达分钟级，VitePress 通常秒级）。3.x 的 future.faster 实验性切换 Rspack + SWC 有改善但仍 beta
  • 首屏体积大：React + React Router 18 + Helmet + 主题 JS bundle 约 200KB+（gzip），相比 VitePress 的 ~80KB / Astro 的 ~0KB 偏重
  • MDX 3 严格性：升级到 3.x 后 { / < 字符的解析更严，老内容（v2 兼容）容易踩坑——{value} 会被解释为 JSX 表达式，需要 { 转义或反引号包裹
  • i18n 维护成本：翻译文件量级随版本数 × 语言数 × 文档数爆炸增长，无内置翻译工具集成（要自接 Crowdin）
  • React 强绑定：MDX 中只能用 React 组件，Vue / Svelte 用户无法复用既有组件；要嵌入 iframe 或 web component
  • theme 定制曲线：浅层用 themeConfig 即可，深层需要 Swizzle + 改 React 组件——Vue 用户不熟悉 React 时学习成本高
  • 官方主题选择少：classic 主题是事实唯一选择，缺乏 Starlight / Nextra 那样的现代视觉风格——除非自己 swizzle 改样式
  • vs VitePress / Starlight / Nextra：
    • VitePress：Vue 生态文档首选 / 极快构建 / 但无多版本 / i18n 较弱
    • Starlight（Astro 出品）：现代设计 / 零 JS / 但社区更小 / 无多版本
    • Nextra（Next.js 出品）：React 生态新秀 / Tailwind 风格 / 但功能不及 Docusaurus 全面
    • Docusaurus 仍是「需要多版本 + i18n + 博客 + 文档一体化」场景的最稳健选择

文档地址 ​

Docusaurus 官网 | Docusaurus 文档 | Showcase 案例 | Playground | 社区资源

GitHub 地址 ​

facebook/docusaurus

学习路径 ​

  • 入门：npx create-docusaurus@latest / 模板选择（classic）/ 项目结构 / docusaurus.config.ts 配置全貌 / 第一篇文档（docs/）/ 第一篇博客（blog/）/ 第一个独立 React 页面（src/pages/）/ MDX 入门 / sidebars.ts 配置 / 本地开发与构建 / 部署到 GitHub Pages
  • 指南：文档系统（autogenerated sidebar / frontmatter）/ 博客系统（作者 / 标签 / RSS / Truncate）/ MDX 完整能力（import 组件 / <MDXComponents /> 全局注入）/ 多版本文档（docs:version 命令 + versioned_docs/ + versions.json）/ i18n 国际化（write-translations + i18n/{locale}/）/ Swizzle 主题定制（wrap vs eject）/ Plugin 系统 / Algolia DocSearch / Markdown 增强（admonitions / tabs / code blocks）/ 客户端 API（useDocusaurusContext / <Link /> / <BrowserOnly />）/ 部署到 GitHub Pages / Vercel / Netlify
  • 参考：docusaurus.config.ts 字段全表 / sidebars.ts 完整语法 / Frontmatter 字段速查 / CLI 命令全集（start / build / serve / swizzle / deploy / docs:version / write-translations / write-heading-ids）/ MDX 内置组件（Tabs / TabItem / Admonition / CodeBlock）/ Plugin / Preset / Theme 配置全表 / Hooks（useDocusaurusContext / useLocation / useColorMode）/ 文件约定