搜索插件

https://www.npmjs.com/package/@payloadcms/plugin-search

该插件会为你的文档生成极速搜索记录。它通过创建一个新的 search 集合（该集合在数据库中被索引），然后仅保存每个文档的关键搜索数据的静态副本来实现。当你管理应用程序文档时，搜索记录会在后台自动创建、同步和删除。

例如，如果你有一个非常庞大且复杂的 posts 集合，该插件可以让你仅同步每篇文章的标题、摘要和 slug，这样你就可以直接查询这些数据，而不是查询原始文章。搜索记录是静态的，因此查询它们还有一个显著优势：可以绕过原始文档上可能存在的任何钩子。你可以精确定义要同步的数据，甚至可以在保存前基于每个文档修改或回退这些数据。

要查询搜索结果，可以使用你已经熟悉的所有现有 Payload API。你还可以通过为每个集合设置自定义优先级来优化搜索结果。例如，你可能希望博客文章排在页面之前，或者希望某篇特定文章始终显示在最前面。搜索记录有一个 priority 字段，可以作为查询中的 ?sort= 参数使用。

该插件是实现快速沉浸式搜索体验（如前端应用中的搜索栏）的理想选择。许多应用可能不需要像 Algolia 或 ElasticSearch 这样的第三方服务的强大功能和复杂性。该插件提供了一个易于设置且完全运行在你自己的数据库上的第一方替代方案。

该插件完全开源，源代码可以在此找到。 如需帮助，请查看我们的社区帮助。如果发现 bug， 请提交新 issue， 并尽可能提供详细信息。

核心功能

  • 自动在数据库中创建带索引的 search 集合
  • 在管理文档时自动创建、同步和删除搜索记录
  • 仅保存你定义的搜索关键数据（如标题、摘要等）
  • 允许使用 Payload 原生 API 查询搜索结果
  • 允许查询文档而不触发其底层钩子
  • 允许按集合或文档轻松设置搜索结果优先级
  • 允许按需重新索引指定集合的搜索结果

安装

使用 pnpm、npm 或 Yarn 等 JavaScript 包管理器安装插件：

  pnpm add @payloadcms/plugin-search

基础用法

在 Payload 配置 的 plugins 数组中，调用插件并传入 选项：

import { buildConfig } from 'payload'
import { searchPlugin } from '@payloadcms/plugin-search'

const config = buildConfig({
  collections: [
    {
      slug: 'pages',
      fields: [],
    },
    {
      slug: 'posts',
      fields: [],
    },
  ],
  plugins: [
    searchPlugin({
      collections: ['pages', 'posts'],
      defaultPriorities: {
        pages: 10,
        posts: 20,
      },
    }),
  ],
})

export default config

选项

collections

collections 属性是一个数组，包含需要启用搜索同步的集合 slug。启用的集合会获得 beforeChange 和 afterDelete 钩子，这些钩子会在文档变更时创建、更新和删除对应的搜索记录。

localize

默认情况下，如果你启用了本地化功能，搜索插件会在新添加的 search 集合的 title 字段上设置 localization: true。如果你想禁用此行为，可以将其设置为 false。

defaultPriorities

该插件会自动向 search collection 添加一个 priority 字段，可用作查询中的 ?sort= 参数。例如，你可能希望博客文章排在页面之前，或者希望某篇特定文章始终显示在最前面。

defaultPriorities 属性用于在 create 操作期间为搜索记录设置回退优先级。它接受一个对象，其键是你的 collection slugs，值可以是数字或返回数字的函数。该函数接收正在创建的文档 doc 作为参数。

// payload.config.ts
{
  // ...
  searchPlugin({
    defaultPriorities: {
      pages: ({ doc }) => (doc.title.startsWith('Hello, world!') ? 1 : 10),
      posts: 20,
    },
  }),
}

searchOverrides

该插件会自动创建 search collection，但你可以通过 searchOverrides 属性覆盖该 collection 的任何配置。它接受 Payload Collection Config 中的任何配置，并将其与插件提供的默认 search collection 配置合并。

注意 fields 属性是一个函数，它接收一个包含 defaultFields 键的对象。defaultFields 是自动添加到 search collection 的字段数组。你可以修改这个数组或向其添加新字段。

// payload.config.ts
{
  // ...
  searchPlugin({
    searchOverrides: {
      slug: 'search-results',
      fields: ({ defaultFields }) => [
        ...defaultFields,
        {
          name: 'excerpt',
          type: 'textarea',
          admin: {
            position: 'sidebar',
          },
        },
      ],
    },
  }),
}

beforeSync

在创建或更新搜索记录之前，会执行 beforeSync 函数。这是一个 afterChange 钩子，允许你在搜索记录创建或更新前修改数据或提供回退值。

// payload.config.ts
{
  // ...
  searchPlugin({
    beforeSync: ({ originalDoc, searchDoc }) => ({
      ...searchDoc,
      // - 在此处以任何方式修改你的文档，可以是异步操作
      // - 你还需要在 `searchOverrides` 配置中添加 `excerpt` 字段
      excerpt: originalDoc?.excerpt || '这是回退摘要',
    }),
  }),
}

syncDrafts

当 syncDrafts 设为 true 时，草稿文档也会被同步到搜索索引中。默认值为 false。此功能需要启用 Payload Drafts 才能生效。

deleteDrafts

如果设为 true，当文档状态变为草稿时，会从搜索索引中删除该文档。默认值为 true。此功能需要启用 Payload Drafts 才能生效。

reindexBatchSize

指定一个数字，用于确定每次批量重新索引时获取的搜索文档数量。如果未设置，默认值为 50。

集合重新索引

集合重新索引功能允许你按需从已启用搜索的集合中重新创建搜索文档。这在已有文档没有搜索索引时特别有用，常见于在现有项目中添加 plugin-search 的情况。要使用此功能，请导航至你的搜索集合，在列表视图右上角操作栏中点击标有 Reindex 的按钮。这将打开一个弹窗，提供选项让你选择要重新索引的一个或所有已启用搜索的集合。

TypeScript

所有类型都可以直接导入：

import type { SearchConfig, BeforeSync } from '@payloadcms/plugin-search/types'