Docusaurus 文档站 6 步实操：含配置模板 + 8 个 MDX 组件 + 部署脚本 + 报错解决，做开发者文档站的最优解。
Docusaurus 文档站搭建 6 步：开发者文档首选
Docusaurus 是 Facebook（现 Meta）开源的静态文档站生成器，专门为开发者文档设计，搜索、侧边栏、版本管理、国际化全内置，比 WordPress 适合做技术文档，比 Jekyll 适合做大型文档库。
一、Docusaurus 是什么
Docusaurus 是一个 React 写的静态网站生成器，最大的特点是：把所有文档相关的烦人事都帮你做了。你只需要写 Markdown 文档，侧边栏自动生成，搜索自动启用，版本切换自动支持，连主题都默认长得不错。
对比其他文档方案：
- **vs GitBook**：Docusaurus 免费 + 主题完全可定制，GitBook 团队版贵
- **vs VuePress**：Docusaurus 用 React，VuePress 用 Vue，按你栈选
- **vs MkDocs**：Docusaurus 功能更全，MkDocs 简单但插件少
- **vs Notion**：Notion 私有数据不好导出，Docusaurus 全在你 Git 仓库
二、6 步搭建流程
### 第 1 步：装 Node.js 18+
Docusaurus 3.x 要求 Node 18 或更高版本。
到 nodejs.org 下载安装包，一路 Next 就行。装完打开终端：
node -v
npm -v
能看到版本号说明装好了。
### 第 2 步：用脚手架创建项目
打开终端，进入你想放项目的目录，执行：
npx create-docusaurus@latest my-docs classic
这条命令会：
- 下载 Docusaurus 3.x
- 创建一个叫 my-docs 的目录
- 用 classic 模板初始化（classic 含博客 + 文档 + 首页全套）
然后：
cd my-docs
npm install
装依赖。
### 第 3 步：改站点配置
打开 `docusaurus.config.js`，重点改这几项：
title: '我的技术文档'
tagline: '开发者文档库'
url: 'https://你的域名.com'
baseUrl: '/'
organizationName: '你的GitHub用户名'
projectName: '仓库名'
`url` 和 `baseUrl` 决定最终生成的网站 URL，配错会导致静态资源 404。
### 第 4 步：写文档
所有文档放在 `docs/` 目录下。比如 `docs/intro.md`：
---
sidebar_position: 1
---
介绍
这是文档的首页内容。
每个 .md 文件的开头 --- 之间的内容叫 frontmatter，控制这篇文档在侧边栏的位置、分类、是否草稿等。
写技术文档时常用的 frontmatter：
- sidebar_position：决定侧边栏顺序
- sidebar_label：自定义显示名称
- sidebar_class_name：自定义 CSS 类
- tags：打标签（启用标签系统后生效）
### 第 5 步：配侧边栏
打开 `sidebars.js`，配置侧边栏菜单：
module.exports = {
docs: [
'intro',
{
type: 'category',
label: '入门指南',
items: ['quick-start', 'install', 'config'],
},
{
type: 'category',
label: '进阶',
items: ['advanced/intro', 'advanced/deploy'],
},
],
};
这样配出来的侧边栏分两层，分类清晰。
### 第 6 步：部署
构建静态站：
npm run build
会生成 `build/` 目录，里面是纯 HTML + CSS + JS。
部署选项：
**Vercel（推荐）**：
1. 推代码到 GitHub
2. 登录 vercel.com
3. Import Project
4. 自动检测 Docusaurus 项目，一键部署
5. 几分钟后分配 https://xxx.vercel.app 域名
**GitHub Pages**：
1. 改 `docusaurus.config.js` 配 organizationName + projectName
2. 配 GitHub Actions 推代码自动部署
3. 推代码触发部署
**Netlify**：
1. 推代码
2. Netlify 导入
3. Build command: npm run build
4. Publish directory: build
5. 自动部署
三、3 个常见坑
### 坑 1：sidebar_position 冲突
两篇文档 sidebar_position 都设了 1，会被覆盖。改成唯一值。
### 坑 2：mdx 语法错误
Docusaurus 文档支持 MDX（Markdown + JSX），但 JSX 标签必须用花括号包起来：
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
不是标准 Markdown 写法，复制粘贴过来要改。
### 坑 3：搜索不生效
Docusaurus 3.x 默认带本地搜索（基于 lunr），装完就能用。如果用 Algolia 搜索（更专业），要单独申请 Algolia 账号配 App ID + API Key + indexName。
四、附件包说明
附件包内含：
- **Docusaurus 完整本地环境**（Node.js + npm 离线安装指南）
- **3 套主题包**（classic 默认 / 暗色模式 / 极简白）
- **docusaurus.config.js 完整配置模板**（含 SEO + GA + 多语言）
- **sidebars.js 侧边栏配置示例**（3 层菜单 + 分类 + 标签）
- **MDX 组件示例**（Tabs / CodeBlock / Details 等 8 个常用组件）
- **部署脚本**（Vercel + GitHub Pages + Netlify 三种方案）
- **常见报错清单**（10 个坑 + 解决方案）
五、写在最后
Docusaurus 是 2026 年做技术文档站的最优解：免费、强大、SEO 好、迁移容易。开源项目、SDK 文档、产品手册都能 hold 住。
跟着这 6 步走，半天就能把文档站搭起来。
