Algolia 搜尋

設定複製錨點連結

安裝相依套件：

npm install algoliasearch

註冊 Algolia複製錨點連結

請註冊帳號並取得搜尋用的應用程式 ID 與 API 金鑰，然後將它們存放在 .env.local 中 (在 Vite 框架中，NEXT_PUBLIC_ 應改為 VITE_；在 Astro 中則改為 PUBLIC_) ：

NEXT_PUBLIC_ALGOLIA_APP_ID="app ID"
NEXT_PUBLIC_ALGOLIA_SEARCH_KEY="search-only API key"
ALGOLIA_WRITE_KEY="write API key"

同步搜尋索引複製錨點連結

預先算繪 static.json 路由，在建置時匯出搜尋索引，並於每次建置後透過指令碼將索引同步至 Algolia：

import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/algolia';

export const revalidate = false;

export async function GET() {
  return Response.json(await toDocuments(source));
}

import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/algolia';
import { algoliasearch } from 'algoliasearch';

// Next.js writes it under `route-cache` when built with an adapter, like on Vercel
const [file] = await Array.fromAsync(fs.glob('.next/server/{app,route-cache/*/*/$}/static.json.body'));
const records = JSON.parse(await fs.readFile(file, 'utf-8')) as DocumentRecord[];

const client = algoliasearch(
  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
  process.env.ALGOLIA_WRITE_KEY!,
);

await sync(client, {
  indexName: 'document',
  documents: records,
});

console.log(`search updated: ${records.length} records`);

{
  "scripts": {
    "build": "next build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
  }
}

sync() 會更新索引設定並取代所有紀錄。build 指令碼會在每次建置時執行同步，因此請在您的部署平台上設定相同的變數。

搜尋 UI複製錨點連結

您可以考慮以下幾種實作 UI 的方式：

• 使用 Fumadocs UI 搜尋對話方塊。

• 透過內建的搜尋用戶端 hook 自行建構：

  複製文字

  import { liteClient } from 'algoliasearch/lite';
  import { useAlgoliaSearch } from 'fumadocs-core/search/client';
  
  const algolia = liteClient('id', 'key');
  
  const { search, onSearchChange, isLoading, data } = useAlgoliaSearch({
    indexName: 'document',
    client: algolia,
  });

• 直接使用 Algolia 的官方用戶端。

進階複製錨點連結

標籤篩選複製錨點連結

若要設定標籤篩選，請在 static.json 路由中將 tag 傳入 toDocuments()：

toDocuments(source, { tag: (page) => page.slugs[0] });

接著更新您的搜尋用戶端：

• Fumadocs UI：在搜尋 UI 中啟用標籤篩選。

• 搜尋用戶端：您可以用以下方式加入標籤篩選：

  複製文字

  import { useAlgoliaSearch } from 'fumadocs-core/search/client';
  
  const { search, onSearchChange, isLoading, data } = useAlgoliaSearch({
    tag: '<your tag value>',
    // ...
  });

tag 欄位是用於分面搜尋 (faceting) 的屬性。您也可以在 Algolia 搜尋用戶端中使用 tag:value 篩選條件。

底層運作原理複製錨點連結

Algolia 整合會自動設定 Algolia Search，用於文件搜尋。

它會為文件中的每個段落各建立一筆紀錄，這也是 Algolia 建議的做法。

每筆紀錄都包含以下可搜尋的屬性：

只有位於標題下方的段落才會有 section 欄位。標題與 段落會分別索引為獨立的紀錄，並依頁面 ID 分組。

請注意，頁面的 url 屬性必須是唯一的，請勿讓兩個頁面使用相同的 URL。