跳到主要内容

Docusaurus 单语言单站点部署

单语言单站点部署用于规避 ESA Pages 的静态文件数量限制。核心思路是保留一个 Git 仓库，但创建两个 ESA Pages 项目，每个项目只构建一个 locale。

部署形态​

推荐结构：

中文 Pages 项目 -> https://nevergpdzy.com
英文 Pages 项目 -> https://en.nevergpdzy.com

两个站都部署在域名根路径。英文站不再使用 /en 前缀。

路径结构如下：

https://nevergpdzy.com/docs/intro       -> 中文文档
https://nevergpdzy.com/blog             -> 中文博客
https://en.nevergpdzy.com/docs/intro    -> 英文文档
https://en.nevergpdzy.com/blog          -> 英文博客

构建命令​

中文项目使用：

npm run build:zh

英文项目使用：

npm run build:en

这两个命令都会先生成站点统计，再只构建指定 locale：

docusaurus build --locale zh-Hans
docusaurus build --locale en

本地验证时，单语言产物约为 810 个文件、411 个目录、1221 个总条目，低于 ESA Pages 常见的 2000 静态文件限制。

环境变量​

单语言独立域名模式必须同时设置：

SITE_URL
SINGLE_LOCALE_DEPLOY

中文 Pages 项目：

SITE_URL=https://nevergpdzy.com
SINGLE_LOCALE_DEPLOY=true

英文 Pages 项目：

SITE_URL=https://en.nevergpdzy.com
SINGLE_LOCALE_DEPLOY=true

只要缺少任意一个变量，配置就回到单站点双语言逻辑。也就是说，英文 locale 的手写链接会继续使用 /en/docs/intro、/en/blog。

链接和语言切换逻辑​

单语言独立域名模式启用后：

  • Docusaurus url 使用 SITE_URL。
  • baseUrl 仍然是 /。
  • Footer 等手写站内链接不再给英文加 /en。
  • Navbar 不使用默认 localeDropdown，改用自定义 custom-locale-switch。

自定义语言切换只改变跳转逻辑，不改变视觉样式。桌面端复用 Docusaurus 默认 navbar__link 链接样式，手机侧边栏复用默认 menu__link 菜单样式，因此手机端也会显示同一个语言切换入口。

跳转规则：

https://nevergpdzy.com/docs/intro
  -> https://en.nevergpdzy.com/docs/intro

https://en.nevergpdzy.com/docs/intro
  -> https://nevergpdzy.com/docs/intro

Query 和 hash 会被保留：

https://nevergpdzy.com/docs/intro?x=1#title
  -> https://en.nevergpdzy.com/docs/intro?x=1#title

实现上，组件会根据当前 SITE_URL 推导对应域名：

  • 当前域名不是 en. 开头时，目标域名前加 en.。
  • 当前域名是 en. 开头时，目标域名去掉 en.。

ESA Pages 项目配置​

中文项目：

Repository: 当前仓库
Build command: npm run build:zh
Output directory: build
SITE_URL: https://nevergpdzy.com
SINGLE_LOCALE_DEPLOY: true

英文项目：

Repository: 当前仓库
Build command: npm run build:en
Output directory: build
SITE_URL: https://en.nevergpdzy.com
SINGLE_LOCALE_DEPLOY: true

不要在同一个 ESA Pages 项目里构建完整双语言站点，否则会回到文件数量过多的问题。

验证清单​

本地或 ESA 构建完成后检查：

  1. 中文项目没有 build/en 目录。
  2. 英文项目没有 build/en 目录。
  3. 中文项目 /docs/intro 可以访问。
  4. 英文项目 /docs/intro 可以访问英文文档。
  5. 英文项目的 Footer 不出现 /en/docs/intro、/en/blog。
  6. 中文站语言切换跳到 https://en.nevergpdzy.com。
  7. 英文站语言切换跳回 https://nevergpdzy.com。
  8. sitemap.xml 使用当前项目的 SITE_URL。
  9. 文件数低于 ESA Pages 限制：
Get-ChildItem build -Recurse -File | Measure-Object
Get-ChildItem build -Recurse -Directory | Measure-Object

旧 /en 路径​

双项目部署成功后，旧的 /en/... 地址不会天然变成英文独立域名。需要保留旧链接时，可以后续在 ESA 上加重定向规则：

https://nevergpdzy.com/en/docs/intro
  -> https://en.nevergpdzy.com/docs/intro

这个重定向不是单语言部署的必需项，可以在主部署跑通后再做。