搜索

配置本地多语言搜索，或显式启用在线服务商。

OINK 默认并推荐使用本地搜索。Hugo 会为每种语言生成独立索引；主题从同源资源提供 Lunr 及其 CJK 回退。站点无需公共爬虫、外部账户、CDN 或网络连接，即可完成构建和搜索。

Google Custom Search 与 Algolia DocSearch 仍作为兼容的在线集成保留。它们默认关闭；只有站点明确接受相应的外部请求、索引方式、可用性与隐私边界时，才应启用。

同一时间只能启用一种搜索实现。

使用 Lunr 的本地搜索

在 hugo.yaml 中启用本地搜索：

params:
  offlineSearch: true

不要同时配置 gcs_engine_id 或 params.search.algolia。生产构建完成后，输出中会为每种语言生成一个索引，例如：

offline-search-index.en.json
offline-search-index.zh.json

浏览器加载当前语言的索引，并在不离开页面的情况下显示结果。中文内容使用 OINK 的 CJK 回退，不依赖以空格分词。

启动预览前先执行常规构建：

hugo --gc
hugo server --disableFastRender

如果索引变化时 server 已经在运行，请将其重启。对于子路径部署，请确认浏览器从配置的 baseURL 下请求索引，而不是从域名根目录请求。

设置摘要长度和最大结果数：

params:
  offlineSearch: true
  offlineSearchSummaryLength: 120
  offlineSearchMaxResults: 12

所选限制应确保搜索对话框在移动设备上保持流畅。摘要用于帮助发现内容，不能替代认真编写的页面描述。

在页面 front matter 中设置 exclude_search: true：

---
title: Internal index
exclude_search: true
---

该设置适用于工具页、重复页、生成页或测试页。不要仅仅因为当前译文不完整就排除页面；应修复译文。

结果面板会随内容扩展。站点可以在 assets/scss/_styles_project.scss 中限制宽度：

.td-offline-search-results {
  max-width: 46rem;
}

覆盖搜索样式时，必须保留键盘焦点、可见选中状态、移动端宽度和深色模式对比度。

OINK 会在品牌外壳中提供搜索入口，也可以在侧栏显示输入框。如果要隐藏侧栏输入框，同时保留主搜索入口，请配置：

params:
  ui:
    sidebar_search_disable: true

外壳的打开与关闭控件会向辅助技术暴露对话框关系和状态。自定义实现必须保留这些语义。

搜索始终停留在当前语言。请验证：

中文搜索出现故障时，应先检查生成的中文 JSON，再考虑修改分词。索引缺失或只包含英文，通常属于内容或构建配置问题。

Google Custom Search Engine（GCSE）通过 Google 索引搜索公开站点。它需要已经部署且允许爬取的生产站点，并会把查询发送给第三方服务。

在 Google Programmable Search 中创建搜索引擎后，添加搜索结果页：

---
title: 搜索结果
layout: search
---

随后配置搜索引擎 ID：

params:
  gcs_engine_id: YOUR_ENGINE_ID
  offlineSearch: false

为每种支持语言创建译文结果页；必要时使用适合该语言的搜索引擎配置。删除 gcs_engine_id 即可禁用 GCSE。

消费站点应在隐私政策中说明外部请求和隐私影响。GCSE 无法在网络隔离部署中使用。

Algolia DocSearch 为符合条件的公开文档站点提供托管爬虫和交互式结果面板。取得项目的 application ID、搜索 API key 和索引名称后，配置：

params:
  offlineSearch: false
  search:
    algolia:
      appId: YOUR_APP_ID
      apiKey: YOUR_SEARCH_API_KEY
      indexName: YOUR_INDEX_NAME

只能使用公开的只读搜索 key，绝不能使用管理 key。爬虫规则、语言 facet、索引更新与外部服务声明应与站点配置一同维护。该集成有意与本地优先默认值分离。

可以覆盖主题 partial layouts/_partials/algolia/head.html 和 layouts/_partials/algolia/scripts.html，实现站点专属集成。空的覆盖文件会禁用对应主题 partial。

如果现有选项都不合适，站点可以替换搜索输入、结果行为与样式。应尽量复用外壳的对话框与无障碍合同。除非自定义代码与服务商无关，并且能被多个产品复用，否则应保留在站点层。

自定义在线服务商必须显式启用，并说明网络、隐私、索引、故障与离线行为。自定义本地服务商必须从站点或主题发布全部运行时资源，并遵守语言和 baseURL 边界。