做技术写作这几年我给团队搭过不少文档站从最早的GitBook到Hexo再到后来专门为开源项目写文档换来换去踩的坑能写满一页纸。直到换到Docusaurus才算是把文档这件事真正理顺了——配置省心、默认主题够用、版本化原生支持最关键是它一套方案能把“写文档”和“做产品展示页”一起解决。这篇就从我做文档站的实际经验出发把Docusaurus从核心原理到完整落地讲透。如果你正在选型或者已经被各类静态站生成器的配置折腾到抓狂这篇应该能帮你节省好几天调研时间。无论你是刚开始接触文档站的纯新手还是想从别的工具迁移的老手按着下面的思路走基本不会走弯路。1. 为什么我推荐Docusaurus做文档站1.1 一句话讲清Docusaurus是什么Docusaurus是Facebook开源的一款静态站点生成器目前主流版本是3.x。它专门为“软件文档”这个场景设计用React构建页面用Markdown或MDX写内容构建后直接输出纯静态的HTML/CSS/JS文件放到任意Web服务器上就能访问。它和Hexo、VuePress这帮工具最大的区别在于“定位”二字。Hexo本质是个博客框架你要拿它做文档侧边栏、版本切换、代码块样式、文档搜索全得自己找插件做完之后你会发现三分之二的工作量是在跟插件较劲。而Docusaurus从一开始就把文档站的“标配功能”做进了核心左侧可折叠侧边栏、上一页/下一页导航、面包屑、全文搜索对接Algolia、多版本文档、国际化、Sitemap、RSS甚至还包括一个完整的博客模块。我用一个类比来形容Hexo给你一块地你想盖什么自己来Docusaurus给你一套带精装修的户型图你只需要往里面摆家具。对绝大多数团队来说后者的效率高得多。1.2 和其它工具怎么选不纠结市面上文档站的生成器不少我实际用过或者深度调研过的有这么几类VuePress / VitePress、GitBook、MkDocs、Gatsby以及直接手写React/Vue页面伺候的“硬核方案”。工具技术栈文档特色上手成本适合场景DocusaurusReact版本化、侧边栏、MDX、搜索一体化低软件项目文档、开源项目官网VuePress / VitePressVue简洁、默认主题漂亮低Vue生态项目、轻量文档GitBookNode.js同步GitHub渲染操作简单极低非技术团队协作写文档MkDocsPython借助Markdown扩展适合API文档中低Python项目、技术规范文档GatsbyReact高度可定制插件生态丰富高内容型站点、复杂官网说个我自己的取舍教训。早年在团队里用GitBook写内部文档非技术同事用起来确实顺手但到了开源项目对外发布阶段完全不够用没有版本化支持搜索结果一塌糊涂前端资源还经常加载慢。后来又尝试VuePress文档写得舒服但要版本化、要自定义首页结构多多少少还是得自己改主题。Docusaurus之所以能留下来核心就三点一是基于React你想要任何定制都能用组件方式实现下限低上限高二是版本化是内置的一等公民不需要魔改三是生态由Facebook团队维护长期使用不用太担心中途跑路。当然如果你的文档非常简单比如十来个页面、发布一次就不怎么更新VuePress甚至GitBook也完全够用不必为了用而用。2. 核心概念和原理弄懂这些不容易踩坑2.1 一个文档页面的完整生命周期很多人在Docusaurus里写文档脑子里装的还是“在文件夹里放个md文件”。这个理解方向没错但要知道中间还有一层“元数据加工”的逻辑否则经常会困惑“为什么我的页面没出现在侧边栏”“为什么标题怪怪的”。一个文档页面在Docusaurus里通常长这样--- id: installation title: 安装指南 sidebar_position: 1 --- # 安装指南 这一节介绍如何安装...最上面的---包裹的部分叫Front Matter前置元数据。它决定了这个页面在站点里的行为title控制浏览器标签和文档标题id是页面在侧边栏和路由中的唯一标识sidebar_position控制它在自动生成的侧边栏里排第几。这些元数据会被解析进站点数据层最终参与生成sidebar、页面路由和面包屑导航。这里的核心原理是Docusaurus会扫描docs目录下的所有Markdown文件读取Front Matter和文件标题生成一个“文档内容树”。你不需要手动注册路由文件路径本身就是路由。例如docs/guide/install.md对应的访问路径就是/docs/guide/install。我在实际使用中强烈建议每个文档文件都要写好sidebar_position这比按文件名字母排序要可控得多。很多人忽略这个字段结果侧边栏里的顺序完全不是想要的尤其是中文文件名或带数字前缀的文件名排序规则很容易出乎意料。2.2 版本化到底在做什么版本化是Docusaurus最容易让人犯迷糊、但又是最亮眼的功能。很多团队每次发版就把文档整个复制一份最后目录一堆v1、v2-fix、final_v2混乱不堪。Docusaurus的版本化思路清晰地多。在项目根目录执行npm run docusaurus docs:version 1.0它会做两件事把当前docs目录的内容快照到versioned_docs/version-1.0/同时生成一份versioned_sidebars/version-1.0-sidebars.json把当前侧边栏结构固定下来。从此刻起docs目录里的更新默认对应“下一次发布版本”而version-1.0目录里的内容被冻结成为一个独立可切换的版本。版本切换器会出现在文档页顶部用户可以在不同版本间跳转。这个机制对开源项目极其重要——用户装的是1.0版本就应该看到1.0的文档而不是明明写着2.0的API却在1.0的环境里瞎试。这里有一个我踩过的坑版本快照不是“全量智能同步”。比如你之后在docs里删掉了一个页面旧版本versioned_docs/version-1.0/里那个页面依然存在这是特性不是bug因为历史版本必须保持原样。但如果你改动了某个公共导航比如把“快速开始”从第二个位置换到了第三个历史版本里的侧边栏也需要手动去versioned_sidebars里调整。2.3 搜索不是白送的默认情况下Docusaurus的文档站点没有即时全文搜索。你看到很多Docusaurus站点右上角带搜索框其实是接入了Algolia DocSearch。Docusaurus官方推荐的方式是使用Algolia DocSearch。它对开源项目是免费的但需要你按流程提交申请Algolia那边审核通过后会给你一个apiKey和indexName然后你在docusaurus.config.js里配置themeConfig: { algolia: { appId: 你的AppID, apiKey: 你的搜索API Key, indexName: 你的索引名, } }注意一个关键点Algolia的爬虫服务会定期抓取你的站点抓取频率取决于配置。不是配置完马上就能搜一般要等爬虫跑完一轮可能几十分钟到几小时索引才会生效。如果你的文档是内部系统、无法公开访问那Algolia官方DocSearch基本申请不下来。此时可以用社区方案比如docusaurus-search-local这类本地搜索插件。它的实现原理是在构建时把文档内容打包成静态索引搜索在浏览器本地完成不依赖任何外部服务适合文档量不大几千页以内的站点。缺点是没有Algolia那种“搜索联想和纠错”的智能体验但胜在省事、可控、离线可用。3. 从零搭一个能上线的文档站3.1 初始化项目三分钟跑起来我直接用官方脚手架操作按照下面的命令一步步来npx create-docusauruslatest my-docs classic cd my-docs npm run start这里classic是官方预设主题包已经集成了文档、博客、首页、搜索框接口这四个模块。启动后访问http://localhost:3000就能看到默认页面。整个目录结构如下my-docs/ ├── blog/ # 博客文章目录 ├── docs/ # 文档目录Markdown/MDX ├── src/ │ ├── components/ # 自定义React组件 │ ├── css/ # 全局样式 │ └── pages/ # 独立页面首页、关于等 ├── static/ # 静态资源图片、favicon等 ├── docusaurus.config.js # 全局配置文件 ├── sidebars.js # 侧边栏配置 └── package.json初次上手我建议大家先不要动src里的React组件把精力放在docusaurus.config.js和docs目录的内容上。依赖node和npm就能跑不需要额外装什么重量级服务。实测下来开发热更新速度很快保存文档内容后基本1秒内刷新。3.2 配置导航和侧边栏把结构立起来站点整体的“骨架”都在docusaurus.config.js。核心字段需要关注这几个module.exports { title: 产品文档, tagline: 让每个用户都能快速上手的文档中心, url: https://docs.example.com, baseUrl: /, onBrokenLinks: throw, onBrokenAnchors: warn, themeConfig: { navbar: { title: 产品文档, items: [ { to: /docs/intro, label: 文档, position: left }, { to: /blog, label: 博客, position: left }, { type: docsVersionDropdown, position: right }, ], }, footer: { links: [ { title: 文档, items: [ { label: 快速开始, to: /docs/intro }, { label: API参考, to: /docs/api/overview }, ], }, ], }, }, };navbar对应顶部导航footer是页脚。注意type: docsVersionDropdown这一项它会在导航栏右侧自动生成版本下拉框不用自己写任何React代码。侧边栏配置在sidebars.js里最常用的写法有两种。第一种是自动生成适合内容不复杂、按目录结构组织的情况module.exports { tutorialSidebar: [ { type: autogenerated, dirName: . }, ], };第二种是手动指定适合对顺序和分组有极致要求的情况module.exports { docs: [ { type: category, label: 入门, items: [intro, installation, quickstart], }, { type: category, label: 指南, items: [guide/deploy, guide/config, guide/api], }, ], };我个人推荐混合策略草稿阶段用autogenerated跑通内容稳定后再改成手动编排把相似主题归组。这样既保证了前期的推进速度也保证了最终阅读体验。3.3 自定义首页与主题样式摆脱“默认脸”Docusaurus默认首页是官方模板的样子一眼就能认出来。如果你的站点是对外产品官网还是建议自定义首页。首页对应的文件在src/pages/index.js它本质上是一个React组件你用任何React组件库都能重写。比如要放一个产品特性区可以直接这样写一个简单的组件import React from react; import Layout from theme/Layout; function Feature({ title, description }) { return ( div classNamefeature h3{title}/h3 p{description}/p /div ); } export default function Home() { return ( Layout title首页 section classNamehero h1让文档成为产品的竞争力/h1 p用Docusaurus搭建结构清晰、维护高效的技术文档中心/p /section div classNamefeatures Feature title版本化 description每次发版自动归档用户永远看到对的文档 / Feature titleMDX description在Markdown里嵌入组件示例代码不再静态 / Feature title国际化 description内置多语言支持翻译起来不费劲 / /div /Layout ); }样式上Docusaurus用CSS变量做主题定制。在src/css/custom.css里改几个变量整个站点的配色就会跟着变:root { --ifm-color-primary: #2563eb; --ifm-color-primary-dark: #1e4bb8; --ifm-color-primary-light: #3b82f6; --ifm-navbar-height: 64px; --ifm-font-family-base: -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif; }如果只是换换颜色改CSS变量就够了。想彻底改布局结构就需要用“Swizzle”功能把默认组件抽出来改。这个功能强大但也有风险——升级Docusaurus版本时被Swizzle的组件不会自动同步更新。我的建议是能不改默认组件就尽量不改这是我在版本升级时被折腾过好几次才得出的教训。3.4 部署到服务器或者三方平台Docusaurus构建产物是纯静态文件跑一下构建命令输出到build目录npm run build之后把build目录里的内容扔到任何静态文件服务器就行。我用过三种方式比较稳定GitHub Pages开源项目首选。因为Docusaurus官方有专门的部署文档只需要在GitHub Actions里配置好push到gh-pages分支即可。Vercel / Netlify连接仓库后自动识别构建命令设为npm run build输出目录设为build剩下交平台处理。自有服务器用Nginx托管build目录注意做SPA的try_files配置避免刷新404。如果部署路径不是网站根目录比如https://example.com/docs/一定要改docusaurus.config.js里的两个字段module.exports { url: https://example.com, baseUrl: /docs/, };这里我踩过坑忘了改baseUrl就部署结果页面CSS和JS全404页面内容“裸奔”。所以任何部署场景先确认url和baseUrl拼出来的最终访问路径再跑npm run build。4. 进阶玩法文档站点也能做出花来4.1 MDX让文档“活”起来写文档最怕什么怕读的人看不懂示例。静态示例代码只能看不能跑用户只能靠想象。MDX直接解决了这个问题——它允许你在Markdown里写React组件把可交互的demo直接嵌到文档页面里。比如你想展示一个按钮组件的用法以前只能贴代码jsx Button typeprimary点击/Button 用MDX后可以导入真正的组件并把实例“跑”在文档里import Button from site/src/components/Button; Button typeprimary onClick{() alert(我被点了)}点击/Button用户在页面上看到的不仅是一段代码还是一个可以点击的真实组件。对组件库类文档来说这个体验是质的飞跃。使用MDX需要注意两个问题。一是扩展名必须是.mdx而不是.md否则组件语法不会被解析。二是别在MDX里写太JavaSript的逻辑文档的主要阅读对象还是人组件只是辅助理解不是把文档页面变成单页应用。4.2 关闭博客、只做纯文档站很多团队只需要文档不需要博客。但Docusaurus的classic预设默认包含博客模块会导致构建产物多出/blog路由侧边栏也多出“博客”入口。我自己的项目就遇到过甲方要求站点只展示产品文档不允许有博客栏目于是我把配置精简了一下。在docusaurus.config.js里把preset里的博客配置设为falsepresets: [ [ classic, { docs: { sidebarPath: require.resolve(./sidebars.js), }, blog: false, theme: { customCss: require.resolve(./src/css/custom.css), }, }, ], ],这之后站点就只保留文档模块。顺带把顶部导航里指向/blog的item也删掉基本就干净了。如果你有“多套文档”的需求比如一套面向最终用户、一套面向开发者Docusaurus 3.x的“多实例文档”功能可以把docs拆成两套独立的文档空间每套有自己的侧边栏和导航前缀。配置上略微复杂但基本就是复制一份docs配置换成不同的id和routeBasePath。这个功能我是在做一个数据中台产品时用到的一份API文档做开发指南一份操作手册做用户指南效果很好。4.3 多语言与SEO相关配置多语言这块Docusaurus内置了i18n支持不用额外装插件。在docusaurus.config.js里开启module.exports { i18n: { defaultLocale: zh-Hans, locales: [zh-Hans, en], }, };然后文档目录按语言放好docs/默认是中文i18n/en/docusaurus-plugin-content-docs/current/放英文翻译站点上就会出现语言切换器。注意多语言不是自动翻译而是让同一个人维护多个语言版本的文档框架负责切换和路由内容翻译靠你自己。这听起来像废话但我真遇到过以为“开了配置就自动翻译”的同事。SEO方面Docusaurus做得很省心自动生成每页的title和meta description自带Sitemap插件需要额外开启也内置了Open Graph标签分享到社交媒体时会带出标题、描述和预览图。唯一要留意的是确保每篇文档在Front Matter里写了description字段否则这个页面在搜索引擎里的摘要会自动截取正文开头往往不是你想突出的重点。5. 常见问题与排查技巧实录5.1 构建与运行时的高频报错问的人最多的几个报错我整理了一张表都是我实际遇到或者帮别人排查过的。报错现象主要原因解决办法构建失败提示Broken link文档里引用了不存在的页面或锚点根据报错信息找到对应文件和链接修正路径可临时将onBrokenLinks改为warn样式丢失页面无CSSbaseUrl配置错误检查url和baseUrl拼接后的路径是否与实际部署地址一致本地能访问部署后404部署平台没有做静态目录映射确认构建输出目录为build静态托管平台要设置正确的输出目录导航栏版本下拉框不出现没有执行过docs:version命令至少执行一次版本归档生成versioned_docs搜索框显示但搜不到内容Algolia索引未更新或未配置appId前往Algolia后台查看爬虫是否抓取成功本地搜索插件则要重新构建onBrokenLinks这个配置值得多说一句。Docusaurus构建时默认对失效链接是throw导致构建失败这是官方刻意设计的安全策略——防止文档烂链。但很多新手会在这里直接卡住以为是代码写错了。排查思路很简单报错信息里会给完整的源文件路径和失效链接文本写了个[快速开始](/docs/quick-start)但实际路径是/docs/quickstart这类笔误一眼就能看出来。5.2 版本化操作的经典翻车现场版本化最大的“坑王”是在归档1.0之后继续在docs目录里改内容但用户访问/docs/默认看到的是最新版或者指定版本你以为自己改的是1.0的文档实际改的是“下一版”。结果就是1.0的文档永远停留在旧状态用户反馈“文档和实际API对不上”。排查方式很直接看URL路径。如果路径是/docs/1.0/xxx说明在看归档版本如果路径是/docs/next/xxx或/docs/xxx很可能是最新版本。需要修改历史版本内容时去versioned_docs/version-1.0/里对应文件改就行但要记住这个修改不会同步到其他版本。还有个小技巧版本名未必非得用1.0这种数字版本号。有的团队用迭代代号如v2、2024.12有的项目直接用latest文档和stable文档两个版本都是可以的。版本名的设置会影响URL路径建议一开始就定好命名规则不然后续切换版本时URL结构很乱。5.3 侧边栏显示不正常的几种情况自动生成的侧边栏偶尔会出现“页面没出现”或者“顺序完全不对”的情况。常见原因一是文档页面的Front Matter里没写sidebar_positionDocusaurus会按文件名称字符顺序排列中文/数字/英文混排时特别容易乱二是文件在新目录下没有归属到任何侧边栏顶层目录需要检查这个目录是否被上级目录的autogenerated规则覆盖到了三是手动模式下忘了把某个新页面加进sidebars.js这种情况下构建时会直接报错提示缺失项。我现在的习惯是每个文档页面都显式写上sidebar_position把它当作版本控制的一部分来管理。虽然多写一行元数据看似啰嗦但等你的文档超过几十篇时这些元数据就是侧边栏的“秩序保证”。最后分享一个我自己用了很长时间的小习惯给Docusaurus文档配备一个“文档维护规范”在里面约定清楚Front Matter怎么写、侧边栏怎么编排、版本何时归档。这听起来很“流程化”但文档站点一旦超过100个页面规范就是救命稻草。Docusaurus给了你极高的自由度而自由恰恰需要约束来兜底——否则时间一长文档站还是会重蹈当年那个乱成一锅粥的旧站点的覆辙。