用bleve建本地文件索引最直接——它专为嵌入式设计，支持持久化、增量更新与多种查询，避免手写倒排索引、分词及打分的坑；需规范ID生成、字段映射、高亮与增量更新逻辑。
用 bleve 建本地文件索引最直接，别自己解析分词
Go 生态里没有内置全文检索库，硬写倒排索引、分词、打分逻辑会踩一堆坑。直接上 bleve 是目前最稳的选择——它专为嵌入式场景设计，支持磁盘持久化、增量更新、布尔/短语/模糊查询，且 API 清晰。自己用 regexp 或 strings.Split 做“关键词匹配”不是全文检索，连基本的同义词、停用词、词干都处理不了。
常见错误现象：os.ReadDir 读完文件就 strings.Contains 一把梭，结果搜 “running” 找不到 “run”，搜 “café” 因编码问题直接 panic；或者把所有文本拼成大字符串再切片，内存爆掉还无法支持更新。
- 只索引
.txt、.md、.go等可读文本，跳过.git、node_modules、二进制文件（用mimetype或文件头判断） - 建索引前统一转 UTF-8，避免
invalid UTF-8 sequence错误；对 HTML 或 Markdown 文件，先用blackfriday或html2text提纯文本再喂给bleve -
bleve.New的路径必须是空目录或不存在的路径，重复调用会报index already exists
bleve.Index 的 Index 方法要传唯一 ID，不是文件路径
很多人直接把 filepath.Abs 结果当文档 ID 传进去，结果路径含特殊字符（比如 Windows 的 \ 或 URL 编码后的 %20）导致后续搜索失败或索引损坏。ID 必须是合法的、稳定的、无歧义的字符串。
使用场景：文件移动、重命名后要能关联到旧索引；多人协作时避免因路径差异导致索引不一致。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 推荐用文件内容哈希（如
sha256.Sum256）+ 修改时间戳拼接，例如fmt.Sprintf("%x-%d", hash[:8], fi.ModTime().Unix()) - 绝对不要用
filepath.Base当 ID——同名文件（如多个README.md）会覆盖 - 如果业务允许，ID 可以是数据库自增 ID 或 UUID，前提是文件和记录有可靠映射关系
搜索时用 bleve.NewQueryStringQuery 而非手拼 JSON 查询 DSL
直接写 map[string]interface{} 构造查询结构体看着灵活，实际容易漏字段、错类型，比如把 "fuzziness" 写成 "fuzzy"，或把整数 1 传成字符串 "1"，bleve 不报错但查不到结果。
性能影响：手写 DSL 每次都要 json.Marshal，而 NewQueryStringQuery 内部已做缓存和语法树复用，简单查询快 2–3 倍。
- 用户输入直接塞进
bleve.NewQueryStringQuery(userInput)即可，它自动处理引号、括号、AND/OR、通配符（te?t）、模糊（roam~） - 需要高亮？在
SearchRequest里设Highlight: &bleve.Highlight{...，别自己正则替换——bleve返回的fragments已按位置对齐原文 - 想限制字段搜索（如只搜标题）？用
title:Go AND body:interface，字段名必须和索引时DocumentMapping定义的一致
增量更新必须用 Index.Document + Index.Delete 配合，不能全量重建
监听文件变化后调用 bleve.Open 再 Index 全量，看着省事，实际每次重建索引 I/O 和 CPU 开销巨大，万级文件下耗时从毫秒级飙到分钟级，用户等不起。
容易踩的坑：Index.Index 对已存在 ID 的文档是覆盖写，但不会自动清理旧字段索引；如果文件删了却不调 Delete，搜索结果里还会出现“幽灵条目”。
- 文件新增/修改：计算新 ID → 调
Index.Index(id, doc) - 文件删除：用原 ID 调
Index.Delete(id)，ID 必须和当初索引时完全一致 - 改名操作：先
Delete旧 ID，再Index新 ID —— 别试图绕过这一步 - 批量操作用
Index.Batch，比单条快 5–10 倍，尤其适合首次建库
最复杂也最容易被忽略的点：ID 的生成逻辑一旦上线就不能变。哪怕只是多 trim 了一个空格，旧 ID 就再也 match 不上，删不掉，查出来还是脏数据。
