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

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

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

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

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

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

- 包体积（解压后）：31.2 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@strapi/client ^1\.6\.2
- 首次发布：2026-10-04T20:16:29.755Z
- 最新版本发布：2026-11-01T00:44:55.848Z
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

为Farm.js集成Strapi CMS

## 安装

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

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

## README

# @farm.js / strapi

用于Farm.js应用的Strapi 5 CMS集成。它配置了官方的Strapi客户端， 展开类型化的集合读取，从生成的上传变量构建响应式图像道具，以及 接收经过身份验证的webhook，以便在编辑器发布后刷新缓存的内容。

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

## 安装

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

`@strapi/client` 是对等依赖项，因此应用程序和集成使用一个客户端版本。

## 配置

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

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

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

| 变量 | 目的 |
| --- | --- |
| `STRAPI_API_URL` | 内容API基础URL，包括 `/api`. |
| `STRAPI_MEDIA_URL` | 可选的公共媒体来源。默认为API URL的源。 |
| `STRAPI_API_TOKEN` | 用于非公共内容的可选服务器专用API令牌。 |
| `STRAPI_WEBHOOK_SECRET` | 一旦配置了webhook无效，就需要。 |

当配置加载时，而不是在第一个内容请求时，缺少API URL失败。

## 阅读内容

构建一次客户机，然后在集成和应用程序服务器代码中重用它。

```ts
// src/lib/cms.server.ts
import {
  createStrapiClient,
  createStrapiCollection,
  resolveStrapiConfig,
  type StrapiDocument,
} from "@farm.js/strapi";

interface Article extends StrapiDocument {
  title: string;
  slug: string;
}

export const cms = createStrapiClient(resolveStrapiConfig({}));
export const articles = createStrapiCollection<Article>(cms, "articles");
```

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

将集合读入 `createServerQuery` 来验证和缓存结果。助手接受了 官方客户的 `populate`， `fields`， `filters`， `sort`， `pagination`， `locale`, `status` 查询选项并展开REST `data` 信封。

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

export const postsQuery = createServerQuery({
  key: () => ["strapi", "articles"],
  staleTime: "5m",
  handler: () =>
    articles.find({
      fields: ["title", "slug"],
      populate: ["cover"],
      sort: ["publishedAt:desc"],
      status: "published",
    }),
});
```

泛型描述应用程序期望的字段。在服务器上保持运行时验证 因为Strapi返回的字段仍然依赖于权限和 `populate`.

## 发布时无效

Strapi可以给每个webhook发送一个固定的头。Farm在解析之前验证共享密钥 并询问应用程序该事件影响哪些缓存条目。

```ts
strapi({
  instance: cms,
  webhook: {
    onChange(payload) {
      if (payload.model !== "article") return;
      const entry = payload.entry as { documentId?: string; slug?: string };
      return {
        keys: [
          ["strapi", "articles"],
          ...(entry.documentId ? [["strapi", "article", entry.documentId] as const] : []),
        ],
        paths: ["/articles", ...(entry.slug ? [`/articles/${entry.slug}`] : [])],
      };
    },
  },
});
```

在Strapi中，创建一个webhook **设置> Webhooks**：

-   URL: `https://your-app.example/api/strapi/webhook`
-   事件：映射处理的条目和媒体事件
-   标题名称: `x-farm-webhook-secret`
-   头值：显示的值 `STRAPI_WEBHOOK_SECRET`

两者都可以改变 `webhook.path` 和 `webhook.secretHeader`． Strapi不签名或重试webhook 交付，所以使用 `staleTime` 作为新鲜度的退步，而不是仅仅依靠webhook。

## 提供图片

`getStrapiImageProps` 选择最小的生成变量，至少与请求的宽度相同 构建一个 `srcset` 从那个线人的真实变种中。它从不创建转换URL。

```tsx
import { getStrapiImageProps, type StrapiMediaAsset } from "@farm.js/strapi";

export function Cover({ asset }: { asset: StrapiMediaAsset }) {
  return (
    <img
      {...getStrapiImageProps(asset, {
        mediaUrl: process.env.STRAPI_MEDIA_URL ?? process.env.STRAPI_API_URL,
        width: 800,
        sizes: "100vw",
      })}
    />
  );
}
```

绝对的上传提供者url被保留。相对url被解析 `mediaUrl`,这 可以与Content API主机不同。

## 生产笔记

-   保持 `STRAPI_API_TOKEN` 而官方客户端仅在服务器模块中。不要从 浏览器输入。
-   Farm的默认数据缓存位于每个进程的内存中。配置分布式缓存适配器 Webhook必须使每个服务器实例失效。
-   Strapi 5的草案状态需要一个可以读取内容类型的API令牌。不要打草稿 选择依赖于不可信的查询参数；将其置于应用程序拥有的预览授权之后。

## 选项

| 选项 | 默认的 | 笔记 |
| --- | --- | --- |
| `apiUrl` | `STRAPI_API_URL` | 内容API基础URL，包括 `/api`. |
| `mediaUrl` | API的起源 | 相对上传url的公共来源。 |
| `token` | `STRAPI_API_TOKEN` | 服务器只。 |
| `instance` |  | 现有的 `StrapiClient`;跳过API URL验证。 |
| `webhook.secret` | `STRAPI_WEBHOOK_SECRET` |  |
| `webhook.path` | `/api/strapi/webhook` |  |
| `webhook.secretHeader` | `x-farm-webhook-secret` | 在Strapi中配置相同的自定义头。 |
| `webhook.onChange` |  | 将有效负载映射到 `{ keys?, paths? }`. |
| `log` |  | 集成生命周期日志记录器。 |

## 常见问题

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

为Farm\.js集成Strapi CMS

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

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

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

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

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

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

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

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

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

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