跳至主要内容

搜尋功能說明

⚠️ 重要限制​

@easyops-cn/docusaurus-search-local 插件在開發模式下無法使用搜尋功能

這是插件的技術限制，不是設定問題。

🔍 搜尋功能可用模式​

✅ 預覽模式（npm run serve）​

搜尋功能可以正常使用，但需要：

  1. 先執行建置：

    npm run build

  2. 再啟動預覽伺服器：

    npm run serve

  3. 或使用批次檔：

    開啟文件管理系統-預覽模式.bat

❌ 開發模式（npm start）​

搜尋功能無法使用，會顯示：

The search index is only available when you run docusaurus build!

🛠️ 解決 404 問題​

如果執行 npm run serve 出現 404，請檢查：

1. 確認建置成功​

npm run build

檢查：

  • 是否有錯誤訊息
  • build/ 資料夾是否存在
  • build/index.html 是否存在

2. 檢查建置輸出​

建置成功應該會顯示：

[SUCCESS] Generated static files in "build" directory.

3. 手動測試 serve​

# 先確認 build 資料夾存在
dir build

# 再執行 serve
npm run serve

4. 如果還是 404​

嘗試：

# 清除快取
npm run clear

# 重新建置
npm run build

# 啟動 serve
npm run serve

📝 工作流程建議​

日常編輯文檔​

npm start
  • ✅ 自動重新載入
  • ✅ 快速預覽
  • ❌ 搜尋功能無法使用

測試搜尋功能​

npm run build
npm run serve
  • ✅ 搜尋功能可用
  • ✅ 接近生產環境
  • ❌ 需要重新建置（較慢）

💡 建議​

  1. 開發時：使用 npm start 快速編輯和預覽
  2. 測試搜尋：定期使用 npm run build && npm run serve 測試
  3. 部署前：確保建置成功且搜尋功能正常

🔧 如果預覽模式還是 404​

請提供：

  1. 建置時的完整輸出（是否有錯誤）
  2. build/ 資料夾是否存在
  3. build/index.html 是否存在
  4. 執行 npm run serve 時的錯誤訊息