部署 Docusaurus 站点
Meta 的 React 文档 SSG，构建输出部署到任何静态主机，含 i18n 和版本管理。
平台进阶
为什么
Docusaurus 是 Meta 文档框架，驱动 React、Jest、Babel 文档。开箱即用提供版本管理、i18n、MDX 和插件生态 — 适合大型项目文档。
平台即服务采用率 2024 年增长 24%，团队从虚拟机管理转向 git push 部署。the cloud infrastructure market reached $330B in 2024, growing 22% year-over-year (Synergy Research)，PaaS 层捕获了大多数新工作负载。
何时使用
版本化项目文档、API 参考和多语言站点用 Docusaurus。小文档避免 — VitePress 更轻。
如何做
1. 构建 — npm run build 输出 build/
2. 部署 — 上传 build/ 到任何静态主机
3. 版本 — docusaurus docs:version 1.0
4. i18n — docusaurus write-translations --locale fr
5. Base — docusaurus.config.js 设 url 和 baseUrl
6. 搜索 — @docusaurus/preset-classic 含 Algolia 选项
示例
// docusaurus.config.js
module.exports = {
title: "My Site",
url: "https://myapp.com",
baseUrl: "/docs/",
presets: [["@docusaurus/preset-classic", {}]],
i18n: { defaultLocale: "en", locales: ["en", "fr"] },
};
// 部署：npm run build && npx wrangler pages deploy build
常见问题
- ⚠baseUrl 不匹配 — 资源 404，设为匹配部署子路径
- ⚠版本文档膨胀 — 每版本复制所有文档，清理旧版本
- ⚠环境间配置漂移 — 使用基础设施即代码（Terraform/Pulumi）保持 dev/staging/prod 一致
最佳实践
- ✓设 includeCurrentVersion: false 跳过当前版本目录 — 更清晰结构
- ✓大文档配 Algolia DocSearch — 本地搜索超 500 页不扩展
- ✓设置健康检查和优雅关闭 — 处理 SIGTERM 以在退出前排空进行中的请求