直接用bleve是当前最稳路径，手写倒排索引仅适合教学或极特殊嵌入场景；关键在于避免绕过bleve处理分词配置、字段映射、并发写入、落盘保证等已知坑。

直接用 bleve 是当前最稳的路径，手写倒排索引只适合教学或极特殊嵌入场景；关键不是“能不能写”，而是“值不值得绕过 bleve 去处理分词配置、字段映射、并发写入、落盘保证这些已知坑”。

bleve.New() 报 permission denied 或 invalid index format 怎么办

这不是代码逻辑错误，是路径生命周期管理没到位——bleve.New() 不创建父目录、不改权限、也不兼容已有数据。

• 必须提前调 os.MkdirAll("/abs/path/to/index", 0755)，确保路径存在且可写
• 绝对别用 "./index" 这类相对路径；推荐用 filepath.Join(filepath.Dir(os.Args[0]), "index")
• 已有索引要复用？必须用 bleve.Open()，不是 bleve.New()；后者会强行覆盖格式，报 invalid index format
• Windows 下路径拼接统一用 filepath.Join()，硬写 "\index" 在 CI 或 Docker 里必挂

中文搜不到关键词的三个硬性条件

bleve 默认完全不支持中文分词，不配 analyzer 就等于没索引中文内容。漏掉任意一条，结果就是静默查不到。

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

• 必须显式注册中文分词器：比如用 github.com/go-ego/gse，初始化 seg := gse.NewGse("")，再包装成 analysis.CustomAnalyzer
• 字段 mapping 必须指定该 analyzer：mapping.AddFieldMapping("Content", "text").Analyzer("jieba")，光设 Index(true) 没用
• 索引文档时字段名必须和 mapping 中声明的**完全一致**（大小写敏感），json:"content" 和 Content 是两个字段

SearchRequest 返回空结果但无报错的常见原因

这是最典型的配置静默失败，90% 出现在字段未启用索引或查询语法不匹配。

• 文本字段必须同时设 field.Index(true) 和 field.Store(true)；光 Store(true) 不行，高亮也拿不到原文
• QueryStringQuery("title:go") 中的 title 必须和 mapping 中定义的字段名一字不差；驼峰字段如 Title 要写成 Title:go
• 短语搜索必须用 bleve.NewPhraseQuery([]string{"fast", "http"})；QueryStringQuery("fast http") 只是字面匹配
• 模糊搜索别只依赖 golang~，它只对单个 term 生效且编辑距离固定为 1；需要更灵活控制时，改用 bleve.NewFuzzyQuery("golang").SetFuzziness(2)

并发写入 panic: concurrent map read and map write 怎么解决

bleve.Index 实例**不是 goroutine 安全的**，多个协程直接调 index.Index() 必崩。

• 不要自己加 sync.Mutex 包一层了事——锁粒度太粗，吞吐上不去
• 推荐串行写入：用 channel 控制写入节奏，或批量调 index.Batch() 提交
• 写完必须调 index.Close() 才能落盘；不关就重启，数据大概率丢失
• 若真需并发索引，按文件分片建多个 Index 实例，查时合并结果

真正难的不是读文件，而是判断“这行值不值得索引”——日志里带毫秒时间戳的行，你索引的是结构化字段还是整段字符串，决定了内存是否爆炸、GC 是否卡顿、后续能否增量更新。这些细节，bleve 不帮你做，但也不会让你在分词、映射、路径、ID、并发这些地方反复踩坑。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！