通过多站点方式另类解决Hexo多国语言问题：Cloudflare Worker与Sitemap架构实战

结论先行：当出海博客的语言版本扩展至 10 国以上且总文章数破千时，将所有语言强行揉合在单个 Hexo 实例中必然遭遇内存溢出（OOM）、编译耗时爆炸与主题标签交叉污染的瓶颈。工程上的破局之道是“多站点分治”：按语言解耦配置与源码，依托 GitHub Actions 矩阵（Matrix）实现多语言并行瞬时构建；同时在边缘网络借助 Cloudflare Worker 动态生成统一的 sitemap_index.xml 与精准 hreflang 映射，彻底兼顾开发体验、渲染性能与搜索引擎抓取效率。

0、单站点多语言的物理瓶颈

使用 Butterfly 等 Hexo 经典主题尝试单实例多语言建站时，往往会遭遇三个难以逾越的障碍：

1. 主题组件语言污染：主题内建的 tags、categories 与 archives 生成器大多设计为全站全局作用域。即使文章详情页面通过参数适配了对应语言，侧边栏的热门标签、全局归档时间轴却依然混杂着中文和其他语言的词条。
2. 编译性能与内存上限：Hexo 是基于 Node.js 单线程运行的生成器。当站点累计包含 10 国语言、每种语言数百篇文章加上高分辨率配图索引时，单次 hexo generate 容易触及 V8 引擎默认的内存上限，触发 JavaScript heap out of memory 崩溃。同时，修改单一语言的错别字，需要强制全量重新渲染数千个静态 HTML。
3. 搜索引擎 Sitemap 割裂：如果退一步将各语言分散到不同子站点独立生成，Google 等搜索引擎将无法在一个统一的根入口抓取全站的国际化索引，严重削弱多语言站点的权重传递。

与其在单一 Hexo 框架的复杂逻辑中反复打补丁，不如换个思路：一个语言一个独立子站，利用边缘计算在前端实现统一聚合。

---

1、多站点解耦与边缘聚合总拓扑

该方案将内容与编译过程拆解为独立单元，在最终输出层通过边缘网络融为一体：

---

2、配置解耦与 GitHub Actions 矩阵并行构建

我们无需为每个语言创建独立的代码仓库，而是通过多份精简的配置文件共享同一套主题与静态资源。

2.1 配置文件分立模式

在博客根目录下维护配置文件：

• _config.yml（主站默认语言，例如中文）
• _config.en.yml（英语独立覆盖配置）
• _config.ja.yml（日语独立覆盖配置）

以 _config.ja.yml 为例，只需覆盖差异字段：

# 日语站点配置覆盖
url: https://blog.ittinker.com/ja
root: /ja/
language: ja

# 日语专属目录映射（让 Hexo 仅扫描日语文章源目录）
source_dir: source_ja

# 站点元数据
title: ITTinker 技術ブログ
subtitle: グローバル開発者向けのツールと実践
author: Richardson

# 归档与固定链接
permalink: posts/:abbrlink.html

通过指定 source_dir: source_ja，各语言站点在编译时只会加载本语言的 Markdown 文件，从根源上杜绝了内存膨胀和标签混淆。

2.2 GitHub Actions 矩阵并发工作流

在 .github/workflows/deploy.yml 中利用 strategy.matrix 定义并行编译任务：

name: Parallel Multi-Site Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - lang: default
            config: _config.yml
            dest: public
          - lang: en
            config: _config.yml,_config.en.yml
            dest: public/en
          - lang: ja
            config: _config.yml,_config.ja.yml
            dest: public/ja
          - lang: de
            config: _config.yml,_config.de.yml
            dest: public/de

    steps:
      - name: Checkout Source
        uses: actions/checkout@v4
        with:
          submodules: true

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Build Language Site
        run: |
          npx hexo generate --config ${{ matrix.config }}
          # 针对分站整理输出目录结构
          if [ "${{ matrix.lang }}" != "default" ]; then
            mkdir -p dist/${{ matrix.lang }}
            cp -r public/* dist/${{ matrix.lang }}/
          else
            mkdir -p dist
            cp -r public/* dist/
          fi

      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: site-${{ matrix.lang }}
          path: dist/

矩阵任务由 GitHub 提供的多个独立 Runner 同时并行编译，原本串行编译 10 个站点所需的 20 分钟时间，被压缩至 2 分钟左右。

---

3、Cloudflare Worker 动态站点地图索引（Sitemap Index）

各子站编译完毕后，每个站点会各自生成一个独立的 sitemap.xml：

• 主站：https://blog.ittinker.com/sitemap.xml
• 英文站：https://blog.ittinker.com/en/sitemap.xml
• 日文站：https://blog.ittinker.com/ja/sitemap.xml

如果直接提交，各站各自为战。我们需要在边缘网络编写一个 Cloudflare Worker，动态拦截对于根目录 /sitemap.xml 的请求，生成标准的 Sitemap Index。

3.1 生产级 Cloudflare Worker 完整源码

创建 worker.js：

/**
 * Cloudflare Worker: 动态聚合多语言 Sitemap Index
 */
const BASE_DOMAIN = 'https://blog.ittinker.com';

// 声明全站支持的语言分支列表
const SUPPORTED_LANGS = [
  { prefix: '', label: 'Default / zh-CN' },
  { prefix: 'en', label: 'English' },
  { prefix: 'ja', label: 'Japanese' },
  { prefix: 'de', label: 'German' },
  { prefix: 'fr', label: 'French' },
  { prefix: 'es', label: 'Spanish' }
];

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    // 拦截对根目录 /sitemap.xml 或 /sitemap_index.xml 的请求
    if (url.pathname === '/sitemap.xml' || url.pathname === '/sitemap_index.xml') {
      const cache = caches.default;
      const cacheKey = new Request(url.toString(), request);
      let response = await cache.match(cacheKey);

      if (!response) {
        const now = new Date().toISOString();
        
        // 动态构建符合 sitemap.org 规范的 XML 索引
        let xml = `<?xml version="1.0" encoding="UTF-8"?>\n`;
        xml += `<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n`;

        SUPPORTED_LANGS.forEach(lang => {
          const sitemapUrl = lang.prefix 
            ? `${BASE_DOMAIN}/${lang.prefix}/sitemap.xml`
            : `${BASE_DOMAIN}/sitemap.xml`;
            
          xml += `  <sitemap>\n`;
          xml += `    <loc>${sitemapUrl}</loc>\n`;
          xml += `    <lastmod>${now}</lastmod>\n`;
          xml += `  </sitemap>\n`;
        });

        xml += `</sitemapindex>`;

        response = new Response(xml, {
          status: 200,
          headers: {
            'Content-Type': 'application/xml; charset=utf-8',
            'Cache-Control': 'public, max-age=43200, s-maxage=86400, stale-while-revalidate=3600',
            'X-Generator': 'Cloudflare-Worker-Sitemap-Aggregator'
          }
        });

        // 将生成的响应写入 Cloudflare 全球边缘节点缓存
        ctx.waitUntil(cache.put(cacheKey, response.clone()));
      }

      return response;
    }

    // 非 sitemap 请求直接回源到真实静态站点
    return fetch(request);
  }
};

3.2 部署描述符 (wrangler.toml)

name = "ittinker-sitemap-worker"
main = "worker.js"
compatibility_date = "2024-09-01"

routes = [
  { pattern = "blog.ittinker.com/sitemap.xml", zone_name = "ittinker.com" },
  { pattern = "blog.ittinker.com/sitemap_index.xml", zone_name = "ittinker.com" }
]

[env.production]
workers_dev = false

部署至 Cloudflare 边缘网络后，当搜索引擎爬虫访问 https://blog.ittinker.com/sitemap.xml 时，Worker 瞬间吐出规范的 Sitemap 索引结构，并引导爬虫平滑爬取各分站地图。

---

4、多语言 SEO 核心：hreflang 与 Canonical 协同

多语言站点在 SEO 层面最忌讳被算法误判为“同一内容的机器复制粘贴”。必须在各站的 HTML <head> 中注入规范的互指标签。

4.1 页面级 hreflang 规范

在 Butterfly 主题的自定义 head 注入模板（如 custom_head.pug）中追加：

<!-- 声明多语言版本之间的对应关系 -->
<link rel="alternate" hreflang="zh-CN" href="https://blog.ittinker.com/posts/example.html" />
<link rel="alternate" hreflang="en" href="https://blog.ittinker.com/en/posts/example.html" />
<link rel="alternate" hreflang="ja" href="https://blog.ittinker.com/ja/posts/example.html" />
<link rel="alternate" hreflang="x-default" href="https://blog.ittinker.com/posts/example.html" />

• x-default：指向默认落地语言（通常为中文或英文），当访客的浏览器语言未在受支持列表中时，引导至该默认版本。
• 对称互指原则：如果中文页面声明了它有日文版对应页面，那么日文版页面必须以完全相同的 URL 格式声明其中文版对应页面，否则会被 Google 搜索引擎认定为无效标签直接丢弃。

---

5、方案优缺点与架构选型对比

评价维度	单一 Hexo 实例集成多语言	多站点分治 + Cloudflare 边缘聚合
构建性能	随文章数线性恶化，极易 OOM 崩溃	矩阵并行处理，构建时间稳定在 2-3 分钟
主题隔离度	标签、分类、近期文章容易跨语言串台	彻底物理级隔离，各语言主题语境纯粹
Sitemap 处理	依赖第三方复杂插件计算	Cloudflare Worker 动态生成标准 Index
日常维护成本	需维护复杂的内部过滤 JS 钩子	仅需维护一份精简的 YAML 配置差异表
CI/CD 复杂度	简单（单次构建单次推流）	需编写 GitHub Actions Matrix 聚合流程

---

6、架构交付自检清单

部署多站点前，按照此表逐一核实各项配置：

• 各分语言配置文件（如 _config.ja.yml）中的 root 与 url 属性已正确配置子路径
• 确认各分站的 source_dir 指向独立的专属目录，互不交叉读取
• 检查 GitHub Actions 构建流程，确认各矩阵任务能够成功生成并聚合到目标目录
• 在终端运行 curl -I https://blog.ittinker.com/sitemap.xml，验证响应头包含 application/xml 与 Worker 标记
• 在浏览器直接打开 /sitemap.xml，验证输出符合 sitemapindex 规范且各分站链接均能正常打开
• 随机抽取一篇翻译文章，检查页面源代码的 <head> 部分是否完整包含了各语言互指的 hreflang 标签