# @farm\.js/sanity 中文文档

规范地址：https://npmcn.com/package/%40farm.js/sanity/

版本：0\.1\.48
npm 元数据更新时间：2026-11-01T00:46:01.109Z
中文译文更新时间：2026-11-01T03:25:36.982Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40farm.js/sanity
原文对照：https://npmcn.com/package/%40farm.js/sanity/?lang=original
项目主页：https://github.com/farming-labs/farm.js#readme
源码仓库：https://github.com/farming-labs/farm.js

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

- 包体积（解压后）：37.1 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：@sanity/client ^7\.0\.0 \|\| ^8\.0\.0，@farm\.js/content ^0\.1\.0-beta\.46
- 首次发布：2026-09-24T20:53:31.368Z
- 最新版本发布：2026-11-01T00:46:00.895Z
- 已发布版本数：61（近 12 个月 61 个）

## 中文简介

为Farm.js集成的Sanity CMS

## 安装

```sh
npm install @farm.js/sanity
```

也可以使用：`pnpm add @farm.js/sanity`、`yarn add @farm.js/sanity`、`bun add @farm.js/sanity`

## README

# @farm.js /理智

用于Farm.js应用的Sanity CMS集成。它解析了Sanity客户端配置， 在启动时验证它，并接收Sanity webhooks，因此缓存的内容立即无效 编辑出版。

看到 [稳定性和支持](https://farmjs.dev/docs/stability) 因为这个包裹保证了什么。

## 安装

```bash
pnpm add @farm.js/sanity @sanity/client
```

`@sanity/client` 是对等依赖，因此应用程序和集成共享一个客户端。

## 配置

```ts
import { defineConfig } from "@farm.js/core";
import { sanity } from "@farm.js/sanity";

export default defineConfig({
  integrations: {
    cms: sanity(),
  },
});
```

在没有选项的情况下，值来自环境：

| 变量 | 目的 |
| --- | --- |
| `SANITY_PROJECT_ID` | 项目id。 `SANITY_STUDIO_PROJECT_ID` 也是读的。 |
| `SANITY_DATASET` | 数据集。 `SANITY_STUDIO_DATASET` 也是读的。 |
| `SANITY_API_VERSION` | 可选的。 `SANITY_STUDIO_API_VERSION` 也是读的。默认为固定日期。 |
| `SANITY_API_READ_TOKEN` | 可选的。查看器令牌，用于私有数据集和草稿。 |
| `SANITY_WEBHOOK_SECRET` | 一旦配置了webhook就需要。 |

缺少项目id或数据集在启动时失败，而不是在第一次请求时失败。

请注意，需要令牌的数据集向未经身份验证的查询返回空结果。 没有错误。如果缺少内容，则在执行其他操作之前先检查令牌。

## 阅读内容

应用程序拥有客户端。构建它一次，直接使用它，并将相同的对象交给 集成，因此Farm不构建第二个。

```ts
// src/lib/cms.server.ts
import { createSanityClient, resolveSanityConfig } from "@farm.js/sanity";

export const cms = createSanityClient(resolveSanityConfig({ useCdn: false }));
```

```ts
// farm.config.ts
integrations: {
  cms: sanity({ instance: cms }),
}
```

将查询封装在 `createServerQuery` 因此，结果被缓存，并可以通过键使其无效。

```ts
import { createServerQuery } from "@farm.js/core";
import { cms } from "./cms.server";

export const postsQuery = createServerQuery({
  key: () => ["sanity", "post", "list"],
  staleTime: "5m",
  handler: () =>
    cms.fetch(`*[_type == "post"] | order(publishedAt desc) { title, "slug": slug.current }`),
});
```

## 发布时无效

当文档更改时，Sanity可以调用应用程序。集成验证请求 来自Sanity，然后询问应用程序更改影响了哪些缓存条目。

```ts
sanity({
  instance: cms,
  webhook: {
    onChange(payload) {
      if (payload._type !== "post") return;
      const slug = payload.slug as string;
      return {
        keys: [
          ["sanity", "post", "list"],
          ["sanity", "post", slug],
        ],
        paths: ["/posts", `/posts/${slug}`],
      };
    },
  },
});
```

`keys` 是服务器查询键。 `paths` 路由路径的渲染输出应该是 也被重新验证了。对于不影响缓存内容的更改，不返回任何内容。

在Sanity中，创建一个webhook **API > Webhooks**：

-   URL: `https://your-app.example/api/sanity/webhook`
-   触发创建、更新和删除
-   投影: `{ _id, _type, "slug": slug.current }`
-   的值 `SANITY_WEBHOOK_SECRET`

传递给 `onChange` 投影返回的是什么，所以包含字段是 映射的需要。例如，其他人引用的文档可以列出它们 `"slugs": *[_type == "post" && references(^._id)].slug.current`.

回复遵循Sanity接下来的做法： `401` 一个糟糕的签名 `400` 为了一个畸形的身体 不重试，和 `500` 从失败中 `onChange` 重试。

### 通读API，而不是CDN

集 `useCdn: false` 当webhook驱动无效时，在客户端上。webhook之前触发 Sanity的CDN已经更新，因此通过CDN重新获取可以返回以前的内容和缓存 它又为满了 `staleTime`． Farm的缓存是这个设置中的缓存；第二个在前面 它只增加了种族。

为依赖的应用程序保留CDN `staleTime` 单独使用，或用于浏览器端读取。

### 多个服务器实例

Farm的数据缓存保存在每个进程的内存中，除非配置了分布式适配器。在一个 无服务器平台，webhook到达一个实例，只清除该实例的内存。使用 一个适配器，例如 `@farm.js/cache-redis` 因此，无效会到达每个实例。

## 选项

| 选项 | 默认的 | 笔记 |
| --- | --- | --- |
| `projectId` | env |  |
| `dataset` | env |  |
| `apiVersion` | 固定的日期 | 导出为 `DEFAULT_SANITY_API_VERSION`. |
| `token` | env | 服务器只。从未传递给浏览器。 |
| `useCdn` | `true` | 集 `false` 与webhook无效。 |
| `instance` |  | 现有的 `SanityClient`． 跳过凭证验证。 |
| `webhook.secret` | env |  |
| `webhook.path` | `/api/sanity/webhook` |  |
| `webhook.onChange` |  | 将有效负载映射到 `{ keys?, paths? }`. |
| `log` |  | 集成生命周期日志记录器。 |

## 带上自己的客户

通过已配置的客户端 `instance` 对于集成不公开的选项。这个 Integration按原样使用该对象。

```ts
import { createClient } from "@sanity/client";

sanity({ instance: createClient({ projectId, dataset, apiVersion, perspective: "published" }) });
```

## 常见问题

### @farm\.js/sanity 是什么？

为Farm\.js集成的Sanity CMS

### 如何安装 @farm\.js/sanity？

在项目目录运行 npm install @farm\.js/sanity，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@sanity/client（^7\.0\.0 \|\| ^8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @farm\.js/sanity 支持 TypeScript 吗？

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

### @farm\.js/sanity 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @farm\.js/sanity 可以商用吗？

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

### @farm\.js/sanity 还在维护吗？

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