搜索: 图标 | AI工具链官网

AnythingLLM

一体化人工智能应用程序

知识库

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 服务器。三、适用人群开源项目开发者：开源库、组件、框架维护者，快速搭建开源官方文档（如 Redux、React 生态通用选型）。企业产品/研发团队：产品帮助文档、API 手册、内部知识库、运维手册。个人博主/技术作者：技术博客、读书笔记、个人知识库站点。内容运营/培训机构：在线教程、课程文档、产品官网。⚠️ 不适合人群：需要纯在线协作编辑文档的用户（如石墨/飞书文档模式）。Docusaurus 采用源码 +Markdown 离线编写、静态部署模式。四、免费与付费详情✅ Docusaurus 框架本体：永久 100% 免费协议： MIT 开源协议，无任何软件授权费。限制：无项目数量限制，无商用收费。个人/企业/商业项目可随便商用、二次修改源码。自带功能：基础主题、文档/博客/版本/多语言/搜索（开源版）全功能免费。搜索：开源项目可申请 Algolia DocSearch 免费索引；私有商业站点 Algolia 按需付费升级。⚠️ 潜在自费项（非框架收费）服务器与域名：免费部署： GitHub Pages（公开仓库）、Vercel 免费套餐、Netlify 免费套餐。付费：自有云服务器、独立域名、Vercel/Netlify 企业套餐（针对大流量站点）。定制开发：深度定制页面、自研插件需前端人力成本。第三方增值服务： 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. 本地预览调试bashcd 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. 打包静态文件bashnpm run build # 生成 build 文件夹（最终上线文件） npm run build # 生成 build 文件夹（最终上线文件） 5. 部署上线（3 种主流方案）GitHub Pages（免费）：配置 config 后执行 npm run deploy 一键推送部署。Vercel/Netlify（免费）：绑定 GitHub 仓库，提交代码自动打包部署。自建 Nginx 服务器：将 build 内所有文件上传至网站根目录，配置 Nginx 静态站点。6. 进阶配置开启版本： npm run docs:version 1.0.0 生成 V1 文档。多语言：使用官方 i18n 命令提取翻译模板，翻译后切换语言。搜索：前往 Algolia 官网申请 DocSearch，将 key 填入 config。六、高频避坑指南（新手必看）1. 环境相关坑Node 版本过低：必须 ≥ 16.14，Node 14 及以下会出现依赖报错、启动失败。建议用 nvm/fnm 切换 Node 版本。依赖错乱：遇到依赖报错，先执行 rm -rf node_modules package-lock.json && npm install 重装依赖。2. MDX 语法坑（V3 采用 MDX3）大括号报错： {} 在文档中被识别为 JS 表达式。写 {key:value} 代码示例时，改用反引号代码块，或转义 {。旧版本不兼容：从 V2 升级 V3 时，用 npx docusaurus-mdx-checker 一键检查所有文档语法错误。3. 侧边栏&链接报错侧边栏 undefined：文件夹缺少 _category_.json 分类配置文件，或文件名、路径拼写和 sidebars 配置不一致。链接失效警告：构建提示 brokenLinks 时，config 中 onBrokenLinks 临时改为 warn，修正文档内失效链接后改回 error 校验。4. 部署&访问坑本地访问限制：默认只能 localhost 访问。需要局域网 IP 访问执行 npm start -- --host 0.0.0.0。部署后页面空白：检查 config 的 baseUrl，子域名部署需配置对应路径（如 baseUrl:"/doc/"）。国内访问问题：国内 Vercel 域名可能被墙，建议绑定自有备案域名，或改用 Cloudflare/国内静态托管。5. 定制开发坑不要修改 node_modules：自定义组件用 swizzle 命令弹出源码修改，升级版本不会覆盖自定义代码。暗黑模式样式：自定义 CSS 写在 src/css/custom.css，避免覆盖框架原生变量。6. 搜索相关坑审核周期： Algolia 免费索引审核周期 1~3 天，上线前先关闭搜索，审核通过再填入配置。私有站点：私有站点无法免费申请 Algolia，建议改用本地 lunr 离线搜索插件。七、补充：同类选型对比GitBook：以 SaaS 付费为主，支持在线编辑；Docusaurus 为源码本地编写、全免费。VitePress：基于 Vue 技术栈；Docusaurus 基于 React，自定义组件更灵活，版本/国际化功能更强。MkDocs：基于 Python 栈，定制能力较弱；Docusaurus 前端生态丰富、插件更多。

知识库