配置字典:搜索与内容发现

$ 发布 2026-11-13 | | 更新 2026-11-13
语境: 以实际代码说明站内搜索配置、文案和单篇收录规则,区分搜索、最新文章、相关文章、标签、RSS 与机器阅读出口。

搜索入口、文章收录、语言索引与其他内容入口。


输出
词 3.2k 令牌 4.1k

先写文章可读写第一篇文章,本地预览和部署见发布教程。配置位置与安装见第一篇教程,其他模块从配置字典总入口进入。

本篇区分两件事:搜索框从构建生成的索引检索文章;首页最新文章、标签、文章底部推荐和 RSS 等是其他内容入口,不由搜索开关统一控制。默认值来自主题包,不是 demo 的覆盖值。

theme.search.enabled:全站搜索开关

  • 类型 / 默认值: boolean / true。
  • 状态与作用: 生效。公共页头显示搜索入口,参与搜索的文章输出索引标记,构建完成后生成静态 Pagefind 资源。
  • 限制: false 同时关闭标准页头入口和本次构建的索引生成;单篇 search: true 不能越过全局关闭状态。关闭不等于删除文章、禁用搜索引擎收录或清除托管平台以前部署的索引文件。
  • 示例: theme: { search: { enabled: false } }。

这是唯一的 theme.search 公开叶子字段。没有公开的搜索服务地址、API key、索引目录、结果排序、关键词权重或跨语言检索开关。主题当前使用构建期 Pagefind,部署后不需要单独运行搜索后端。

单篇 search:不是 site.config 字段

位置 类型 / 默认值 状态、作用与限制 示例
src/content/blog/<语言>/某篇文章.md 的 frontmatter.search boolean,可省略 / schema 未设置,文章布局默认 true 条件生效:全局搜索开启时决定是否输出该篇索引根标记;false 不影响列表、相关文章、RSS、机器阅读出口或公开文章地址 search: false

只排除这篇文章的站内搜索收录,可以在已有 frontmatter 中添加:

search: false

不要把它写成 theme.search: false,或在 site.config 顶层新增 search: false。也不要把 frontmatter.search 当作私密文章开关。当前没有 draft 或未来发布日期过滤;未公开内容应放在内容集合之外。完整文章字段见文章字典。

哪些内容进入索引?

标准文章布局在全局与单篇开关同时允许时输出 data-anglefeint-search 根标记。当前明确标记的正文区域包含文章标题、可见副标题和正文;与副标题相同的 context 只按副标题位置处理一次,不是单独给所有 context 建字段索引。

导航、播放器、页脚、评论和相关文章不作为文章正文一起收录。frontmatter.description 不是此搜索 UI 直接使用的结果摘要,标签也不是可配置的搜索过滤器;搜索结果使用 Pagefind 返回的标题元数据与正文摘要。只出现在图片像素、视频或音频中的文字不会被主题做 OCR 或转写。

默认 About、Fragments、Decoder、首页和列表没有文章索引根标记,不因搜索开关开启而自动成为搜索结果。自定义页面需要自己遵守索引标记约定;这不是添加一个不存在的 site.config 字段就能启用的功能。

messages.search:十一项搜索文案

完整前缀是 i18n.locales.<语言>.messages.search.。以下均为可省略的 string,默认取内置当前语言文案与语言回退链。表中只列中文 / 英文默认值;每行示例是字段值。所有字段条件生效:搜索入口存在且对应界面或状态出现时使用。

字段 中文 / 英文默认值 作用、限制与占位符 示例值
label 搜索 / Search 搜索入口按钮的无障碍名称、提示及弹窗标题;不是要搜索的关键字 "搜索文章"
close 关闭搜索 / Close search 关闭按钮的无障碍名称和提示;可见 esc 提示及图标由实现固定 "关闭搜索"
placeholder 搜索文章… / Search articles… 搜索框占位文字及其无障碍标签;不预填关键字 "输入文章关键词"
hint 搜索当前语言的文章。 / Search articles in the current language. 生产环境中没有输入关键字时的提示 "搜索当前语言的文章。"
loading 正在搜索… / Searching… 正在检索或准备检索的提示,不改变延迟与资源加载策略 "正在查找…"
empty 没有找到匹配的文章。 / No matching articles. 没有结果的提示;当前语言没有索引时也可能显示它 "没有找到相关文章。"
error 搜索加载失败,请重试。 / Search could not load. Please try again. 索引清单、搜索模块或结果详情加载失败的提示;不用于生成构建错误 "搜索暂时不可用,请重试。"
retry 重试 / Retry 失败状态的重试按钮文字;点击会重试加载搜索引擎,不会在浏览器重建索引 "重新加载"
more 加载更多 / Load more 还有未显示结果时的继续加载按钮;不改变每批数量 "更多结果"
results 找到 {count} 篇文章 / {count} articles found 有结果时的数量提示;保留字面占位符 {count},脚本替换第一个该占位符,不是已展示卡片数 "共找到 {count} 篇文章"
dev 本地完整搜索请先运行 npm run build,再运行 npm run preview。 / To test full search locally, run npm run build, then npm run preview. dev 模式提示,开发时不执行真实检索;不能靠改文字生成索引 "请构建后在 preview 中测试搜索。"

文案按文本输出,不执行配置里的 HTML。空字符串会覆盖文字,不会隐藏相应按钮;错误使用空字符串还可能让控件失去清楚的无障碍名称。results 的 {count} 不会自动附加到你自定义的句子中,想显示数字就保留一次占位符。

可合并的配置示例

合并到 src/site.config.ts 现有 defineThemeConfig({…}),保留 import、export 与其他个人配置,不重复创建 theme 或 i18n:

theme: { search: { enabled: true } },
i18n: {
  locales: {
    zh: {
      messages: {
        search: {
          label: '搜索文章',
          placeholder: '输入文章关键词',
          results: '共找到 {count} 篇文章',
          empty: '没有找到相关文章。',
        },
      },
    },
  },
},

语言、资源加载与结果展示

  • 构建输出 pagefind/,包含语言清单 anglefeint.json 和 Pagefind 模块。浏览器打开搜索时才加载清单及搜索引擎;搜索 UI 脚本本身会随含入口的页面加载,不是整套搜索代码都等点击才下载。
  • 资源路径自动包含 Astro 的 BASE_URL。只部署 HTML、漏传 pagefind/,或把路径错误重写成 HTML,可能导致加载失败;没有单独的 site.config 索引路径配置。
  • 客户端先用文档 html lang 对照索引语言清单,比较时不区分大小写;当前语言没有索引则返回空结果,不切换到英文搜索。这里使用页面有效语言值,不是根据文案的回退语言查询文章。
  • 输入约 200 毫秒后检索;中文输入法组合输入结束后再安排检索,提交表单可立即触发。空关键字不执行全文搜索。延迟不是配置字段,也不是请求远端 AI。
  • 每批取最多 8 条结果详情,再由“更多”继续加载;没有 pageSize 配置。数量提示使用找到的结果总数,不是当前批次条数。结果只保留同源链接,摘要只保留文本和关键词 mark 高亮,不渲染文章里的任意 HTML。
  • 结果顺序由 Pagefind 返回;没有主题级排序或推荐算法参数。普通翻译回退不会把另一语言的文章补入结果。

语言元数据、启停和回退见语言字典。search 文案只改变界面,不会生成对应语言文章或改变索引语言。

为什么 dev 中没有真实搜索?

索引在 Astro 构建结束后生成,npm run dev 不执行这一步。开发环境会显示 messages.search.dev 提示;即使输入关键词也不会真正检索。这是当前行为,不是搜索失效或少填配置。

准备好内容后,在本地运行:

npm run build
npm run preview

preview 使用构建产物;编辑文章、语言元数据、单篇收录开关或站点路径后,想检验新索引需要重新构建。正式站点要一起部署网页与 pagefind 资源。开着 dev 修改文案不等于线上索引已经更新。

没有可索引文章时仍会生成可识别的空语言清单,UI 可以显示空结果。构建期索引失败会报错,不会默默发布一个伪造的成功索引。重试按钮只重试读取已有资源,不能在访客浏览器中修复构建或生成缺失文章。

其他内容发现入口使用哪些配置?

下面沿用各模块已有字段与默认值;主说明仍在原字典,不新增另一套搜索配置。

配置路径或位置 类型 / 默认值 实际作用与限制、示例 详细说明
theme.homeLatestCount number / 3 首页最新文章数量;如 theme: { homeLatestCount: 5 }。不改变搜索结果批次或文章底部相关文章数量 首页数量
theme.blogPageSize number / 10 Blog List 与标签文章列表每页数量;如 theme: { blogPageSize: 8 }。不是搜索结果数量 列表分页
theme.tags.enabled boolean / true 标签入口与标准标签页;如 theme: { tags: { enabled: false } }。关闭不删除文章 tags,也不关闭站内全文搜索 标签开关
文章 frontmatter.tags string[],可省略 / 未设置 用于标签归档与页面标签显示;例值 [‘Astro’, ‘随笔’]。不参与当前“相关文章”的相关度计算,也不是搜索白名单 文章字段
i18n.locales.<语言>.messages.blog.related string / 内置当前语言,中文与英文见下表 文章底部相关文章标题,只改文案;例值 ‘继续阅读’ 文章文案
i18n.locales.<语言>.messages.blog.relatedAria string / 内置当前语言,中文与英文见下表 相关文章区域无障碍名称;例值 ‘其他文章’ 文章文案

相关文章实际选取当前语言中排除自身后的最新三篇,不依据共同标签、canonicalTopic 或内容相似度。没有独立 relatedCount、相关文章开关或手动推荐名单的 site.config 字段;没有其他文章时不显示该区域。search: false 的文章仍可能被推荐。

文案 中文 / 英文默认值
messages.blog.related 相关文章 / Related
messages.blog.relatedAria 相关文章 / Related posts

RSS、SEO 和机器阅读出口不是站内搜索

入口 当前行为及配置关系
/<语言>/rss.xml 每个启用语言的文章摘要订阅;标题使用全站名称,描述使用该语言 messages.blog.archiveDescription。条目来自该语言文章的 title、description、pubDate 与公开路径;不因单篇 search: false 排除,也不是全文 RSS。没有 theme.search 内的 RSS 开关
页面元信息与搜索引擎 与站内搜索索引是不同输出;search: false 不自动添加 noindex 或关闭 sitemap,不能用它控制互联网搜索引擎抓取
公开机器阅读文本 文章、About、Fragments 等有自己的导出管线,不依赖 Pagefind 收录;语言级公开补充见语言字典。search: false 不作为这些产物的私密过滤器

站点名称、域名和订阅描述应填写真实值;部署与公开地址见发布教程,RSS 使用的 archiveDescription 见列表文案。不要把“站内没有结果”理解成“网站没有公开这个内容”。

当前全局搜索开关、单篇 search 和十一项搜索文案都有消费位置,没有需要填写的旧搜索兼容字段。canonicalTopic 等当前不消费的文章字段,也不会因为放在搜索附近就自动成为索引分类;相关状态见文章字典。没有公开的跨语言合并搜索、图片 OCR、搜索词分析、搜索结果权重或新增索引类型设置。

返回配置字典总入口查其他模块。