# @farm\.js/preview-gateway 中文文档

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

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

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

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

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

- 包体积（解压后）：189 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-29T15:28:18.903Z
- 最新版本发布：2026-11-01T00:43:01.843Z
- 已发布版本数：160（近 12 个月 160 个）

## 中文简介

用于vercel托管的即时预览url的Farm.js预览网关

## 安装

```sh
npm install @farm.js/preview-gateway
```

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

## README

# @farm.js / preview-gateway

用于vercel托管的即时预览url的Farm.js预览网关

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

```bash
npm install @farm.js/preview-gateway
```

看到 [Farm.js库](https://github.com/farming-labs/farm.js) 获取文档、示例和支持。

缺省情况下，网关限制公共请求体和本地预览响应体的长度为5mib。使用 `maxBodyBytes` 和 `maxResponseBodyBytes` 在创建处理程序以设置下限或上限时。过大的本地响应在上传时被拒绝，等待的公共请求接收到 `502` 响应，而不是待挂起。

公共断开连接通过请求队列传播。轮询代理会中止匹配的localhost取回，而不是让被放弃的应用工作一直运行到超时。

`authorizeSession` 是一个可选的、配置时必需的访问钩子。它只接收 会话ID、名称、经过验证的所有者/项目/密钥/授权ID和过期令牌，而不是传输令牌。 返回 `true` 允许进入；拒绝返回403，异常返回通用的503。 网关检查注册、公共/控制请求、排队调度和等待响应。 不像 `observer`错误永远不会失败。将权限请求与超时绑定； Infra示例使用5秒。Session DELETE仍然可用于清理。 省略钩子保留了自托管行为。持久中继提供相同的功能 钩子，也每五秒检查一次空闲套接字，并从它的协调器调度。

托管部署可以配置 `auth` 使用GitHub OAuth客户端id和签名密钥。然后，网关公开CLI登录交换，发布范围为一个预览名和绝对到期的帐户绑定隧道授权，并在创建会话之前要求授权：

```ts
const githubClientId = process.env.FARM_PREVIEW_GITHUB_CLIENT_ID;
const signingSecret = process.env.FARM_PREVIEW_AUTH_SECRET;
if (!githubClientId || !signingSecret) {
  throw new Error("Farm Preview managed auth is not configured");
}

const handler = createPreviewGatewayHandler({
  auth: {
    githubClientId,
    signingSecret,
  },
});
```

将签名秘密仅保留在服务器上，并且长度至少为32字节。GitHub访问令牌仅用于在交换期间解析帐户身份，不包含在Farm凭据中。 受管理的公共网关也应该提供 `rateLimitExchange`． 钩子在请求体之前运行 读取或调用提供程序API，并接收被拒绝的请求 `429` 与 `Retry-After`． 使用一个 用于多实例部署的共享存储；托管的Vercel示例使用了一个原子Redis窗口。 如果该共享限制器不可用，则交换失败，并以可重试的方式关闭 `503` 反应和 不联系提供程序API。

预览名称绑定到其已验证的所有者。而一个帐户保存一个名字，和 `nameReservationMs` （默认为5分钟）在停止心跳或断开连接后，网关 拒绝其他帐户对该名称进行隧道授权或会话 `409`;同一个所有者可以 随时重新连接。通过实现可选的方法来跨实例存储绑定 `reserveName` 和 `getNameReservation` 存储方法（内存和Redis REST存储）。 当持久中继服务于同一域时，传递其 `isPreviewNameClaimed(name, ownerId)` 作为 网关的 `isPreviewNameClaimed` 选项，并将网关的处理程序方法发送给中继，因此两者都不是 传输接受另一方持有的名称。一张失败的支票拒绝认领 `503`.

托管授权和明确请求的持续时间是绝对过期。未经身份验证的会话 没有创建 `expiresInMs` 而不是使用 `sessionTtlMs` 作为闲置租约，只有在 当地的投票代理证明它仍然在线。

当前网关为轮询会话控件发布承载头身份验证。农场命令行 只有在确定了预验证兼容性网关后才使用查询字符串会话令牌。 这些遗留请求将会话凭据放在URL中，其中包含反向代理、cdn、平台 访问日志，URL工具可以记录它。Farm CLI和预览网关包则没有 日志控制url，但兼容性网关操作符必须编辑 `token` 查询参数 请求日志并限制对现有日志的访问。将网关升级为承载认证 保持会话凭据不受url控制。

## 常见问题

### @farm\.js/preview-gateway 是什么？

用于vercel托管的即时预览url的Farm\.js预览网关

### 如何安装 @farm\.js/preview-gateway？

在项目目录运行 npm install @farm\.js/preview-gateway，或使用 pnpm add / yarn add / bun add。

### @farm\.js/preview-gateway 支持 TypeScript 吗？

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

### @farm\.js/preview-gateway 支持 ESM 还是 CommonJS？

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

### @farm\.js/preview-gateway 可以商用吗？

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

### @farm\.js/preview-gateway 还在维护吗？

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