跳到主要内容

Docusaurus 单站点双语言部署

这是本站的默认部署方式。一个构建产物里同时包含中文和英文两个 locale，中文页面放在根路径，英文页面放在 /en 前缀下。

适用场景​

使用单站点双语言部署时，整个站点只有一个入口域名，例如：

https://docs.nevergpdzy.cn

路径结构如下：

/docs/intro        -> 中文文档
/blog              -> 中文博客
/en/docs/intro     -> 英文文档
/en/blog           -> 英文博客

这种方式最符合 Docusaurus 默认 i18n 输出结构。语言切换使用 Docusaurus 原生 localeDropdown，英文链接也继续带 /en 前缀。

构建命令​

默认构建命令是：

npm run build

这个命令会先生成站点统计，再执行完整的 Docusaurus 双语言构建：

npm run generate:site-stats && docusaurus build

构建完成后，产物目录是 build。中文页面在 build 根目录下，英文页面在 build/en 下。

环境变量回退规则​

本站同时支持 ESA Pages 双项目单语言部署。为了避免误配置，单语言独立域名模式必须同时满足两个条件：

SITE_URL 已设置
SINGLE_LOCALE_DEPLOY 已设置

只要缺少其中任意一个，就按单站点双语言部署处理。

这意味着：

  • url 使用默认站点地址。
  • Navbar 继续使用 Docusaurus 原生 localeDropdown。
  • Footer 等手写链接在英文 locale 下继续生成 /en/docs/intro、/en/blog。
  • 构建时如果运行 npm run build，仍然生成完整双语言产物。

注意，回退规则只控制配置和链接逻辑。最终构建几个语言，仍由构建命令决定。要生成双语言产物，必须运行 npm run build。

ESA Pages 文件数风险​

完整双语言构建会把两个 locale 都放进同一个 build 目录。如果托管平台按纯文件数量统计，当前产物低于 2000 个文件；如果平台把目录也算作上传条目，总条目会更高。

本地统计命令：

Get-ChildItem build -Recurse -File | Measure-Object
Get-ChildItem build -Recurse -Directory | Measure-Object

如果 ESA Pages 因总条目数拒绝部署，就改用双项目单语言部署。

部署检查​

上线前至少检查：

  1. npm run build 能完整成功。
  2. build/en 存在。
  3. /docs/intro 能访问中文文档。
  4. /en/docs/intro 能访问英文文档。
  5. Navbar 的语言切换仍然使用原生下拉。
  6. Footer 的英文链接仍然带 /en 前缀。
  7. sitemap.xml 和站点域名一致。