tinysearch 概览与架构

项目概述

tinysearch 是一个专为静态网站设计的轻量级、快速的全文搜索引擎。该项目采用 Rust 语言编写，并编译为 WebAssembly 以在浏览器中运行，无需后端服务器即可提供客户端搜索功能。

核心特性

架构设计

graph TB
    A[静态网站内容] --> B[构建过程]
    B --> C[生成 JSON 索引]
    C --> D[tinysearch WASM 模块]
    D --> E[浏览器端搜索]
    E --> F[搜索结果展示]
    
    G[tinysearch.toml] --> B
    H[Rust 源代码] --> I[编译为 WASM]
    I --> D

技术栈

• 核心语言：Rust
• 目标平台：WebAssembly (WASM)
• 索引格式：JSON
• 配置格式：TOML

工作原理

tinysearch 的工作流程可以分为以下几个阶段：

1. 索引生成阶段

在构建过程中，tinysearch 会：

1. 读取 tinysearch.toml 配置文件
2. 扫描网站内容，提取需要索引的字段
3. 生成 JSON 格式的搜索索引
4. 将 WASM 模块和索引文件部署到网站

2. 搜索执行阶段

当用户在浏览器中进行搜索时：

1. WASM 模块加载到浏览器内存
2. 解析用户的搜索查询
3. 在 JSON 索引中执行搜索算法
4. 返回匹配的搜索结果

配置说明

tinysearch.toml 配置文件

[search]
# 配置搜索行为
indexed_fields = ["title", "content", "tags"]
metadata_fields = ["author", "date", "category"]
url_field = "url"

主要配置选项

集成模式

作为 Rust 库使用

从版本 0.10.0 开始，tinysearch 支持作为 Rust 库使用，允许用户在 Rust 代码中直接调用搜索功能，而无需依赖可执行文件。

use tinysearch::{BasicPost, TinySearch};
use std::collections::HashMap;

let posts = vec![
    BasicPost {
        title: "My Post".to_string(),
        url: "/my-post".to_string(),
        body: Some("Post content here".to_string()),
        meta: HashMap::new(),
    }
];

let search = TinySearch::new();
let index = search.build_index(&posts)?;
let results = search.search(&index, "content", 10);

与静态网站生成器集成

tinysearch 可以与多种静态网站生成器集成：

• Jekyll：使用 Liquid 模板生成 JSON 索引
• Hugo：利用 JSON 输出格式自动生成索引
• Zola：通过 Tera 模板创建搜索索引
• Gatsby/Next.js：在构建过程中以编程方式生成索引

性能对比

tinysearch 相比其他搜索解决方案具有显著优势：

路线图与发展

根据社区讨论，tinysearch 的未来发展方向包括：

• 支持更多配置选项
• 改进搜索算法的相关性
• 添加搜索建议功能
• 增强对中文等非英文内容的支持
• 优化索引压缩率

常见问题

搜索结果似乎随机

如果遇到搜索结果相关性不高的问题，可以：

1. 检查 indexed_fields 配置是否包含所有需要搜索的字段
2. 调整内容预处理过程，确保关键词提取准确
3. 考虑使用更描述性的关键词

集成问题

在与特定静态网站生成器集成时遇到问题：

1. 确认构建过程正确生成了 JSON 索引
2. 检查 WASM 文件的 MIME 类型配置
3. 验证 CORS 头设置（如果需要跨域加载）

相关资源

• GitHub 仓库
• 版本发布
• 使用示例

See Also

• tinysearch 快速入门指南
• 配置文件参考
• API 文档

概述

tinysearch 是一个使用 Rust 编写并编译为 WebAssembly 的轻量级全文搜索引擎，定位是为静态网站提供客户端搜索能力。在 v0.10.0 版本中，项目引入了通过 tinysearch.toml 配置文件进行字段映射的能力，让用户可以自定义 JSON 输入中哪些字段参与索引、哪些字段作为元数据存储、以及哪个字段作为结果链接。资料来源：README.md:1-15

Configuration and Schema Design 主要解决两个问题：一是将不同静态站点生成器（Jekyll、Hugo、Zola、Pelican 等）产生的异构 JSON 结构映射到 tinysearch 的内部索引结构；二是允许用户按需控制索引体积与结果丰富度之间的权衡。资料来源：README.md:17-22

配置文件的结构

顶层 `schema` 段

tinysearch.toml 当前只支持一个顶层表 [schema]，包含三类键：

资料来源：tinysearch.toml:1-9

未显式提供 tinysearch.toml 时，tinysearch 会回退到默认 schema，对 title 与 body 建索引，并以 url 作为链接字段。资料来源：README.md:36-40

默认与示例配置

仓库根目录的 tinysearch.toml 与 examples/tinysearch.toml 给出了最小可用的 schema 形式，仅声明 url_field。资料来源：examples/tinysearch.toml:1-4

更复杂的示例分布在 examples/ecommerce、examples/blog、examples/documentation 三个子目录中，分别面向电商商品、博客文章和技术文档三类典型场景。资料来源：examples/ecommerce/tinysearch.toml:1-5、资料来源：examples/blog/tinysearch.toml:1-5、资料来源：examples/documentation/tinysearch.toml:1-6

JSON 输入与字段映射

通用数据形态

tinysearch 期望的输入是一个 JSON 数组，每个元素代表一篇可搜索的文档。字段名可以任意命名，真正决定其角色的是 tinysearch.toml 中的 schema 定义。资料来源：README.md:30-40

以电商场景为例，商品对象的 title、description、category、tags 进入 indexed_fields；而 price、image_url、brand、availability 仅作为元数据保留在结果中，product_url 被声明为 url_field。资料来源：examples/ecommerce/README.md:1-10、资料来源：examples/ecommerce/products.json:1-20

博客场景的对应映射则为：索引 title、content、excerpt、tags；元数据 author、publish_date、category、reading_time、featured_image；permalink 作为 url_field。资料来源：examples/blog/README.md:1-10、资料来源：examples/blog/posts.json:1-10

文档场景在此基础上增加 version、last_updated、contributor、difficulty、type 等元数据字段，用于在搜索结果页展示版本与维护信息。资料来源：examples/documentation/README.md:1-12、资料来源：examples/documentation/tinysearch.toml:1-6

与静态站点生成器的衔接

对于不直接输出 JSON 的静态站点生成器，通常的流程是先编写模板把页面序列化为 JSON，再用 tinysearch 处理该 JSON。Zola 模板通过 json_encode 过滤器把 title、permalink、content 注入到结果对象中；Pelican 模板使用 tojson 实现等价功能。资料来源：examples/zola/README.md:9-23、资料来源：examples/pelican/README.md:1-12

完成 JSON 输出后，使用 tinysearch --optimize --path <out> <json> 即可生成 WASM 搜索模块。资料来源：examples/zola/README.md:30-36、资料来源：examples/pelican/README.md:18-20

库模式下的 Schema 表达

v0.10.0 同时引入了以 Rust 库形式调用 tinysearch 的能力。examples/library_advanced/main.rs 演示了如何传入自定义的 BlogPost 结构体，并在创建 TinySearch 实例时通过 .with_stopwords(...) 调整停用词集合，从而影响索引构建的语义。资料来源：examples/library_advanced/main.rs:30-55

库模式与配置文件模式共享同一套底层索引算法，schema 的核心概念（索引字段、元数据字段、URL 字段）都直接对应到 TinySearch::build_index 与 search 的输入上。资料来源：README.md:80-105

设计权衡与常见陷阱

由于 tinysearch 在浏览器中加载 WASM 模块即可搜索，索引体积直接关系到首屏加载时间。schema 设计应遵循两点原则：只把参与匹配查询的字段放入 indexed_fields，其余字段一律放入 metadata_fields；url_field 应选择最终可访问的稳定链接字段（例如 Zola 的 permalink），避免将模板渲染路径错误地暴露为 URL。资料来源：README.md:9-15、资料来源：examples/blog/tinysearch.toml:1-5

社区中也出现过因字段名大小写或拼写与 schema 不一致导致结果缺失的反馈（参见 Issue #120），因此配置完成后建议先用 tinysearch -m search 在命令行验证一次匹配行为，再进入 WASM 构建阶段。资料来源：README.md:75-85

See Also

• README.md
• examples/blog/README.md
• examples/ecommerce/README.md
• examples/zola/README.md

概述

tinysearch 是一个轻量、快速的全文搜索引擎，专为静态网站设计。它使用 Rust 编写并编译为 WebAssembly 在浏览器中运行，与 Jekyll、Hugo、Zola、Cobalt、Pelican 等静态站点生成器（SSG）配合良好。最新版本 v0.10.0 引入了两个关键特性：可通过 tinysearch.toml 配置 JSON 字段映射，以及支持作为 Rust 库在程序中调用，这恰好回应了社区长期以来的诉求。

资料来源：README.md:1-40

CLI 使用方式

运行模式

CLI 通过 -m 参数切换运行模式，主要包含三种（资料来源：README.md:60-80）：

• storage：从 JSON 输入文件构建搜索索引
• search：在已有索引上执行查询
• wasm：生成可在浏览器中加载的 WebAssembly 模块

常用命令

# 构建索引
tinysearch -m storage -p ./output posts.json

# 在索引上搜索
tinysearch -m search -S "rust programming" -N 3 ./output/storage

# 生成 WASM（开发版）
tinysearch -m wasm -p ./wasm_output posts.json

# 生成 WASM（生产优化版）
tinysearch --release -m wasm -p ./wasm_output posts.json

静态站点生成器集成

CLI 通常接收 SSG 模板生成的 JSON 数组作为输入。社区为常见 SSG 提供了集成示例：

• Zola：通过 Tera 模板将所有页面序列化为 JSON（资料来源：examples/zola/README.md:1-40）
• Hugo：在 config.toml 中添加 json 输出格式后由模板生成（资料来源：examples/hugo/README.md:1-20）
• Pelican：使用 Jinja2 模板遍历所有文章（资料来源：examples/pelican/README.md:1-16）

库 API

核心抽象

src/lib.rs 暴露了库的核心类型（资料来源：src/lib.rs:1-50）：

• BasicPost：内置的基础文章结构
• TinySearch：搜索引擎主体，提供 new()、build_index()、search() 等方法
• Post：trait，允许用户实现自定义文章类型
• SearchIndex：序列化后的索引类型

基础用法

使用内置 BasicPost 配合 HashMap 元数据：

use tinysearch::{BasicPost, TinySearch};
use std::collections::HashMap;

let posts = vec![
    BasicPost {
        title: "My Post".to_string(),
        url: "/my-post".to_string(),
        body: Some("Post content here".to_string()),
        meta: HashMap::new(),
    }
];

let search = TinySearch::new();
let index = search.build_index(&posts)?;
let results = search.search(&index, "content", 10);

自定义文章类型

通过实现 Post trait 可使用任意自定义结构（资料来源：examples/library_advanced/main.rs:1-50）：

use tinysearch::{Post, TinySearch};
use std::collections::HashMap;

struct BlogPost {
    title: String, slug: String, content: String,
    tags: Vec<String>, author: String,
}

impl Post for BlogPost {
    fn title(&self) -> &str { &self.title }
    fn url(&self)   -> &str { &self.slug }
    fn body(&self)  -> Option<&str> { Some(&self.content) }
    fn meta(&self)  -> HashMap<String, String> {
        let mut meta = HashMap::new();
        meta.insert("author".into(), self.author.clone());
        meta.insert("tags".into(),   self.tags.join(", "));
        meta
    }
}

TinySearch 还提供 with_stopwords() 方法用于自定义停用词列表（资料来源：examples/library_advanced/main.rs:55-70）。

配置：tinysearch.toml

v0.10.0 引入的配置文件允许灵活映射 JSON 字段，分为三类（资料来源：README.md:40-60）：

典型配置示例：

[schema]
indexed_fields   = ["title", "content", "tags"]
metadata_fields  = ["author", "date", "category"]
url_field        = "permalink"

针对不同场景，字段选取有所不同：博客场景索引 title、content、excerpt、tags（资料来源：examples/blog/README.md:1-15）；文档场景索引 title、content、section、keywords（资料来源：examples/documentation/README.md:1-15）。

社区反馈与已知问题

• 库 API 缺失：用户在 Issue #183 中提出希望不依赖可执行文件而直接以 Rust 库方式调用——v0.10.0 已通过新增库 API 予以解决。
• WASM 加载兼容性：现代浏览器对 WASM 的加载行为发生变化，影响部分 JS 集成（Issue #175）。部署到生产环境前需按 Rust WASM 部署指南 显式配置 gzip MIME 类型。
• 构建产物控制：Issue #169 建议添加构建目录开关并仅复制 WASM 文件以简化部署流程。

See Also

• tinysearch 主仓库
• Bloom 过滤器全文搜索
• Xor Filter 论文
• examples/library_basic
• examples/library_advanced

部署、集成与故障排查

概述

tinysearch 是一款专为静态网站设计的轻量级全文搜索引擎，使用 Rust 编写并编译为 WebAssembly 在浏览器中执行。本页面聚焦于将 tinysearch 投入生产环境所涉及的三个核心环节：构建与部署、与主流静态站点生成器（SSG）的集成模式、以及在生产环境中常见的故障与排查思路。

tinysearch 在底层使用 Xor Filter（一种概率集合成员判定数据结构）以极小体积实现快速查找，对于约 40 篇文章的博客，WASM 产物体积仅约 99kB（gzip 后 49kB，brotli 后 40kB），适合嵌入到任何静态站点中 资料来源：README.md:10-16。

Pitfall Log / 踩坑日志

项目：tinysearch/tinysearch

摘要：发现 16 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

1. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -v $PWD:/app tinysearch/cli -m wasm
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -v $PWD:/app tinysearch/cli -m wasm
• 证据：identity.distribution | https://github.com/tinysearch/tinysearch | docker run -v $PWD:/app tinysearch/cli -m wasm

2. 安装坑 · 来源证据：Add a switch for build dir, and copy only the resulting wasm file to the path

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add a switch for build dir, and copy only the resulting wasm file to the path
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tinysearch/tinysearch/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：CI error for tinysearch v0.9.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CI error for tinysearch v0.9.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tinysearch/tinysearch/issues/182 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：Demo broken

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Demo broken
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tinysearch/tinysearch/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 来源证据：No such file or directory (os error 2)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：No such file or directory (os error 2)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tinysearch/tinysearch/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。

6. 安装坑 · 来源证据：On npm

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：On npm
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tinysearch/tinysearch/issues/173 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：Roadmap

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Roadmap
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tinysearch/tinysearch/issues/116 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安装坑 · 来源证据：latest tinysearch, cargo install tinysearch not working.

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：latest tinysearch, cargo install tinysearch not working.
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/tinysearch/tinysearch/issues/170 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

9. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/tinysearch/tinysearch | README/documentation is current enough for a first validation pass.

10. 维护坑 · 来源证据：Changes in the way browsers work with wasm causes issues with some js implementation to load the wasm.

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Changes in the way browsers work with wasm causes issues with some js implementation to load the wasm.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tinysearch/tinysearch/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。

11. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/tinysearch/tinysearch | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/tinysearch/tinysearch | no_demo; severity=medium

13. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/tinysearch/tinysearch | no_demo; severity=medium

14. 安全/权限坑 · 来源证据：Error: failed to execute "wasm-pack" "build"

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Error: failed to execute "wasm-pack" "build"
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/tinysearch/tinysearch/issues/151 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

15. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/tinysearch/tinysearch | issue_or_pr_quality=unknown

16. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/tinysearch/tinysearch | release_recency=unknown