---

name: algolia-search description: Algolia 搜索实现、索引策略、React InstantSearch 和相关性调优的专家模式 risk: unknown source: vibeship-spawner-skills (Apache 2.0) date_added: 2026-02-27

Algolia 搜索集成

Algolia 搜索实现、索引策略、React InstantSearch 和相关性调优的专家模式

模式

使用 Hooks 的 React InstantSearch

使用 hooks 进行预输入搜索的现代 React InstantSearch 设置。

使用 react-instantsearch-hooks-web 包和 algoliasearch 客户端。 Widget 是可以用 classnames 自定义的组件。

关键 hooks：

• useSearchBox：搜索输入处理
• useHits：访问搜索结果
• useRefinementList：分面过滤
• usePagination：结果分页
• useInstantSearch：完整状态访问

代码示例

// lib/algolia.ts
import algoliasearch from 'algoliasearch/lite';

export const searchClient = algoliasearch(
  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
  process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY!  // Search-only key!
);

export const INDEX_NAME = 'products';

// components/Search.tsx
'use client';
import { InstantSearch, SearchBox, Hits, Configure } from 'react-instantsearch';
import { searchClient, INDEX_NAME } from '@/lib/algolia';

function Hit({ hit }: { hit: ProductHit }) {
  return (
    <article>
      <h3>{hit.name}</h3>
      <p>{hit.description}</p>
      <span>${hit.price}</span>
    </article>
  );
}

export function ProductSearch() {
  return (
    <InstantSearch searchClient={searchClient} indexName={INDEX_NAME}>
      <Configure hitsPerPage={20} />
      <SearchBox
        placeholder="Search products..."
        classNames={{
          root: 'relative',
          input: 'w-full px-4 py-2 border rounded',
        }}
      />
      <Hits hitComponent={Hit} />
    </InstantSearch>
  );
}

// Custom hook usage
import { useSearchBox, useHits, useInstantSearch } from 'react-instantsearch';

function CustomSearch() {
  const { query, refine } = useSearchBox();
  const { hits } = useHits<ProductHit>();
  const { status } = useInstantSearch();

  return (
    <div>
      <input
        value={query}
        onChange={(e) => refine(e.target.value)}
        placeholder="Search..."
      />
      {status === 'loading' && <p>Loading...</p>}
      <ul>
        {hits.map((hit) => (
          <li key={hit.objectID}>{hit.name}</li>
        ))}
      </ul>
    </div>
  );
}

反模式

• 模式：在前端代码中使用 Admin API 密钥 | 原因：Admin 密钥暴露完整索引控制包括删除 | 修复：使用带限制的仅搜索 API 密钥
• 模式：前端未使用 /lite 客户端 | 原因：完整客户端包含搜索不需要的代码 | 修复：从 algoliasearch/lite 导入以获得更小的包

Next.js 服务端渲染

使用 getServerState 进行 SSR 集成，确保首屏搜索结果在服务端渲染。

索引策略

// scripts/index-products.ts
import algoliasearch from 'algoliasearch';

const client = algoliasearch(APP_ID, ADMIN_KEY);
const index = client.initIndex('products');

// Configure searchable attributes and ranking
await index.setSettings({
  searchableAttributes: [
    'name',           // Most important
    'description',
    'category',
    'tags'
  ],
  attributesForFaceting: [
    'filterOnly(inStock)',
    'searchable(category)',
    'searchable(brand)',
    'price'
  ],
  customRanking: [
    'desc(popularity)',
    'desc(rating)'
  ],
  replicas: [
    'products_price_asc',
    'products_price_desc'
  ]
});

// Batch indexing
const records = products.map(p => ({
  objectID: p.id,
  name: p.name,
  description: p.description,
  price: p.price,
  category: p.category,
  inStock: p.stock > 0,
}));

await index.saveObjects(records);

相关性调优

• 使用 searchableAttributes 按重要性排序属性
• 使用 customRanking 添加业务指标
• 使用 replicas 支持不同排序方式
• 使用 synonyms 处理同义词
• 使用 rules 进行查询级别的自定义

限制

• 仅在任务明确匹配上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少所需的输入、权限、安全边界或成功标准，请停下来寻求澄清。