🔧 文档框架对比

维度	Docusaurus	Mintlify	Nextra	GitBook	Notion
开源	✅ MIT	❌ SaaS	✅ MIT	❌ SaaS	❌ SaaS
自部署	✅	❌	✅	❌	❌
技术栈	React+MDX	MDX	Next.js+MDX	Git+Markdown	自有编辑器
设计质量	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
版本化文档	✅ 内置	✅	⚠️ 需配置	✅	❌
全文搜索	Algolia	AI 搜索	Pagefind	内置	内置
API 交互文档	需插件	✅ 内置	需插件	✅ 内置	❌
i18n	✅ 内置	✅	Next.js i18n	✅	❌
博客支持	✅ 内置	❌	✅	❌	✅ (发布功能)
SEO	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐
定制性	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐	⭐
学习曲线	中等	低	低-中	低	极低
月成本	$0	$0-$120+	$0	$0-$6.5/人	$0-$10/人

Docusaurus — Meta 出品，文档框架的事实标准

GitHub Stars: 58K+ | 使用者: Redux, Jest, React Native, Temporal, IOTA

Docusaurus 由 Meta（Facebook）开发维护，是目前最成熟的开源文档框架。React Native 维护者 Hector Ramos 说："迁移到 Docusaurus 后，开源贡献量暴增。"

# 5 分钟搭建 Docusaurus 站点 npx create-docusaurus@latest my-website classic cd my-website npm start # 项目结构 my-website/ ├── blog/ ← 博客（SEO 增长引擎） ├── docs/ ← 文档（Markdown/MDX） ├── src/ ← 自定义 React 组件 ├── static/ ← 静态资源 ├── docusaurus.config.js ← 主配置 └── sidebars.js ← 侧边栏配置 # docusaurus.config.js 关键配置 module.exports = { title: 'My Project', tagline: 'Build something amazing', url: 'https://docs.example.com', baseUrl: '/', // 版本化文档 presets: [ [ '@docusaurus/preset-classic', { docs: { sidebarPath: require.resolve('./sidebars.js'), lastVersion: 'current', versions: { current: { label: 'v2.x' }, '1.x': { label: 'v1.x' }, }, }, blog: { blogTitle: 'Blog' }, }, ], ], // Algolia 搜索 themes: ['@docusaurus/theme-search-algolia'], // i18n 国际化 i18n: { defaultLocale: 'zh-Hans', locales: ['zh-Hans', 'en'], }, };

🌿 Mintlify 深度解析

Mintlify — 最美的文档体验，没有之一

使用者: Perplexity, Supabase, Mercado Pago, 数百家 SaaS

Mintlify 的核心理念是"文档应该是产品的一部分"。它提供开箱即用的最美设计、AI 搜索、API 交互演示。但它是 SaaS 服务，不是开源工具。

# Mintlify 配置 (mint.json) { "name": "My Project Docs", "logo": { "dark": "/logo-dark.svg", "light": "/logo-light.svg" }, "favicon": "/favicon.png", "colors": { "primary": "#6c5ce7", "light": "#a29bfe", "dark": "#6c5ce7" }, "topbarLinks": [ { "name": "Dashboard", "url": "https://app.example.com" } ], "tabs": [ { "name": "Documentation", "url": "docs" }, { "name": "API Reference", "url": "api" }, { "name": "Examples", "url": "examples" } ], "navigation": [ { "group": "Getting Started", "pages": ["docs/quickstart", "docs/installation"] }, { "group": "API", "pages": [ { "group": "Authentication", "pages": ["api/auth/api-keys", "api/auth/oauth"] }, "api/users", "api/projects" ] } ], "footerSocials": { "twitter": "https://twitter.com/example", "github": "https://github.com/example" }, "openapi": "https://api.example.com/openapi.json" }

⚡ Nextra 深度解析

Nextra — Next.js 开发者的最佳选择

GitHub Stars: 12K+ | 使用者: SWR, Tailwind CSS, Vite, Prisma

如果你已经用 Next.js，Nextra 是最自然的选择。它复用 Next.js 的所有能力（图片优化、链接预取、ISR），同时提供文档主题。Pagefind 全文搜索零配置，速度极快。

# Nextra 搭建 npm install nextra nextra-theme-docs # next.config.mjs import nextra from 'nextra' const withNextra = nextra({ theme: 'nextra-theme-docs', themeConfig: './theme.config.tsx', }) export default withNextra({ // Next.js 配置 }) # theme.config.tsx export default { logo: My Project, project: { link: 'https://github.com/user/repo' }, docsRepositoryBase: 'https://github.com/user/repo/tree/main', search: { placeholder: '搜索文档...' }, feedback: { content: '有问题？提 Issue →' }, editLink: { text: '在 GitHub 上编辑此页 →' }, toc: { title: '本页目录' }, footer: { text: '© 2024 My Project' }, } # 文档结构（基于文件系统的路由） pages/ ├── index.mdx ← 首页 ├── docs/ │ ├── _meta.json ← 页面元数据（标题、顺序） │ ├── getting-started.mdx │ ├── installation.mdx │ └── api/ │ ├── _meta.json │ ├── auth.mdx │ └── users.mdx

🎯 选型决策树

你的场景是什么？ │ ├─ 大型开源项目，需要版本化+i18n → Docusaurus │ (React Native, Redux 的选择) │ ├─ SaaS 产品，追求极致体验 → Mintlify │ (Supabase, Perplexity 的选择) │ ├─ Next.js 项目，想复用生态 → Nextra │ (SWR, Tailwind CSS 的选择) │ ├─ 非 React 技术栈，用 Git 管理 → GitBook │ (传统文档的选择) │ ├─ 快速原型，不需要自定义 → Notion + Super.so │ (MVP 阶段的选择) │ └─ 完全自定义需求 → Next.js/Nuxt + MDX 自己搭 (Stripe 的选择 — 完全自建)

💡 迁移成本警告

文档框架的迁移成本极高——不只是重新格式化 Markdown，还有：自定义组件、搜索索引、SEO URL 结构、版本化逻辑、贡献者工作流。选型时请想清楚 3 年后的需求。最安全的默认选择是 Docusaurus（最成熟）或 Nextra（最灵活），因为它们开源且自部署，不会被供应商锁定。

📊 全面对比

🦖 Docusaurus 深度解析