bleve 是本地文件搜索的合理起点，但需确保目录权限、字段索引、中文分词器、ID 唯一性及 query 类型等配置全部正确，否则静默失败。
别手写倒排索引，也别用 strings.Contains 拼凑全文检索——99% 的本地文件搜索场景，直接用 bleve 是唯一合理起点；但配置错一个地方，比如字段没开 Index(true) 或中文没挂 gojieba 分词器，结果就是“搜不到”，且不报错。
bleve.New() 报 permission denied 怎么办
不是代码 bug，是目录根本不存在或没写权限。Go 不会自动建父目录，也不会帮你改 chmod。
- 必须提前调
os.MkdirAll("/path/to/index", 0755)，确保路径存在且可写 - 绝对路径优先，避免
"./index"这类相对路径——启动位置一变就失效 - Windows 下别硬写
"\index"，统一用filepath.Join("data", "myindex.bleve") -
bleve.New()只能用于空目录或不存在的路径；已有索引用bleve.Open()，否则报invalid index format
字段搜不出来，八成是 mapping 配错了
bleve 默认不索引任何字段，全靠 IndexMapping 显式声明。字段名大小写、嵌套层级、类型定义，错一个就静默失败。
- 文本字段必须同时设
field.Index(true)和field.Store(true)；光Store(true)不行 - 中文字段必须绑定分词器：
mapping.AddCustomAnalyzer("jieba", analyzer)+titleField.Analyzer = "jieba" - 数值/时间字段误设为
text类型，numeric_range查询永远不命中 - 字段名必须和实际结构完全一致：比如 struct 里是
FileName string `json:"file_name"`，查询就得写file_name:main.go，写FileName就查不到 - 推荐用
AddFieldMappingsAt("Body", bleve.NewTextFieldMapping())，比AddFieldMappingsFromStruct更可控
搜索慢、结果不准、高亮失效的常见坑
不是数据量大，是 query 类型和用法没对上。QueryStringQuery 看似方便，但默认行为容易误导。
立即学习“go语言免费学习笔记（深入）”；
- 搜短语如
"fast http"，别用QueryStringQuery("fast http")——它只是字面匹配；要用bleve.NewPhraseQuery([]string{"fast", "http"}) - 模糊搜索别只依赖
golang~，它只对单个 term 生效且编辑距离固定为 1；需要更灵活控制时，改用bleve.NewFuzzyQuery("golang").SetFuzziness(2) - 用户输入直接塞进
bleve.NewQueryStringQuery(userInput)即可，它自动处理引号、括号、AND/OR、通配符（te?t）、模糊（roam~） - 高亮需在
SearchRequest中启用：req.Highlight = &bleve.Highlight{...，且字段必须Store(true)
ID 必须稳定、唯一、无歧义，不能直接用文件路径
很多人直接把 filepath.Abs 结果当文档 ID，结果路径含特殊字符（比如 Windows 的 \ 或 URL 编码后的 %20）导致后续搜索失败或索引损坏。
- 绝对不要用
filepath.Base当 ID——同名文件（如多个README.md）会覆盖 - 推荐用文件内容哈希（如
sha256.Sum256）+ 修改时间戳拼接，例如fmt.Sprintf("%x-%d", hash[:8], fi.ModTime().Unix()) - 如果业务允许，ID 可以是数据库自增 ID 或 UUID，前提是文件和记录有可靠映射关系
-
bleve.Index的Index方法要传唯一 ID，不是文件路径；重复 ID 会导致旧文档被覆盖
真正难的不是建索引，而是让每个配置项都严丝合缝：目录权限、字段映射、分词器绑定、ID 生成逻辑、query 类型选择——漏掉任何一个，搜索就变成“看起来在跑，实际没结果”。
