# @findlane/server 中文文档

规范地址：https://npmcn.com/package/%40findlane/server/

版本：0\.39\.0
npm 元数据更新时间：2026-11-08T15:29:56.000Z
中文译文更新时间：2026-11-14T18:39:47.815Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40findlane/server
原文对照：https://npmcn.com/package/%40findlane/server/?lang=original
项目主页：https://findlane.dev/docs/server-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：714 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-09-30T14:47:59.134Z
- 最新版本发布：2026-11-08T15:29:55.826Z
- 近 30 天下载量：5583（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

Findlane服务器 SDK:上传目录,管理索引设置,并使用密件工作空间API密钥进行搜索.

## 安装

```sh
npm install @findlane/server
```

也可以使用：`pnpm add @findlane/server`、`yarn add @findlane/server`、`bun add @findlane/server`

## README

# @ findlane/ 服务器

Findlane服务器SDK:上传并更新目录,管理索引设置,并进行搜索,带有密件工作空间API密钥. 它随处可见 `fetch` does: Node.js 18+, Bun, Deno, 以及边缘运行时间。 永远不要将其或密钥捆绑到浏览器代码; 使用 [`@findlane/browser`](https://www.npmjs.com/package/@findlane/browser) 在这里.

文档 : [https://findlane.dev/docs/server-sdk 页面存档备份,存于互联网档案馆](https://findlane.dev/docs/server-sdk)

## 安装

```sh
npm install @findlane/server
```

## 快开始

```ts
import { SearchServerClient } from "@findlane/server"

const client = new SearchServerClient({
  workspaceId: process.env.FINDLANE_WORKSPACE_ID!,
  apiKey: process.env.FINDLANE_API_KEY!,
})
const products = client.index("products")

await products.upsert([{ objectID: "sku-1", title: "Trail shoe", brand: { name: "Acme" }, price: 12900 }])
const results = await products.search({ q: "trail shoe", limit: 10 })
console.log(results.total, results.hits[0]?.record.title)
```

工作空间ID位于仪表板设置下,密钥位于API密钥下. 密钥有一个或两个范围:

-   `search`数字 : `search()`。 。 。 .
-   `write`:记录写作,设置,公开搜索限制,以及索引状态.

## 寻找访客

当你的服务器搜索某个人时,比如装入服务器的搜索页时,通过访问者. 索引的限制和机器人规则然后适用于它们,就像它们适用于浏览器搜索一样,从Googlebot等经核实的爬行者那里搜索是免费的:

```ts
const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent: req.get("user-agent") } })
```

`suggest()` 财务报告和审定财务报表 `recommendations()` 选择相同。 没有它,搜索算作你的服务器自己的.

## 索引的方法

`client.index<T>(name)` 返回这些; `T` 键入您需要字符串的记录 `objectID`。 。 。 .

| 方法 | 它会做什么 |
| --- | --- |
| `search(request, options?)` | 以查询、过滤、侧面、排序、呼呼和突出显示来搜索. `explain: true` 说为什么每次命中和命令一致 `appliedRules` 列出索引中的查询规则. `options` 带 `signal` 财务报告和审定财务报表 `visitor` (下关. |
| `querySuggestions({ q, limit? })`, (中文(简体) ), `popularSearches({ limit? })` | 作为访客的搜索, `[{ q, typed }]`,索引的流行搜索一个空框。 不计为搜索 . |
| `upsert(records)` | 增加或更新最多1 000个记录 `objectID`。 。 。 . |
| `replaceAll(records)` | 在一个请求中替换整个目录(最多10万个记录). |
| `replaceAllStaged(records, options)` | 在一个阶段 ID 中替换一个 批次较大的目录, 在一个阶段 中切换 。 重试中相同的 `stageId` 简历. `abortReplacement(stageId)` 丢出一个舞台. |
| `delete(objectID)` | 删除记录. |
| `getRecord(objectID)` | 记录及其版本. |
| `upsertOne(record, { expectedVersion })`, (中文(简体) ), `deleteOne(objectID, { expectedVersion })` | 只有记录还在时才写 `expectedVersion` (0对一个从未存在过的人来说);用一等分量键重审. |
| `getSettings()`, (中文(简体) ), `replaceSettings(settings)`, (中文(简体) ), `waitForSettings()` | 读取和更改可搜索字段,方块,过滤器,类型,自定义排序,同义词,语言,字典容忍度,和文本正常化. |
| `compareSettings(settings, { queries, searched }?)` | 比较索引本身的设置而不保存它们:它的搜索测试和大多数被搜索的查询,每个都同时搜索. 说哪项测试会失败,谁的结果会改变. |
| `getSearchTests()`, (中文(简体) ), `setSearchTests(tests)` | 搜索必须持续工作,除设置外保存,如前3或至少100个结果的记录. `compareSettings` 检查他们. |
| `getIndexingStatus()`, (中文(简体) ), `waitUntilIndexed(revision)` | 写入一个已接受的修改, 并在被接受时可以搜索, 所以 `waitUntilIndexed` 立即返回. |
| `getPublicSearchAccess()`, (中文(简体) ), `setPublicSearchPolicy(policy)`, (中文(简体) ), `usePublicIndexDefaults()` | 限制浏览器可能读取和查询的内容 . |
| `events.send(events, { visitorId, visitId, abTest }?)`, (中文(简体) ), `events.importOrders(orders)`, (中文(简体) ), `events.cancelOrder(orderID)` | 索引“事件”页面和“购买”的顺序和其他事件;关键需要 `events` 或者说 `write` 范围。 你自己的匿名访客身份证明 将一个蠢货的事件联系起来 当索引带走他们时. `abTest`从Shopper的搜索答案, 把它们放在他们的A/B测试组. |
| `abTests.get()`, (中文(简体) ), `abTests.estimate({ share })`, (中文(简体) ), `analytics.abTest()` | 该指数的A/B测试它的设置, 及其结果, 以及测试会是什么。 主人在仪表板上开始和结束它们. |
| `events.forget(ids)` | 在一周内删除与这些访客或访问身份证一起发送的事件. |
| `events.proxy(request)`, (中文(简体) ), `events.relay(body, visitor)` | 浏览器 SDK 事件的路径( 它) `eventsUrl`),是广告阻塞者让通过. 见 [活动](https://findlane.dev/docs/events#through-your-own-domain)。 。 。 . |
| `analytics.searches()`, (中文(简体) ), `.queries({ list, limit })`, (中文(简体) ), `.filters()`, (中文(简体) ), `.events()`, (中文(简体) ), `.products()`, (中文(简体) ), `.productCounts()`, (中文(简体) ), `.product(objectID)` | 索引是分析的,对于你自己的管理者:随时间推移而搜索,用点击来进行最高查询,没有结果或点击的查询,使用的过滤器,事件,以及每个产品的观点,加到目录和命令. 关键是 `analytics` 范围,并且只在服务器上工作。 见 [分析](https://findlane.dev/docs/api#analytics)。 。 。 . |
| `writes.get({ range })`, (中文(简体) ), `writes.log({ problems, before, limit })` | 索引中的内容:当数据最后到达和最后改变任何东西时,按来源分列,写作拒绝的理由。 关键是 `analytics` 范围,并且只在服务器上工作。 见 [更新](https://findlane.dev/docs/api#updates)。 。 。 . |

### 设置

`replaceSettings` 发送完整的设置; 首先获取以保留其他字段。 内容 `applied` 说变化是如何产生的:

-   `instant`:查询时间设置,并删除或重排可搜索字段.
-   `fields`:平面,过滤器,排序,和排序字段,已填入.
-   `searchable`: 新建可搜索字段,填入.
-   `rebuild`:文本正常化;索引重建.

一个大 `searchable` 或者说 `rebuild` 背景变化仍在继续,其进展包括: `rebuild` (也由 `getSettings`) (中文(简体) ). 搜索使用以前的设置直到完成,以及 `waitForSettings()` 等待着.

在保存更改规则,同义词, 字形容忍,或排名之前, `compareSettings` 显示它的作用,和 `{}` 以当前设置运行搜索测试 :

```ts
const comparison = await products.compareSettings({ rules: nextRules })
const failing = comparison.tests.filter((test) => test.before && !test.after)
if (!failing.length) await products.replaceSettings({ ...(await products.getSettings()), rules: nextRules })
```

### 浏览器搜索

仅当浏览器搜索被启用时, 您打算公开的上传字段 . `getPublicSearchAccess()` 显示当前模式. `setPublicSearchPolicy({ returnFields, searchFields, filterFields, facetFields, sortIds, defaultSort })` 限制 API 的索引,并且 `usePublicIndexDefaults()` 取消限制。 只有工作空间所有者才能更改允许浏览器的出处,在仪表板中.

### 已签名密钥

对于已登录的人的浏览器搜索,从仪表板的API密钥页面中用签名密钥在短命密钥上签名. 它不提出要求,它的限制取代了索引的公开设置:

```ts
import { signSearchKey } from "@findlane/server"

const signedKey = await signSearchKey(process.env.FINDLANE_SIGNING_KEY!, {
  validUntil: new Date(Date.now() + 60 * 60 * 1000),
  indexes: ["products"],
  filters: { customerGroup: user.group },
  userToken: user.id,
})
```

浏览器 SDK 将其视为 `signedKey`。见 [登录访问者](https://findlane.dev/docs/security#logged-in-visitors)。 。 。 .

## 错误

请求抛出失败 `FindlaneError` 与 HTTP 连接 `status` 和API的信息。 402指计划限制,如记录或每月搜索. `replaceAllStaged` 丢出一个 `StagedReplacementError` 与 `stageId` 重试。 每一种方法都有选择 `AbortSignal`。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @findlane/server 是什么？

Findlane服务器 SDK:上传目录,管理索引设置,并使用密件工作空间API密钥进行搜索\.

### 如何安装 @findlane/server？

在项目目录运行 npm install @findlane/server，或使用 pnpm add / yarn add / bun add。

### @findlane/server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @findlane/server 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @findlane/server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @findlane/server 可以商用吗？

@findlane/server 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @findlane/server 的下载量有多少？

根据 npm 官方下载统计，@findlane/server 在 2026/10/15 – 2026/11/13 这 30 天内被下载 5,583 次，日均约 186 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @findlane/server 还在维护吗？

最新版本 0\.39\.0 发布于 2026/11/08（6 天前）；至今共发布 41 个版本，其中过去 12 个月发布了 41 个；首次发布于 2026/09/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。