搜索版本控制

概述

为了解决 Cloudflare 缓存导致的搜索索引数据更新问题，对 Wowchemy 搜索系统实施了以下改进：

主要改进

1. 动态版本生成机制

构建脚本改进 (scripts/build.js):

• 为每个搜索索引文件生成 MD5 哈希值
• 结合时间戳创建唯一版本标识：{timestamp}_{hash}
• 分别处理中文和英文搜索索引
• 生成版本数据文件供 Hugo 模板使用

版本生成逻辑:

const hash = crypto.createHash('md5').update(fileContent).digest('hex').substring(0, 8);
const timestamp = Date.now();
const versionHash = `${timestamp}_${hash}`;

2. 数据文件驱动的版本控制

版本数据文件 (data/search_versions.json):

{
  "generated_at": "2025-07-06T09:02:49.455Z",
  "search_version": {
    "zh": "1751792568636_7ee7db60",
    "en": "1751792569442_830a558b"
  }
}

3. 模板动态版本注入

搜索模板改进 (layouts/partials/wowchemy_search.html):

• 移除硬编码的占位符 __SEARCH_HASH_ZH__、__SEARCH_HASH_EN__
• 从 Hugo 数据文件动态读取版本信息
• 构建带版本参数的搜索索引 URL

模板逻辑:

{{/* Get search versions from data file */}}
{{ $search_versions := .Site.Data.search_versions }}
{{ $zh_version := $search_versions.search_version.zh | default "default" }}
{{ $en_version := $search_versions.search_version.en | default "default" }}

{{/* Configure index URI with version parameter */}}
{{ $indexURI := printf "search-index/index.json.gz?v=%s" $zh_version }}
{{ if ne .Site.Language.Lang "zh" }}
  {{ $indexURI = printf "search-index/%s/index.json.gz?v=%s" .Site.Language.Lang $en_version }}
{{ end }}

工作流程

构建过程

1. 压缩搜索索引：
2. 读取 public/index.json (中文) 和 public/en/index.json (英文)
3. 为每个文件生成 MD5 哈希值
4. 压缩为 .gz 格式

5. 输出到 public/search-index/ 目录

6. 生成版本数据：

7. 收集各语言版本的哈希值
8. 创建 data/search_versions.json 文件

9. 包含时间戳和版本信息

10. Hugo 模板处理：

11. 读取版本数据文件
12. 动态构建搜索索引 URL
13. 确保每次都有唯一的缓存破坏参数

部署验证

搜索索引 URL 示例：

• 中文：/search-index/index.json.gz?v=1751792568636_7ee7db60
• 英文：/search-index/en/index.json.gz?v=1751792569442_830a558b

解决的问题

1. Cloudflare 缓存问题

• 问题：静态的 URL 导致旧数据被缓存
• 解决：每次构建生成新的版本参数，确保 URL 唯一性

2. 占位符替换问题

• 问题：静态占位符 __SEARCH_HASH__ 未被替换
• 解决：使用 Hugo 数据文件动态注入版本信息

3. 版本同步问题

• 问题：搜索索引和网站内容版本不同步
• 解决：构建时统一生成，确保版本一致性

技术细节

文件哈希算法

• 使用 MD5 算法对文件内容生成哈希
• 取前 8 位字符确保唯一性且不过长
• 结合时间戳提供额外的唯一性保证

缓存破坏策略

原始URL: /search-index/index.json.gz
新URL: /search-index/index.json.gz?v=1751792568636_7ee7db60

多语言支持

• 自动检测源文件语言（通过路径判断）
• 为不同语言生成独立的版本标识
• 支持中文默认语言的特殊处理

构建集成

构建命令现在包含搜索版本生成：

npm run build  # 包含 generate-analysis + hugo build + compress-json

监控建议

1. 检查版本数据文件：确认 data/search_versions.json 在每次构建后更新
2. 验证 URL 参数：检查生成的 HTML 中搜索配置是否包含正确的版本参数
3. 测试搜索功能：确认搜索结果反映最新内容
4. 缓存清理：首次部署后可能需要手动清理 Cloudflare 缓存

与分析数据版本控制的对比

这套搜索版本控制系统确保了每次网站内容更新后，搜索功能都能及时反映最新的内容索引。