及踩坑指南)
今天是“30天挑戰(zhàn)”的第11天整個項目剛好走完三分之一。先交代一下背景我在做的是一個本地優(yōu)先的 Markdown 知識管理工具 DayNotes要求數(shù)據(jù)完全離線、啟動速度快、折騰成本低。前 10 天已經(jīng)完成了文檔解析、編輯器、標(biāo)簽體系和列表頁今天集中攻一個繞不過去的功能——全文搜索。如果你也在做類似的知識庫、筆記工具或者本地文檔管理應(yīng)用這一篇應(yīng)該能幫你少走不少彎路尤其是涉及到中文分詞和桌面端性能的部分我會把踩過的坑和排查過程原原本本寫出來。1. 第11天的進度線從“正則匹配”到“全文索引”每天開工前我都會花 10 分鐘把當(dāng)天要做的功能拆成小塊寫在項目的 TODO 里。今天的標(biāo)簽是“搜索模塊”乍一聽范圍很大真正拆開其實就三塊索引怎么建、查詢怎么執(zhí)行、結(jié)果怎么展示。想清楚再動手寫代碼的速度會快很多。1.1 前10天做了什么為什么今天才開始做搜索DayNotes 前 10 天的功能比較基礎(chǔ)本地目錄掃描、Markdown 文件解析、編輯器支持即時預(yù)覽、標(biāo)簽體系、文檔列表的排序和篩選。在最初的設(shè)計里我其實沒有考慮索引搜索直接用最簡單粗暴的辦法——遞歸遍歷目錄對每個文件的文本內(nèi)容做正則匹配。剛開始內(nèi)容少的時候這個方法一點問題沒有。幾十篇文檔遍歷一遍也就幾十毫秒用戶根本感覺不出來。直到第 10 天我把手上攢了兩年的一千多篇 Markdown 筆記全部導(dǎo)進去之后情況急轉(zhuǎn)直下每次搜索要遍歷一千多個文件全部讀一遍再匹配慢的時候要兩三秒而且界面直接卡住因為讀取和正則匹配都是在主線程做的。正是在這個節(jié)點我才意識到不引入真正的全文索引后面沒法用了。這算是一個挺典型的教訓(xùn)前期做原型可以偷懶但當(dāng)你明顯感覺到“內(nèi)容量上來之后體驗崩壞”的瞬間就是該上正經(jīng)方案的時候了。DayNotes 的整體存儲層早就分開了元數(shù)據(jù)在 SQLite正文按文件路徑讀取所以今天加索引不需要動底層結(jié)構(gòu)這讓工作量小了不少。1.2 技術(shù)選型為什么最終選了SQLite FTS5桌面端做全文搜索可選方案其實不少。我把當(dāng)時認真考慮過的幾個方案列了個表方便對比方案優(yōu)點缺點結(jié)論Elasticsearch功能強、生態(tài)成熟要裝 Java 環(huán)境、起服務(wù)、占內(nèi)存對單機離線工具太重放棄Meilisearch / Typesense開箱即用、搜索體驗好需要額外進程部署和升級成本高放棄SQLite LIKE 通配查詢實現(xiàn)簡單沒有分詞、不能排序、一千篇就卡放棄SQLite FTS5 虛擬表內(nèi)嵌在庫里、零額外服務(wù)、支持 BM25 排序中文分詞要自己處理采用最終選 SQLite FTS5 是綜合考慮了離線、單機、輕量這三點。DayNotes 的元數(shù)據(jù)本來就在 SQLite 里FTS5 虛擬表可以直接建在同一份數(shù)據(jù)庫文件中不需要額外維護一個索引服務(wù)也不引入新的運行時依賴。對于“本地優(yōu)先”的工具來說這個方案是復(fù)雜度最低、可控性最高的。還有一個容易被忽略的好處FTS5 索引跟隨數(shù)據(jù)庫文件走備份、遷移、同步都統(tǒng)一了。如果將來要支持多設(shè)備同步索引也可以跟著數(shù)據(jù)庫一起處理不需要擔(dān)心本地文件和服務(wù)狀態(tài)不一致。這一點在我這種跨平臺小工具里非常重要。2. SQLite FTS5 做中文全文搜索三個必須繞開的坑FTS5 本身很成熟但它是為英文環(huán)境設(shè)計的默認行為對中文特別不友好。這幾個坑我基本是逐個踩過來的每一個都會導(dǎo)致“搜索結(jié)果完全不可用”。2.1 unicode61分詞器對中文等于沒有分詞FTS5 默認的分詞器是 unicode61它按照 Unicode 字符類型做切分。英文、數(shù)字這類能很好處理空格和標(biāo)點作為分隔符每個單詞建立索引。但中文沒有空格整段文字在 unicode61 眼里就是一個連續(xù)的“詞語”所以它只能把整句當(dāng)成一個 token。這會導(dǎo)致什么后果如果你的筆記里有“知識筆記軟件”這個詞你搜索“筆記”FTS5 是匹配不到的因為它建立索引的最小單位是整句話而不是“知識”“筆記”“軟件”這些詞。我當(dāng)時第一次跑通搜索輸入“筆記”結(jié)果返回空一度以為自己建表語句寫錯了。更麻煩的是FTS5 還默認把超長 token 給截斷默認情況下每個分詞單元的索引上限是 10 個字符。中文一句話遠超過這個長度后面的內(nèi)容根本不會進索引也就是說搜索“一篇長文中后半段的某個詞”永遠搜不到。要解決這個問題就得繞開默認分詞器在寫入索引之前自己做分詞把分詞結(jié)果按約定格式填進去。這也是我換到 jieba 的根本原因。2.2 用 jieba 預(yù)分詞索引側(cè)和查詢側(cè)要配合確定用 jieba 之后一個比較自然的思路是寫入時先把標(biāo)題和正文分詞用空格把詞拼起來存到 FTS5 表里查詢時也對用戶輸入分詞再拼成查詢語句。建表語句我改成了這樣CREATE VIRTUAL TABLE IF NOT EXISTS doc_search USING fts5( doc_id UNINDEXED, title, content_seg, content_raw, tokenize unicode61 );這里content_seg存的是分詞后的文本content_raw存原始正文用來在結(jié)果列表里做上下文摘要。查詢時配合 jieba 做同樣的分詞處理import jieba def build_query(text): words [w.strip() for w in jieba.cut(text) if w.strip()] return OR .join(f{w} for w in words)這里有一個很關(guān)鍵也很容易寫錯的細節(jié)查詢時拼出來的每個詞都要加雙引號否則 FTS5 會把用戶輸入當(dāng)成一個完整的短語去匹配分好詞也沒用。我當(dāng)時在這個地方吃了虧——索引側(cè)分詞做好了查詢側(cè)忘了給詞加引號結(jié)果搜“筆記軟件”時命中的是完整的“筆記軟件”短語而不是“筆記”和“軟件”兩個詞的任意匹配。另外jieba 的默認詞庫對通用中文處理得不錯但對專業(yè)領(lǐng)域術(shù)語識別很差。我的筆記里有大量技術(shù)名詞比如“Rust”“Tauri”“unmount”這類中英混合詞默認詞典經(jīng)常切得稀碎。解決辦法是維護一個自定義詞典文件把高頻術(shù)語加進去。2.3 索引同步機制增刪改怎么保持一致性建立一個索引只是第一步真正讓人頭疼的是后續(xù)的持續(xù)同步。文檔會新增、修改、刪除索引如果不跟著變搜索就變成垃圾數(shù)據(jù)展示。我在設(shè)計上采用了一個非常樸素的方案在應(yīng)用層做同步不搞數(shù)據(jù)庫觸發(fā)器。文檔保存的時候順帶調(diào)用一個sync_doc_to_index函數(shù)把該文檔從索引里刪掉再重新插入。流程拆開看大概是這么幾步文檔保存時讀取最新的標(biāo)題和正文用 jieba 對標(biāo)題和正文做分詞先從doc_search里刪除該doc_id的所有舊記錄再插入一條新記錄。這里要注意FTS5 虛擬表沒有主鍵約束如果用INSERT OR REPLACE去按doc_id覆蓋會因為doc_id不是真正的主鍵而插入重復(fù)行。所以邏輯上必須是“先刪后插”不能偷懶。剛一開始我圖省事只在文檔保存時同步?jīng)]有處理批量導(dǎo)入的場景。結(jié)果第 10 天我導(dǎo)入一千多篇文檔導(dǎo)入完成后索引是空的因為批量寫入路徑壓根沒有調(diào)用同步函數(shù)。后來我在導(dǎo)入流程的末尾統(tǒng)一執(zhí)行了一次全量重建索引# 先刪除整個虛擬表 DROP TABLE IF EXISTS doc_search; # 再建表 # 然后從 docs 表里重新讀取全部分詞寫入全量重建索引其實沒有想象中那么慢一千多篇 Markdown 文檔全部重新分詞再寫入在我的筆記本上大概也就是兩秒多。所以日常增量靠保存時同步批量操作后做一次重建索引一致性的問題就基本解決了。3. 本輪踩坑實錄從“搜不出”到“排序不對”的完整排查鏈路這一節(jié)我要完整記錄今天遇到的三個問題的排查過程。之所以寫這么細是因為這些問題的表象和根因離得很遠光看報錯信息完全無從下手必須自己一步步推。3.1 搜索“筆記”搜不出“知識筆記”分詞器的鍋問題出現(xiàn)得非常突然。第一輪功能做完之后我輸入“筆記”測試結(jié)果返回零條。數(shù)據(jù)庫里明明有十幾篇標(biāo)題帶“筆記”的文檔為什么搜不到排查第一步是驗證原始數(shù)據(jù)有沒有進索引。我直接打開 SQLite查doc_search表里有多少條記錄確認數(shù)據(jù)確實寫入了。第二步是看匹配行為單獨執(zhí)行SELECT doc_id, title FROM doc_search WHERE doc_search MATCH 筆記;返回空。換一個查法SELECT doc_id, title FROM doc_search WHERE doc_search MATCH 知識筆記;居然能查到。這一步基本確認了問題出在分詞索引里根本沒有“筆記”這個 token只有“知識筆記”這種整句 token。原因就是前面說的 unicode61 分詞器不切分中文。排查到這里方向已經(jīng)很清楚了不是數(shù)據(jù)問題不是查詢語法問題是分詞策略問題。解決方式不做展開——換成 jieba 預(yù)分詞之后重建索引再搜“筆記”能正常命中了。一個容易忽略的點是重建索引之后舊 token 還殘留在虛擬表里所以排查時一定記住先 DROP 再重建。3.2 輸入一個關(guān)鍵字CPU就飆升IPC通信和全表掃描分詞問題解決后搜索的核心功能能用了但隨之而來的是性能問題。我在輸入框里打了三個字應(yīng)用窗口就出現(xiàn)明顯的卡頓系統(tǒng)監(jiān)視器一看CPU 占用直接頂滿。一開始我以為是 FTS5 索引查詢本身慢后來仔細一想FTS5 對一千多篇文檔的索引查詢應(yīng)該是毫秒級不可能是瓶頸。于是我把排查重點放在調(diào)用鏈路上。DayNotes 用的框架里渲染進程和主進程之間通過 IPC 通信。我的搜索邏輯在主進程里執(zhí)行每次輸入框有內(nèi)容變化渲染進程就發(fā)一次 IPC 請求。關(guān)鍵在于我監(jiān)聽的是input事件每敲一個字符都會觸發(fā)一次請求。如果一句搜索詞有五個字輸入過程中就發(fā)了五次請求而且主進程每次都要連接數(shù)據(jù)庫、執(zhí)行查詢、把結(jié)果序列化回傳。還有一個隱藏的性能殺手我在主進程的搜索函數(shù)里拿到搜索結(jié)果后會讀取命中文檔的完整內(nèi)容來做上下文摘要。一千多篇文檔匹配到幾十篇每篇都要讀文件、截取摘要這個操作比索引查詢本身慢得多。解決分兩層渲染進程側(cè)加防抖用戶停止輸入 300ms 后才發(fā)請求主進程側(cè)只查結(jié)果的前 50 條并且摘要直接從 FTS5 表里存好的content_raw字段截取不額外讀磁盤文件。防抖代碼很簡單大概是這樣的let timer; inputElement.addEventListener(input, () { clearTimeout(timer); timer setTimeout(() { search(inputElement.value); }, 300); });加完之后即使連續(xù)輸入整句話實際查詢也只觸發(fā)一次CPU 占用基本可以忽略。3.3 標(biāo)題命中的結(jié)果排到了正文后面rank排序修正功能能跑、性能也上去了第三個問題浮出水面搜索結(jié)果排序不對。按常識標(biāo)題里包含關(guān)鍵詞的文章優(yōu)先級應(yīng)該高于正文里碰巧出現(xiàn)一次關(guān)鍵詞的文章。但實際結(jié)果恰恰相反正文提到的排在前面標(biāo)題命中的卻排到了后面。FTS5 默認的排序依據(jù)是 BM25 算法它會綜合考慮詞頻、文檔長度等因素打分。這個打分本身沒問題但它完全不理解“標(biāo)題命中”這件事在業(yè)務(wù)上的重要性。對于知識管理工具來說標(biāo)題命中往往意味著這篇文章就是講這個主題的正文命中可能只是順帶提到。修正方式是給排序加權(quán)重。FTS5 對每一行會算出一個rank值rank越小越靠前。我在ORDER BY里人為加上一個判斷如果標(biāo)題里包含搜索詞就給這行減一個固定值讓它排上去SELECT doc_id, title, rank FROM doc_search WHERE doc_search MATCH ? ORDER BY rank CASE WHEN title LIKE % || ? || % THEN -20 ELSE 0 END LIMIT 50;這種加權(quán)方式雖然粗暴但對于個人工具完全夠用。再進一步還可以給標(biāo)簽命中更高的權(quán)重這個今天沒做列進了后面的計劃里。排查過程中有一個值得記錄的細節(jié)很多人會直接把搜索詞拼進 SQL 里這在本地單機工具里問題不大但一旦數(shù)據(jù)源來自第三方就有 SQL 注入風(fēng)險。FTS5 的正規(guī)寫法是用MATCH ?傳參我全程都用占位符這個習(xí)慣值得長期保持。4. 搜索框背后容易被忽略的交互與性能細節(jié)搜索模塊的核心打通之后剩下的工作主要圍繞“好用”展開。功能能跑只是起點真正決定用戶感受的往往是那些技術(shù)棧之外的小細節(jié)。4.1 300ms防抖加過期請求丟棄防抖解決了“打字過程中反復(fù)請求”的問題但還有一個并發(fā)場景沒處理如果用戶在防抖生效之前快速按了回車上一個請求還沒返回新的請求就發(fā)出去了。這種情況下兩個請求的返回順序是不確定的先發(fā)出的請求后返回就會把較新的結(jié)果覆蓋掉造成搜索結(jié)果落后于輸入框內(nèi)容。解決辦法是在渲染進程維護一個自增的請求編號let requestId 0; async function search(keyword) { const currentId requestId; const results await window.api.search(keyword); if (currentId ! requestId) return; // 過期結(jié)果直接丟棄 renderResults(results); }這個模式在很多場景下都通用尤其是桌面端和前端交互。思路很簡單每次都把請求編號遞增哪個結(jié)果回來時發(fā)現(xiàn)自己已經(jīng)不是最新編號了就放棄渲染。4.2 搜索高亮的正確姿勢先轉(zhuǎn)義再渲染搜索結(jié)果列表里匹配的關(guān)鍵詞需要高亮否則用戶看不出為什么這篇被搜出來了。我一開始直接用正則替換原始正文把命中詞替換成mark命中詞/mark然后塞進渲染層。寫完一測發(fā)現(xiàn)一個嚴(yán)重安全漏洞——如果正文本身包含 HTML 標(biāo)簽比如一篇講前端開發(fā)的筆記里寫了div這個標(biāo)簽會被渲染層當(dāng)成真正的 DOM 執(zhí)行。正確順序必須是先把原始文本做 HTML 轉(zhuǎn)義再做高亮替換。比如function escapeHtml(text) { return text .replace(//g, amp;) .replace(//g, lt;) .replace(//g, gt;) .replace(//g, quot;) .replace(//g, #039;); } function highlight(text, terms) { const safe escapeHtml(text); const escapedTerms terms.map(escapeHtml); let result safe; for (const term of escapedTerms) { result result.replaceAll(term, (match) mark${match}/mark); } return result; }先轉(zhuǎn)義再替換既能保證高亮生效又不會讓原始 HTML 破壞頁面結(jié)構(gòu)。順便一提replaceAll里面用函數(shù)作為參數(shù)是為了避免$這種特殊替換變量的坑寫的時候容易被忽略。4.3 空態(tài)、快捷鍵和索引狀態(tài)感知細節(jié)上我還做了幾個不起眼但價值很大的功能。搜索無結(jié)果時的空態(tài)我一開始只顯示了“沒有找到匹配內(nèi)容”一行字后來發(fā)現(xiàn)這樣很容易讓用戶陷入死胡同?，F(xiàn)在空態(tài)里會提示嘗試縮短關(guān)鍵詞、檢查是否有錯別字、或者去設(shè)置里重建索引。實際使用中很多“搜不到”的問題根源是索引沒有跟上給出重建索引的引導(dǎo)能省掉很多用戶困惑。全局快捷鍵CtrlK聚焦搜索框這已經(jīng)是這類工具的標(biāo)配了我之前的編輯器里其實已經(jīng)有了今天只是把觸發(fā)邏輯統(tǒng)一到搜索組件上。還有一個小細節(jié)搜索框里輸入全角空格或者只有空格的字符串時不會發(fā)起搜索請求避免又一次無意義的 IPC。索引狀態(tài)感知也是一個容易漏掉的功能。我在設(shè)置頁里增加了一個“索引信息”面板顯示當(dāng)前索引了多少文檔、最近一次重建時間、自建詞典的詞條數(shù)。這看起來像是開發(fā)者接口但對個人工具來說它是排查“為什么搜不到”的第一入口。5. 30天挑戰(zhàn)過半我重新思考“搜索”這件事今天是第 11 天項目已過三分之一正好借這個機會做一次階段性復(fù)盤。我發(fā)現(xiàn)做知識管理工具搜索不僅僅是一個功能模塊它在很大程度上決定了用戶對這個工具的信任感。5.1 這11天最大的教訓(xùn)接口預(yù)留與過早優(yōu)化回頭看我前 10 天的代碼最慶幸的是當(dāng)初做存儲層的時候把“元數(shù)據(jù)”和“正文內(nèi)容”明確分開了。文檔表只存標(biāo)題、路徑、標(biāo)簽、創(chuàng)建時間這些結(jié)構(gòu)化數(shù)據(jù)正文通過文件路徑按需讀取。這個設(shè)計當(dāng)時只是出于“Markdown 文件本來就應(yīng)該直接存在磁盤上”的直覺沒想到今天加搜索引擎時幾乎不用改動原來的數(shù)據(jù)層直接在旁邊多建一張 FTS5 虛擬表就接上了。這一點其實比“一開始就設(shè)計好搜索功能”更重要——前期搜索需求不明確如果強行一開始就設(shè)計索引結(jié)構(gòu)大概率會根據(jù)錯誤的假設(shè)做出過度設(shè)計。更合理的做法是保證層與層之間的邊界清晰給未來的功能留出插入位置而不是提前把所有擴展點都實現(xiàn)。與之相對的另一個極端是過早優(yōu)化。我最初沒加搜索原因就是覺得“內(nèi)容少用正則也行”。事實證明這個決定是對的正是因為內(nèi)容量到了臨界點、體驗真實惡化我才理解了為什么需要索引而不是憑空想象出一個性能問題。過早引入 ES 或者重型的搜索服務(wù)只會讓項目陷入維護泥潭。5.2 明天的計劃可配置的詞庫和重建索引入口雖然今天的搜索功能已經(jīng)能正常使用了但距離“順手”還有一段距離。我整理了幾個必須要做的東西設(shè)置頁增加“重建索引”按鈕配合進度提示解決用戶遇到搜索異常時的自救途徑自建詞典的可視化管理方便把常用術(shù)語直接加進詞庫不用改配置文件重啟標(biāo)簽權(quán)重加分讓標(biāo)簽命中排在標(biāo)題命中前面增強檢索業(yè)務(wù)語義搜索歷史記錄把最近的搜索詞存在本地方便重復(fù)查找。這些功能都不復(fù)雜難點在于接口怎么設(shè)計得順滑。比如重建索引進度提示如果索引量少根本不需要進度條但如果文檔量上千就必須給用戶一個明確的“在做什么”的狀態(tài)反饋避免誤以為卡死。寫到這里我想多說一句個人體會。做本地優(yōu)先的工具最大的幸福感其實來自“它能自己持續(xù)變得好用”這件事。前 10 天寫編輯器、寫標(biāo)簽系統(tǒng)是給自己造器皿這一天的搜索功能做出來之后我每天記錄筆記時終于敢往里面堆量了因為我知道「找得到」這個底線已經(jīng)被守住了。30 天的項目還在繼續(xù)明天繼續(xù)解決新問題。 基于SQLite FTS5的中文全文搜索實現(xiàn)及踩坑指南
今天是“30天挑戰(zhàn)”的第11天整個項目剛好走完三分之一。先交代一下背景我在做的是一個本地優(yōu)先的 Markdown 知識管理工具 DayNotes要求數(shù)據(jù)完全離線、啟動速度快、折騰成本低。前 10 天已經(jīng)完成了文檔解析、編輯器、標(biāo)簽體系和列表頁今天集中攻一個繞不過去的功能——全文搜索。如果你也在做類似的知識庫、筆記工具或者本地文檔管理應(yīng)用這一篇應(yīng)該能幫你少走不少彎路尤其是涉及到中文分詞和桌面端性能的部分我會把踩過的坑和排查過程原原本本寫出來。1. 第11天的進度線從“正則匹配”到“全文索引”每天開工前我都會花 10 分鐘把當(dāng)天要做的功能拆成小塊寫在項目的 TODO 里。今天的標(biāo)簽是“搜索模塊”乍一聽范圍很大真正拆開其實就三塊索引怎么建、查詢怎么執(zhí)行、結(jié)果怎么展示。想清楚再動手寫代碼的速度會快很多。1.1 前10天做了什么為什么今天才開始做搜索DayNotes 前 10 天的功能比較基礎(chǔ)本地目錄掃描、Markdown 文件解析、編輯器支持即時預(yù)覽、標(biāo)簽體系、文檔列表的排序和篩選。在最初的設(shè)計里我其實沒有考慮索引搜索直接用最簡單粗暴的辦法——遞歸遍歷目錄對每個文件的文本內(nèi)容做正則匹配。剛開始內(nèi)容少的時候這個方法一點問題沒有。幾十篇文檔遍歷一遍也就幾十毫秒用戶根本感覺不出來。直到第 10 天我把手上攢了兩年的一千多篇 Markdown 筆記全部導(dǎo)進去之后情況急轉(zhuǎn)直下每次搜索要遍歷一千多個文件全部讀一遍再匹配慢的時候要兩三秒而且界面直接卡住因為讀取和正則匹配都是在主線程做的。正是在這個節(jié)點我才意識到不引入真正的全文索引后面沒法用了。這算是一個挺典型的教訓(xùn)前期做原型可以偷懶但當(dāng)你明顯感覺到“內(nèi)容量上來之后體驗崩壞”的瞬間就是該上正經(jīng)方案的時候了。DayNotes 的整體存儲層早就分開了元數(shù)據(jù)在 SQLite正文按文件路徑讀取所以今天加索引不需要動底層結(jié)構(gòu)這讓工作量小了不少。1.2 技術(shù)選型為什么最終選了SQLite FTS5桌面端做全文搜索可選方案其實不少。我把當(dāng)時認真考慮過的幾個方案列了個表方便對比方案優(yōu)點缺點結(jié)論Elasticsearch功能強、生態(tài)成熟要裝 Java 環(huán)境、起服務(wù)、占內(nèi)存對單機離線工具太重放棄Meilisearch / Typesense開箱即用、搜索體驗好需要額外進程部署和升級成本高放棄SQLite LIKE 通配查詢實現(xiàn)簡單沒有分詞、不能排序、一千篇就卡放棄SQLite FTS5 虛擬表內(nèi)嵌在庫里、零額外服務(wù)、支持 BM25 排序中文分詞要自己處理采用最終選 SQLite FTS5 是綜合考慮了離線、單機、輕量這三點。DayNotes 的元數(shù)據(jù)本來就在 SQLite 里FTS5 虛擬表可以直接建在同一份數(shù)據(jù)庫文件中不需要額外維護一個索引服務(wù)也不引入新的運行時依賴。對于“本地優(yōu)先”的工具來說這個方案是復(fù)雜度最低、可控性最高的。還有一個容易被忽略的好處FTS5 索引跟隨數(shù)據(jù)庫文件走備份、遷移、同步都統(tǒng)一了。如果將來要支持多設(shè)備同步索引也可以跟著數(shù)據(jù)庫一起處理不需要擔(dān)心本地文件和服務(wù)狀態(tài)不一致。這一點在我這種跨平臺小工具里非常重要。2. SQLite FTS5 做中文全文搜索三個必須繞開的坑FTS5 本身很成熟但它是為英文環(huán)境設(shè)計的默認行為對中文特別不友好。這幾個坑我基本是逐個踩過來的每一個都會導(dǎo)致“搜索結(jié)果完全不可用”。2.1 unicode61分詞器對中文等于沒有分詞FTS5 默認的分詞器是 unicode61它按照 Unicode 字符類型做切分。英文、數(shù)字這類能很好處理空格和標(biāo)點作為分隔符每個單詞建立索引。但中文沒有空格整段文字在 unicode61 眼里就是一個連續(xù)的“詞語”所以它只能把整句當(dāng)成一個 token。這會導(dǎo)致什么后果如果你的筆記里有“知識筆記軟件”這個詞你搜索“筆記”FTS5 是匹配不到的因為它建立索引的最小單位是整句話而不是“知識”“筆記”“軟件”這些詞。我當(dāng)時第一次跑通搜索輸入“筆記”結(jié)果返回空一度以為自己建表語句寫錯了。更麻煩的是FTS5 還默認把超長 token 給截斷默認情況下每個分詞單元的索引上限是 10 個字符。中文一句話遠超過這個長度后面的內(nèi)容根本不會進索引也就是說搜索“一篇長文中后半段的某個詞”永遠搜不到。要解決這個問題就得繞開默認分詞器在寫入索引之前自己做分詞把分詞結(jié)果按約定格式填進去。這也是我換到 jieba 的根本原因。2.2 用 jieba 預(yù)分詞索引側(cè)和查詢側(cè)要配合確定用 jieba 之后一個比較自然的思路是寫入時先把標(biāo)題和正文分詞用空格把詞拼起來存到 FTS5 表里查詢時也對用戶輸入分詞再拼成查詢語句。建表語句我改成了這樣CREATE VIRTUAL TABLE IF NOT EXISTS doc_search USING fts5( doc_id UNINDEXED, title, content_seg, content_raw, tokenize unicode61 );這里content_seg存的是分詞后的文本content_raw存原始正文用來在結(jié)果列表里做上下文摘要。查詢時配合 jieba 做同樣的分詞處理import jieba def build_query(text): words [w.strip() for w in jieba.cut(text) if w.strip()] return OR .join(f{w} for w in words)這里有一個很關(guān)鍵也很容易寫錯的細節(jié)查詢時拼出來的每個詞都要加雙引號否則 FTS5 會把用戶輸入當(dāng)成一個完整的短語去匹配分好詞也沒用。我當(dāng)時在這個地方吃了虧——索引側(cè)分詞做好了查詢側(cè)忘了給詞加引號結(jié)果搜“筆記軟件”時命中的是完整的“筆記軟件”短語而不是“筆記”和“軟件”兩個詞的任意匹配。另外jieba 的默認詞庫對通用中文處理得不錯但對專業(yè)領(lǐng)域術(shù)語識別很差。我的筆記里有大量技術(shù)名詞比如“Rust”“Tauri”“unmount”這類中英混合詞默認詞典經(jīng)常切得稀碎。解決辦法是維護一個自定義詞典文件把高頻術(shù)語加進去。2.3 索引同步機制增刪改怎么保持一致性建立一個索引只是第一步真正讓人頭疼的是后續(xù)的持續(xù)同步。文檔會新增、修改、刪除索引如果不跟著變搜索就變成垃圾數(shù)據(jù)展示。我在設(shè)計上采用了一個非常樸素的方案在應(yīng)用層做同步不搞數(shù)據(jù)庫觸發(fā)器。文檔保存的時候順帶調(diào)用一個sync_doc_to_index函數(shù)把該文檔從索引里刪掉再重新插入。流程拆開看大概是這么幾步文檔保存時讀取最新的標(biāo)題和正文用 jieba 對標(biāo)題和正文做分詞先從doc_search里刪除該doc_id的所有舊記錄再插入一條新記錄。這里要注意FTS5 虛擬表沒有主鍵約束如果用INSERT OR REPLACE去按doc_id覆蓋會因為doc_id不是真正的主鍵而插入重復(fù)行。所以邏輯上必須是“先刪后插”不能偷懶。剛一開始我圖省事只在文檔保存時同步?jīng)]有處理批量導(dǎo)入的場景。結(jié)果第 10 天我導(dǎo)入一千多篇文檔導(dǎo)入完成后索引是空的因為批量寫入路徑壓根沒有調(diào)用同步函數(shù)。后來我在導(dǎo)入流程的末尾統(tǒng)一執(zhí)行了一次全量重建索引# 先刪除整個虛擬表 DROP TABLE IF EXISTS doc_search; # 再建表 # 然后從 docs 表里重新讀取全部分詞寫入全量重建索引其實沒有想象中那么慢一千多篇 Markdown 文檔全部重新分詞再寫入在我的筆記本上大概也就是兩秒多。所以日常增量靠保存時同步批量操作后做一次重建索引一致性的問題就基本解決了。3. 本輪踩坑實錄從“搜不出”到“排序不對”的完整排查鏈路這一節(jié)我要完整記錄今天遇到的三個問題的排查過程。之所以寫這么細是因為這些問題的表象和根因離得很遠光看報錯信息完全無從下手必須自己一步步推。3.1 搜索“筆記”搜不出“知識筆記”分詞器的鍋問題出現(xiàn)得非常突然。第一輪功能做完之后我輸入“筆記”測試結(jié)果返回零條。數(shù)據(jù)庫里明明有十幾篇標(biāo)題帶“筆記”的文檔為什么搜不到排查第一步是驗證原始數(shù)據(jù)有沒有進索引。我直接打開 SQLite查doc_search表里有多少條記錄確認數(shù)據(jù)確實寫入了。第二步是看匹配行為單獨執(zhí)行SELECT doc_id, title FROM doc_search WHERE doc_search MATCH 筆記;返回空。換一個查法SELECT doc_id, title FROM doc_search WHERE doc_search MATCH 知識筆記;居然能查到。這一步基本確認了問題出在分詞索引里根本沒有“筆記”這個 token只有“知識筆記”這種整句 token。原因就是前面說的 unicode61 分詞器不切分中文。排查到這里方向已經(jīng)很清楚了不是數(shù)據(jù)問題不是查詢語法問題是分詞策略問題。解決方式不做展開——換成 jieba 預(yù)分詞之后重建索引再搜“筆記”能正常命中了。一個容易忽略的點是重建索引之后舊 token 還殘留在虛擬表里所以排查時一定記住先 DROP 再重建。3.2 輸入一個關(guān)鍵字CPU就飆升IPC通信和全表掃描分詞問題解決后搜索的核心功能能用了但隨之而來的是性能問題。我在輸入框里打了三個字應(yīng)用窗口就出現(xiàn)明顯的卡頓系統(tǒng)監(jiān)視器一看CPU 占用直接頂滿。一開始我以為是 FTS5 索引查詢本身慢后來仔細一想FTS5 對一千多篇文檔的索引查詢應(yīng)該是毫秒級不可能是瓶頸。于是我把排查重點放在調(diào)用鏈路上。DayNotes 用的框架里渲染進程和主進程之間通過 IPC 通信。我的搜索邏輯在主進程里執(zhí)行每次輸入框有內(nèi)容變化渲染進程就發(fā)一次 IPC 請求。關(guān)鍵在于我監(jiān)聽的是input事件每敲一個字符都會觸發(fā)一次請求。如果一句搜索詞有五個字輸入過程中就發(fā)了五次請求而且主進程每次都要連接數(shù)據(jù)庫、執(zhí)行查詢、把結(jié)果序列化回傳。還有一個隱藏的性能殺手我在主進程的搜索函數(shù)里拿到搜索結(jié)果后會讀取命中文檔的完整內(nèi)容來做上下文摘要。一千多篇文檔匹配到幾十篇每篇都要讀文件、截取摘要這個操作比索引查詢本身慢得多。解決分兩層渲染進程側(cè)加防抖用戶停止輸入 300ms 后才發(fā)請求主進程側(cè)只查結(jié)果的前 50 條并且摘要直接從 FTS5 表里存好的content_raw字段截取不額外讀磁盤文件。防抖代碼很簡單大概是這樣的let timer; inputElement.addEventListener(input, () { clearTimeout(timer); timer setTimeout(() { search(inputElement.value); }, 300); });加完之后即使連續(xù)輸入整句話實際查詢也只觸發(fā)一次CPU 占用基本可以忽略。3.3 標(biāo)題命中的結(jié)果排到了正文后面rank排序修正功能能跑、性能也上去了第三個問題浮出水面搜索結(jié)果排序不對。按常識標(biāo)題里包含關(guān)鍵詞的文章優(yōu)先級應(yīng)該高于正文里碰巧出現(xiàn)一次關(guān)鍵詞的文章。但實際結(jié)果恰恰相反正文提到的排在前面標(biāo)題命中的卻排到了后面。FTS5 默認的排序依據(jù)是 BM25 算法它會綜合考慮詞頻、文檔長度等因素打分。這個打分本身沒問題但它完全不理解“標(biāo)題命中”這件事在業(yè)務(wù)上的重要性。對于知識管理工具來說標(biāo)題命中往往意味著這篇文章就是講這個主題的正文命中可能只是順帶提到。修正方式是給排序加權(quán)重。FTS5 對每一行會算出一個rank值rank越小越靠前。我在ORDER BY里人為加上一個判斷如果標(biāo)題里包含搜索詞就給這行減一個固定值讓它排上去SELECT doc_id, title, rank FROM doc_search WHERE doc_search MATCH ? ORDER BY rank CASE WHEN title LIKE % || ? || % THEN -20 ELSE 0 END LIMIT 50;這種加權(quán)方式雖然粗暴但對于個人工具完全夠用。再進一步還可以給標(biāo)簽命中更高的權(quán)重這個今天沒做列進了后面的計劃里。排查過程中有一個值得記錄的細節(jié)很多人會直接把搜索詞拼進 SQL 里這在本地單機工具里問題不大但一旦數(shù)據(jù)源來自第三方就有 SQL 注入風(fēng)險。FTS5 的正規(guī)寫法是用MATCH ?傳參我全程都用占位符這個習(xí)慣值得長期保持。4. 搜索框背后容易被忽略的交互與性能細節(jié)搜索模塊的核心打通之后剩下的工作主要圍繞“好用”展開。功能能跑只是起點真正決定用戶感受的往往是那些技術(shù)棧之外的小細節(jié)。4.1 300ms防抖加過期請求丟棄防抖解決了“打字過程中反復(fù)請求”的問題但還有一個并發(fā)場景沒處理如果用戶在防抖生效之前快速按了回車上一個請求還沒返回新的請求就發(fā)出去了。這種情況下兩個請求的返回順序是不確定的先發(fā)出的請求后返回就會把較新的結(jié)果覆蓋掉造成搜索結(jié)果落后于輸入框內(nèi)容。解決辦法是在渲染進程維護一個自增的請求編號let requestId 0; async function search(keyword) { const currentId requestId; const results await window.api.search(keyword); if (currentId ! requestId) return; // 過期結(jié)果直接丟棄 renderResults(results); }這個模式在很多場景下都通用尤其是桌面端和前端交互。思路很簡單每次都把請求編號遞增哪個結(jié)果回來時發(fā)現(xiàn)自己已經(jīng)不是最新編號了就放棄渲染。4.2 搜索高亮的正確姿勢先轉(zhuǎn)義再渲染搜索結(jié)果列表里匹配的關(guān)鍵詞需要高亮否則用戶看不出為什么這篇被搜出來了。我一開始直接用正則替換原始正文把命中詞替換成mark命中詞/mark然后塞進渲染層。寫完一測發(fā)現(xiàn)一個嚴(yán)重安全漏洞——如果正文本身包含 HTML 標(biāo)簽比如一篇講前端開發(fā)的筆記里寫了div這個標(biāo)簽會被渲染層當(dāng)成真正的 DOM 執(zhí)行。正確順序必須是先把原始文本做 HTML 轉(zhuǎn)義再做高亮替換。比如function escapeHtml(text) { return text .replace(//g, amp;) .replace(//g, lt;) .replace(//g, gt;) .replace(//g, quot;) .replace(//g, #039;); } function highlight(text, terms) { const safe escapeHtml(text); const escapedTerms terms.map(escapeHtml); let result safe; for (const term of escapedTerms) { result result.replaceAll(term, (match) mark${match}/mark); } return result; }先轉(zhuǎn)義再替換既能保證高亮生效又不會讓原始 HTML 破壞頁面結(jié)構(gòu)。順便一提replaceAll里面用函數(shù)作為參數(shù)是為了避免$這種特殊替換變量的坑寫的時候容易被忽略。4.3 空態(tài)、快捷鍵和索引狀態(tài)感知細節(jié)上我還做了幾個不起眼但價值很大的功能。搜索無結(jié)果時的空態(tài)我一開始只顯示了“沒有找到匹配內(nèi)容”一行字后來發(fā)現(xiàn)這樣很容易讓用戶陷入死胡同?，F(xiàn)在空態(tài)里會提示嘗試縮短關(guān)鍵詞、檢查是否有錯別字、或者去設(shè)置里重建索引。實際使用中很多“搜不到”的問題根源是索引沒有跟上給出重建索引的引導(dǎo)能省掉很多用戶困惑。全局快捷鍵CtrlK聚焦搜索框這已經(jīng)是這類工具的標(biāo)配了我之前的編輯器里其實已經(jīng)有了今天只是把觸發(fā)邏輯統(tǒng)一到搜索組件上。還有一個小細節(jié)搜索框里輸入全角空格或者只有空格的字符串時不會發(fā)起搜索請求避免又一次無意義的 IPC。索引狀態(tài)感知也是一個容易漏掉的功能。我在設(shè)置頁里增加了一個“索引信息”面板顯示當(dāng)前索引了多少文檔、最近一次重建時間、自建詞典的詞條數(shù)。這看起來像是開發(fā)者接口但對個人工具來說它是排查“為什么搜不到”的第一入口。5. 30天挑戰(zhàn)過半我重新思考“搜索”這件事今天是第 11 天項目已過三分之一正好借這個機會做一次階段性復(fù)盤。我發(fā)現(xiàn)做知識管理工具搜索不僅僅是一個功能模塊它在很大程度上決定了用戶對這個工具的信任感。5.1 這11天最大的教訓(xùn)接口預(yù)留與過早優(yōu)化回頭看我前 10 天的代碼最慶幸的是當(dāng)初做存儲層的時候把“元數(shù)據(jù)”和“正文內(nèi)容”明確分開了。文檔表只存標(biāo)題、路徑、標(biāo)簽、創(chuàng)建時間這些結(jié)構(gòu)化數(shù)據(jù)正文通過文件路徑按需讀取。這個設(shè)計當(dāng)時只是出于“Markdown 文件本來就應(yīng)該直接存在磁盤上”的直覺沒想到今天加搜索引擎時幾乎不用改動原來的數(shù)據(jù)層直接在旁邊多建一張 FTS5 虛擬表就接上了。這一點其實比“一開始就設(shè)計好搜索功能”更重要——前期搜索需求不明確如果強行一開始就設(shè)計索引結(jié)構(gòu)大概率會根據(jù)錯誤的假設(shè)做出過度設(shè)計。更合理的做法是保證層與層之間的邊界清晰給未來的功能留出插入位置而不是提前把所有擴展點都實現(xiàn)。與之相對的另一個極端是過早優(yōu)化。我最初沒加搜索原因就是覺得“內(nèi)容少用正則也行”。事實證明這個決定是對的正是因為內(nèi)容量到了臨界點、體驗真實惡化我才理解了為什么需要索引而不是憑空想象出一個性能問題。過早引入 ES 或者重型的搜索服務(wù)只會讓項目陷入維護泥潭。5.2 明天的計劃可配置的詞庫和重建索引入口雖然今天的搜索功能已經(jīng)能正常使用了但距離“順手”還有一段距離。我整理了幾個必須要做的東西設(shè)置頁增加“重建索引”按鈕配合進度提示解決用戶遇到搜索異常時的自救途徑自建詞典的可視化管理方便把常用術(shù)語直接加進詞庫不用改配置文件重啟標(biāo)簽權(quán)重加分讓標(biāo)簽命中排在標(biāo)題命中前面增強檢索業(yè)務(wù)語義搜索歷史記錄把最近的搜索詞存在本地方便重復(fù)查找。這些功能都不復(fù)雜難點在于接口怎么設(shè)計得順滑。比如重建索引進度提示如果索引量少根本不需要進度條但如果文檔量上千就必須給用戶一個明確的“在做什么”的狀態(tài)反饋避免誤以為卡死。寫到這里我想多說一句個人體會。做本地優(yōu)先的工具最大的幸福感其實來自“它能自己持續(xù)變得好用”這件事。前 10 天寫編輯器、寫標(biāo)簽系統(tǒng)是給自己造器皿這一天的搜索功能做出來之后我每天記錄筆記時終于敢往里面堆量了因為我知道「找得到」這個底線已經(jīng)被守住了。30 天的項目還在繼續(xù)明天繼續(xù)解決新問題。