Pagefind怎麼用 靜態網站搜尋工具教程

Pagefind是一個靜態網站搜尋工具，構建後自動生成搜尋索引，不用伺服器，適合給部落格和文件站加搜尋功能。它讀取靜態生成器輸出的HTML，把索引檔案和瀏覽器端搜尋資源寫入網站目錄；訪客搜尋時由瀏覽器載入所需索引內容。下面以構建結果位於public/、使用Node.js為例，帶你完成安裝、索引和頁面接入。

第一步：安裝Pagefind

先確認專案能正常構建，並找到靜態檔案輸出目錄，比如Hugo常見的public/，也可能是dist/或_site/。Pagefind要讀取的是已經生成的HTML，而不是開發伺服器裡的原始碼模板。開啟終端進入專案根目錄，若還沒有Node.js環境，先安裝Node.js；已有環境可直接用npx執行，不必把工具永久加入專案依賴。

最省事的方式是在構建完成後執行npx -y pagefind –site public。這裡public是示例路徑，請換成自己的網站輸出目錄；路徑寫錯時，Pagefind可能找不到頁面或索引到錯誤檔案。首次執行會下載並執行Pagefind，終端會顯示索引頁面數、詞數和生成檔案等資訊。臨時預覽可加–serve，它會啟動本地預覽服務，常見埠為1414。

如果團隊希望每次構建使用固定版本，可以把Pagefind作為開發依賴安裝，再在專案指令碼里串接“站點構建”和“生成索引”。關鍵是先完成靜態站點構建，再執行Pagefind；部署時要把生成後的整個輸出目錄一併釋出。Pagefind本身不提供線上搜尋伺服器，–serve只是本地測試用的預覽方式。

第二步：構建搜尋索引

先用站點生成器構建頁面，再執行npx -y pagefind –site public。成功後檢查public/pagefind/目錄，裡面會有瀏覽器端依賴和搜尋索引檔案。部署前確認這個目錄沒有被清理、忽略或漏傳；如果託管平臺只上傳了部分檔案，搜尋框可能出現，但索引請求會失敗。更新文章後也要重新構建索引，否則新內容不會出現在搜尋結果裡。

建議把命令加入自動化構建流程，例如在package.json的指令碼中先執行靜態站點構建，再執行pagefind –site public。具體構建命令取決於框架，不能照抄示例名稱；檢查CI日誌，確認Pagefind執行在HTML生成之後。若站點輸出目錄不是public，就同步修改引數。釋出後可在瀏覽器開發者工具的網路面板檢查/pagefind/資源是否正常返回。

配置過濾和分詞

需要控制索引範圍時，可在頁面內容區加data-pagefind-body，讓搜尋重點落在正文；如果全站使用這個標記，記得其他也要被搜尋的頁面同樣新增，否則未標記頁面可能不會進入索引。正文裡的側欄、推薦內容等噪聲，可加data-pagefind-ignore排除。若想按作者或分類篩選，在對應元素上新增data-pagefind-filter=”category”，元素文字會作為篩選值。

Pagefind通常會自動識別頁面語言並建立相應索引。給HTML根元素設定正確的lang屬性，例如中文頁面使用適當的中文語言標記，有助於語言識別；不要把它理解成需要逐篇手動切詞的傳統分詞配置。若搜尋標點符號很重要，比如程式碼文件裡的尖括號，可在配置中用include_characters保留指定字元。修改後重新執行索引命令，再用中英文關鍵詞、標點和過濾條件逐項測試。

第三步：嵌入搜尋UI

Pagefind提供可直接使用的搜尋元件。將下面三行放入希望顯示搜尋入口的頁面模板，路徑應與部署後的站點根路徑匹配；隨後重新構建網站並再次執行Pagefind，因為元件資源會在索引構建時生成。Pagefind當前入門文件示例使用pagefind-component-ui資源及模態框觸發器，適合先快速驗證，再按專案佈局調整樣式和互動。

<link href=”/pagefind/pagefind-component-ui.css” rel=”stylesheet”>
<script src=”/pagefind/pagefind-component-ui.js” type=”module”></script>
<pagefind-modal-trigger></pagefind-modal-trigger>
<pagefind-modal></pagefind-modal>

釋出後開啟搜尋入口，輸入一段確定存在於文章正文的詞，檢查結果標題、摘要和連結是否正確，再測試無結果的情況。若搜尋資源報404，優先核對輸出目錄、部署路徑和資源地址；若搜不到頁面，檢查構建日誌、頁面是否生成HTML、索引範圍標記是否覆蓋該頁面，以及部署時是否包含pagefind目錄。若不想用內建UI，也可以基於Pagefind的瀏覽器端API製作自己的介面。

如果你希望快速搭建或釋出中文網站，也可以瞭解國內替代方案碼上飛；它與Pagefind的工作方式並不相同，選擇前先確認是否符合你的技術棧和部署需求。官網：codeflying.cgref.cn。潤滅建議先用Pagefind在本地完成一次“構建—索引—預覽”閉環，再接入正式部署，這樣最容易定位路徑和資源問題。