Docusaurus 文档版本、i18n 与部署治理手册

高谷深陵大约 4 分钟约 1143 字

Docusaurus 版本、i18n 与 React 构建链文档、版本快照和翻译资源经插件、主题与 React 静态构建形成多入口站点。高清原图

Docusaurus 适合需要 docs、blog、版本文档、i18n 和 React 生态扩展的站点。能力越多，事实源也越多：当前文档、冻结版本、翻译文件、侧栏、插件和主题都可能改变路由与输出。团队必须定义版本和语言的生命周期，不能只初始化一个示例站点。

初始化并确定站点对象

脚手架可以创建 classic 模板，随后固定 Node、包管理器和依赖锁。站点 URL 与 baseUrl 是不同配置：前者表达域名，后者表达部署路径，两者共同影响 canonical URL 和资源地址。

npx create-docusaurus@latest handbook classic
cd handbook
npm run start
npm run build
npm run serve

docs、blog、pages 和 static 分别承担不同内容入口。关闭不用的插件比保留空目录更清楚，也能减少路由和构建依赖。

站点配置控制 URL、baseUrl、i18n、插件和主题；sidebars 组织文档导航；React 组件与 MDX 承担增强。普通 Markdown 的格式规则回到家族 19 的 Markdown，MDX 的可执行内容边界回到 MDX。

export default {
  url: 'https://docs.example.invalid',
  baseUrl: '/handbook/',
  i18n: {defaultLocale: 'zh-CN', locales: ['zh-CN', 'en']},
}

正向验证从默认语言首页走到一篇文档和静态资源，再切换另一语言。反例删除翻译键或配置错误 baseUrl，预期构建或部署 smoke 能定位失败。

版本命令会复制当前 docs 与侧栏形成站点内快照，后续修改当前文档不会自动更新旧版本。只有仍需用户访问和支持的产品版本才值得进入站点版本；无期限复制会扩大翻译、链接和搜索成本。

docs/                 当前文档
versioned_docs/       冻结版本内容
versioned_sidebars/   冻结版本导航
versions.json         可见版本入口

退役版本先提供迁移提示，再从导航、索引和发布中清理。历史证据可以归档，但不应继续出现在默认搜索结果里误导读者。