# https://github.com/tinysearch/tinysearch 项目说明书

生成时间：2026-06-25 07:31:18 UTC

## 目录

- [tinysearch Overview and Architecture](#page-1)
- [Configuration and Schema Design](#page-2)
- [Library API and CLI Usage](#page-3)
- [Deployment, Integration, and Troubleshooting](#page-4)

<a id='page-1'></a>

## tinysearch Overview and Architecture

### 相关页面

相关主题：[Configuration and Schema Design](#page-2), [Library API and CLI Usage](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- 资料来源： [README.md](https://github.com/tinysearch/tinysearch/blob/main/README.md)
- 资料来源： [src/lib.rs](https://github.com/tinysearch/tinysearch/blob/main/src/lib.rs)
- 资料来源： [src/api.rs](https://github.com/tinysearch/tinysearch/blob/main/src/api.rs)
</details>

# tinysearch 概览与架构

## 项目概述

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

### 核心特性

| 特性 | 描述 |
|------|------|
| **轻量级** | 完整搜索引擎压缩后仅约 40KB（gzip 后更小） |
| **静态优先** | 专为静态网站设计，无需数据库或后端服务 |
| **客户端搜索** | 在浏览器中直接执行搜索，保护用户隐私 |
| **易于集成** | 可与 Jekyll、Hugo、Zola、Cobalt、Pelican 等静态网站生成器配合使用 |
| **可配置** | 通过 `tinysearch.toml` 配置文件自定义搜索行为 |

## 架构设计

```mermaid
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 配置文件

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

### 主要配置选项

| 配置项 | 描述 |
|--------|------|
| `indexed_fields` | 指定需要进行全文索引的字段 |
| `metadata_fields` | 指定作为元数据存储的字段（仅显示，不索引） |
| `url_field` | 指定用作链接目标的字段 |

## 集成模式

### 作为 Rust 库使用

从版本 0.10.0 开始，tinysearch 支持作为 Rust 库使用，允许用户在 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 | ~40KB | 极快 | 静态网站 |
| lunr.js | ~200KB | 快 | 中型应用 |
| elasticlunr | ~300KB | 快 | 复杂搜索 |
| flexsearch | ~100KB | 极快 | 现代浏览器 |
| fuse.js | ~50KB | 中等 | 模糊搜索 |

## 路线图与发展

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

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

## 常见问题

### 搜索结果似乎随机

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

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

### 集成问题

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

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

## 相关资源

- [GitHub 仓库](https://github.com/tinysearch/tinysearch)
- [版本发布](https://github.com/tinysearch/tinysearch/releases)
- [使用示例](https://github.com/tinysearch/tinysearch/tree/main/examples)

## See Also

- [tinysearch 快速入门指南](https://github.com/tinysearch/tinysearch/blob/main/README.md)
- [配置文件参考](https://github.com/tinysearch/tinysearch/blob/main/tinysearch.toml)
- [API 文档](https://docs.rs/tinysearch)

---

<a id='page-2'></a>

## Configuration and Schema Design

### 相关页面

相关主题：[tinysearch Overview and Architecture](#page-1), [Library API and CLI Usage](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tinysearch.toml](https://github.com/tinysearch/tinysearch/blob/main/tinysearch.toml)
- [examples/tinysearch.toml](https://github.com/tinysearch/tinysearch/blob/main/examples/tinysearch.toml)
- [examples/ecommerce/tinysearch.toml](https://github.com/tinysearch/tinysearch/blob/main/examples/ecommerce/tinysearch.toml)
- [examples/blog/tinysearch.toml](https://github.com/tinysearch/tinysearch/blob/main/examples/blog/tinysearch.toml)
- [examples/documentation/tinysearch.toml](https://github.com/tinysearch/tinysearch/blob/main/examples/documentation/tinysearch.toml)
- [examples/ecommerce/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/ecommerce/README.md)
- [examples/blog/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/blog/README.md)
- [examples/documentation/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/documentation/README.md)
- [examples/library_advanced/main.rs](https://github.com/tinysearch/tinysearch/blob/main/examples/library_advanced/main.rs)
- [README.md](https://github.com/tinysearch/tinysearch/blob/main/README.md)
</details>

# Configuration and Schema Design

## 概述

`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]`，包含三类键：

| 键 | 含义 | 是否必填 | 示例 |
|---|---|---|---|
| `indexed_fields` | 写入倒排/过滤器、参与匹配的字段名列表 | 否（缺省为 `["title", "body"]`） | `["title", "description", "tags"]` |
| `metadata_fields` | 仅作为结果返回的展示字段，不进入索引 | 否 | `["price", "image_url", "author"]` |
| `url_field` | 用于在搜索结果中生成跳转链接的字段名 | 否（缺省为 `"url"`） | `"permalink"` |

`资料来源：[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](https://github.com/tinysearch/tinysearch/blob/main/README.md)
- [examples/blog/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/blog/README.md)
- [examples/ecommerce/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/ecommerce/README.md)
- [examples/zola/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/zola/README.md)

---

<a id='page-3'></a>

## Library API and CLI Usage

### 相关页面

相关主题：[tinysearch Overview and Architecture](#page-1), [Configuration and Schema Design](#page-2), [Deployment, Integration, and Troubleshooting](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/lib.rs](https://github.com/tinysearch/tinysearch/blob/main/src/lib.rs)
- [src/api.rs](https://github.com/tinysearch/tinysearch/blob/main/src/api.rs)
- [src/bin/tinysearch.rs](https://github.com/tinysearch/tinysearch/blob/main/src/bin/tinysearch.rs)
- [src/bin/utils/mod.rs](https://github.com/tinysearch/tinysearch/blob/main/src/bin/utils/mod.rs)
- [src/bin/utils/index.rs](https://github.com/tinysearch/tinysearch/blob/main/src/bin/utils/index.rs)
- [src/bin/utils/storage.rs](https://github.com/tinysearch/tinysearch/blob/main/src/bin/utils/storage.rs)
- [README.md](https://github.com/tinysearch/tinysearch/blob/main/README.md)
- [examples/library_advanced/main.rs](https://github.com/tinysearch/tinysearch/blob/main/examples/library_advanced/main.rs)
</details>

# Library API and CLI Usage

## 概述

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 模块

### 常用命令

```bash
# 构建索引
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` 元数据：

```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);
```

### 自定义文章类型

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

```rust
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]()）：

| 配置项 | 作用 |
|--------|------|
| `indexed_fields` | 参与全文索引的字段列表 |
| `metadata_fields` | 仅作为元数据存储、不参与搜索的字段 |
| `url_field` | 用于生成结果链接的字段 |

典型配置示例：

```toml
[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](https://github.com/tinysearch/tinysearch/issues/183) 中提出希望不依赖可执行文件而直接以 Rust 库方式调用——v0.10.0 已通过新增库 API 予以解决。
- **WASM 加载兼容性**：现代浏览器对 WASM 的加载行为发生变化，影响部分 JS 集成（[Issue #175](https://github.com/tinysearch/tinysearch/issues/175)）。部署到生产环境前需按 [Rust WASM 部署指南](https://rustwasm.github.io/book/reference/deploying-to-production.html) 显式配置 gzip MIME 类型。
- **构建产物控制**：[Issue #169](https://github.com/tinysearch/tinysearch/issues/169) 建议添加构建目录开关并仅复制 WASM 文件以简化部署流程。

## See Also

- [tinysearch 主仓库](https://github.com/tinysearch/tinysearch)
- [Bloom 过滤器全文搜索](https://www.stavros.io/posts/bloom-filter-search-engine/)
- [Xor Filter 论文](https://arxiv.org/abs/1912.08258)
- [examples/library_basic](https://github.com/tinysearch/tinysearch/tree/main/examples/library_basic)
- [examples/library_advanced](https://github.com/tinysearch/tinysearch/tree/main/examples/library_advanced)

---

<a id='page-4'></a>

## Deployment, Integration, and Troubleshooting

### 相关页面

相关主题：[Configuration and Schema Design](#page-2), [Library API and CLI Usage](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/tinysearch/tinysearch/blob/main/README.md)
- [src/lib.rs](https://github.com/tinysearch/tinysearch/blob/main/src/lib.rs)
- [examples/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/README.md)
- [examples/zola/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/zola/README.md)
- [examples/pelican/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/pelican/README.md)
- [examples/blog/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/blog/README.md)
- [examples/documentation/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/documentation/README.md)
- [examples/library_advanced/main.rs](https://github.com/tinysearch/tinysearch/blob/main/examples/library_advanced/main.rs)
- [examples/index.json](https://github.com/tinysearch/tinysearch/blob/main/examples/index.json)
</details>

# 部署、集成与故障排查

## 概述

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

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

---

## 部署模式与产物生成

### CLI 构建流水线

tinysearch 同时提供命令行模式（`-m`）与 WASM 模式。常见部署步骤为：先生成 JSON 索引文件，再通过 tinysearch 编译为 WASM 资产。对于博客场景，命令为 `tinysearch -m storage -p ./output posts.json`，再执行 `tinysearch -m wasm -p ./wasm_output posts.json` 即可生成可嵌入到前端的产物 资料来源：[examples/blog/README.md:18-26]()。

### Docker 镜像分发

若环境不具备完整的 Rust 工具链，可使用 nightly 构建的 Docker 镜像进行索引生成。`README.md` 给出了基于 Docker 的快速试用流程：先下载示例索引 `fixtures/index.json`，再通过容器挂载输出目录生成 WASM 资料来源：[README.md:144-156]()。

### 生产环境 WASM 托管要求

由于浏览器加载 `.wasm` 文件需要正确的 MIME 类型（`application/wasm`），官方文档明确建议在生产环境显式配置 gzip 与 wasm MIME 类型，否则在某些 Web 服务器（如 nginx、CDN）上会出现加载失败 资料来源：[README.md:138-142]()。这一要求在社区反馈中也多次被强调（参见 issue #175 关于浏览器加载策略变更导致的失败）。

### 库模式（Rust API）

自 v0.10.0 起，tinysearch 提供实验性 Rust 库 API，允许在自定义静态站点生成器中直接调用索引构建与查询逻辑，而不必依赖外部可执行文件 资料来源：[src/lib.rs:1-15]()。基本用法通过 `TinySearch::new()` 创建实例，再调用 `build_index(&posts)` 与 `search(&index, query, n)` 完成索引与检索 资料来源：[src/lib.rs:30-50]()。高级用法可参考 `examples/library_advanced/main.rs`，其中演示了自定义 stopwords 与自定义结构体的用法 资料来源：[examples/library_advanced/main.rs:30-50]()。

---

## 与静态站点生成器集成

tinysearch 官方文档与社区示例覆盖了多种主流 SSG，其共同模式是：在构建期生成符合 tinysearch 输入规范的 JSON 数组（每条记录至少包含 `title` 与 `url`/`body` 字段），再将其送入 tinysearch 编译为 WASM 嵌入站点。

| 静态站点生成器 | 集成入口 | 关键模板/产物 |
| --- | --- | --- |
| Zola | `templates/tinysearch_index.html` | 通过 Tera 模板迭代 `section.pages` 渲染为 JSON 资料来源：[examples/zola/README.md:14-24]() |
| Pelican | `templates/json.html` + `content/pages/json.md` | 通过 Jinja 模板将 `articles` 序列化为 JSON 资料来源：[examples/pelican/README.md:5-12]() |
| Hugo | 示例 README（社区提供） | 使用 `--optimize --path static` 写入 `public/` 目录 资料来源：[examples/documentation/README.md:32-38]() |
| 通用博客 | `posts.json` + `tinysearch.toml` | 在 `examples/blog/` 中演示 资料来源：[examples/blog/README.md:8-16]() |

### 字段可配置（v0.10.0 新特性）

自 v0.10.0 起，用户可通过 `tinysearch.toml` 自定义哪些字段参与索引（`indexed_fields`）、哪些字段仅作为元数据存储（`metadata_fields`）、以及哪个字段作为结果链接（`url_field`）。这一改进使 tinysearch 能适配不同 JSON 结构，从简单博客到复杂电商目录 资料来源：[examples/documentation/docs.json:1-12]()。

```mermaid
flowchart LR
  A[Markdown 内容] --> B[SSG 构建期模板]
  B --> C[JSON 索引]
  C --> D[tinysearch CLI]
  D --> E[WASM 资产]
  E --> F[浏览器搜索]
```

---

## 常见故障与排查

### JSON 模板输出问题

在 Zola 或 Pelican 中，若模板未正确使用 `json_encode`/`tojson` 过滤器或缺少逗号分隔，tinysearch 在解析时会失败。建议先用 JSON 校验器测试模板输出，并确认迭代循环的 `loop.last` 逻辑 资料来源：[examples/zola/README.md:62-70]()。

### WASM 加载失败

最常见的原因是 `.wasm` 文件的 MIME 类型配置错误或缺少 CORS/HTTPS 设置。当浏览器行为变化（如 issue #175 反馈的现代浏览器加载策略变更）时，旧版 JS 胶水代码可能停止工作，需更新前端加载逻辑 资料来源：[README.md:138-142]()。

### 搜索结果不符合预期

社区反馈（如 issue #120）指出结果"看起来随机"，这通常源于 Bloom/Xor Filter 概率特性以及 stopword 处理。建议在 `tinysearch.toml` 中明确指定 `indexed_fields`，并在 `examples/blog/README.md` 推荐的字段集合（`title`、`content`、`excerpt`、`tags`）基础上微调 资料来源：[examples/blog/README.md:8-12]()。

### 中文与多语言分词限制

tinysearch 当前仅支持整词匹配（无搜索建议与子词切分），对中文等非空格分隔语言可能出现漏检，例如搜索"排序"无法命中包含"快速排序"的页面（issue #179）。可通过在 `tinysearch.toml` 的 `indexed_fields` 中加入更细粒度的人工切分字段缓解 资料来源：[examples/documentation/README.md:8-12]()。

### 版本与 CI 不一致

Homebrew 等第三方分发渠道曾因 crates.io 上 `tinysearch` 与 `tinysearch-engine` 版本错位而出现安装错误（issue #182）。建议用户在 CI 中显式锁定 `tinysearch = "0.10.0"` 以避免传递依赖漂移。

### 突出显示匹配关键词

社区已在 `abridge` 主题中实现关键词高亮（issue #119），相关 JS 逻辑位于 `static/tinysearch.js`，可在自有前端参考其实现思路。

---

## See Also

- 架构与底层原理：[README.md](https://github.com/tinysearch/tinysearch/blob/main/README.md)
- 库 API 用法：[src/lib.rs](https://github.com/tinysearch/tinysearch/blob/main/src/lib.rs)
- 电商目录集成示例：[examples/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/README.md)
- Zola 集成模板：[examples/zola/README.md](https://github.com/tinysearch/tinysearch/blob/main/examples/zola/README.md)
- 库模式高级用法：[examples/library_advanced/main.rs](https://github.com/tinysearch/tinysearch/blob/main/examples/library_advanced/main.rs)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: tinysearch/tinysearch; human_manual_source: deepwiki_human_wiki -->