# @fjall/payload 中文文档

规范地址：https://npmcn.com/package/%40fjall/payload/

版本：39\.2\.2
npm 元数据更新时间：2026-11-15T12:13:20.113Z
中文译文更新时间：2026-11-14T20:56:55.844Z
软件包许可：SEE LICENSE IN LICENSE

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

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

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

- 包体积（解压后）：36.3 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.3\.0
- 运行依赖：1 个
- peer 依赖：payload ^3\.0\.0，@aws-sdk/client-s3 ^3\.0\.0，@payloadcms/storage-s3 ^3\.0\.0，@payloadcms/db-postgres ^3\.0\.0
- 首次发布：2026-02-02T06:51:37.931Z
- 最新版本发布：2026-11-15T12:13:19.929Z
- 近 30 天下载量：2933（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：179（近 12 个月 179 个）

## 中文简介

Fjall AWS适配器和有效载荷CMS的公用事业

## 安装

```sh
npm install @fjall/payload
```

也可以使用：`pnpm add @fjall/payload`、`yarn add @fjall/payload`、`bun add @fjall/payload`

## README

# @ fjall/ 负载

AWS Lambda 适配器,用于有效载荷CMS. 这个软件包为Bayload的数据库和存储适配器提供倒置替换,优化后用于AWS上的无服务器部署.

## 安装

```bash
npm install @fjall/payload @payloadcms/storage-s3
```

## 特征

-   **`fjallPostgresAdapter`** - 装有 AWS 保密管理器集成的 PostgreSQL 适配器
-   **`awsS3Storage`** - S3 媒体上传存储插件
-   **`fjallDefaults`** - Lambda的感知性CORS/CSRF默认值
-   **`isProduction`** 编号 : **`isLambda`** - 环境检测助手

## 使用量

### 数据库适配器

```typescript
// payload.config.ts
import { buildConfig } from "payload";
import { fjallPostgresAdapter, fjallDefaults } from "@fjall/payload";
import { migrations } from "./migrations";

export default buildConfig({
  ...fjallDefaults(),
  db: await fjallPostgresAdapter({
    migrationDir: "./src/migrations",
    prodMigrations: migrations,
  }),
  // ... rest of config
});
```

适配器自动:

-   从 Lambda 的 AWS 保密管理器获取数据库证书
-   倒计时 `DATABASE_URL` 地方发展
-   为 Aurora PostgreSQL 配置 SSL
-   使得Habload的迁移相互等待, 所以环境开始一起运行 每一个迁移一次。 每次运行都会在迁移时在自己的连接上挂起Postgres咨询锁(1718250604, 1),而等待15分钟的运行会因错误而失败,从而命名了锁

### S3 存储插件

```typescript
// plugins/index.ts
import { awsS3Storage } from "@fjall/payload";
import { Plugin } from "payload";

export const plugins: Plugin[] = [awsS3Storage()];
```

自动插件 :

-   用途 `MEDIA_BUCKET_NAME` fjall基础设施设置的环境变量
-   处理上传的预先签名的 URL
-   返回本地文件系统进行开发

### 环境检测

```typescript
import { isProduction, isLambda } from "@fjall/payload";

// Conditional logic based on environment
if (isProduction()) {
  // Running in AWS with Fjall infrastructure
}

if (isLambda()) {
  // Running in AWS Lambda runtime
}
```

### 有条件的静态目录

对于需要本地上传到 dev 但制作中S3的媒体收藏:

```typescript
import { isProduction } from "@fjall/payload";
import path from "path";

export const Media: CollectionConfig = {
  slug: "media",
  upload: {
    ...(isProduction()
      ? {}
      : {
          staticDir: path.resolve(__dirname, "../../public/media"),
        }),
  },
};
```

## 环境变量

### 生产(兰布达)

由 Fjall 基础设施自动设定 :

| 变量 | 说明 |
| --- | --- |
| `DATABASE_HOST` | 奥罗拉 PostgreSQL 终点 |
| `DATABASE_PORT` | 数据库端口( 默认: 5432) |
| `DATABASE_NAME` | 数据库名称 |
| `DATABASE_SSL` | 启用 SSL ()`true`(中文(简体) ) |
| `MEDIA_BUCKET_NAME` | S3 上传桶 |

从保密管理器获取的证书 :

-   `DATABASE_USERNAME`
-   `DATABASE_PASSWORD`

### 发展

| 变量 | 说明 |
| --- | --- |
| `DATABASE_URL` | 完整的 PostgreSQL 连接字符串 |

## 设立和部署有效载荷项目

也没有 `fjall create app` 也没有 `fjall deploy` 为Lambda设置有效载荷项目. `fjall create app --name <app> --pattern payload --non-interactive` 写入 `fjall/<app>/infrastructure.ts`, (中文(简体) ), `fjall/<app>/open-next.config.ts`,旁边的 CDK 项目文件和应用程序的配置文件, 没有任何东西可以改变您的项目自己的文件 。 在没有 `--non-interactive`, (中文(简体) ), `fjall create app` 打开应用程序向导,该向导忽略 `--pattern`: 运行 `fjall create` 选择 **模式** 换句话说 一次手动配置项目,再在项目根部进行构建,并部署所生成的东西. 整个食谱在 [有效载荷图案页](https://docs.fjall.io/patterns/payload-pattern#configure-the-project)。 。 。 .

**在Lambda,一个部署在这条路的场地需要fjall 39.0.13或后期建造.** 有效载荷模式赋予其服务器功能数据库用户名和密码,以及 `PAYLOAD_SECRET`,通过Fjall的秘密支持,并通过fjall 39.0.12的支持不能提供. 从代码读取,从39.0.8到39.0.12,功能的每个起步都会在其处理器运行前在Fjall的秘密解析器中停止,在39.0.8之前,一个起步可以跳过解析器,开始时没有秘密. 原因是AWS的参数和秘诀Lambda扩展的版本fjall 39.x pins, 1.0.103:在2026年10月15日于我们-东-2的arm64上测出,它以一个功能启动的前8秒以未准备好的拒绝来回答每个40个读取,从代码中读取,解答者将该拒绝视为最终拒绝. 从39.0.13起,解析器读取系统管理器和秘密管理器本身,从而不再停止一个功能可通达两个服务的有效载荷站点,以及 `fjallPostgresAdapter` 取已移交的解析器的值。 有效载荷站点尚未结束.

### 配置项目

在工程根工作, 保存的目录 `package.json` 编辑 `fjall/` 文件夹。 下面的命令使用 npm.

1.  安装此软件包和 S3 存储适配器 : `npm install @fjall/payload @payloadcms/storage-s3`。 。 。 .
2.  单位 `payload.config.ts`,使用时 `fjallPostgresAdapter` 与 `prodMigrations`扩展 `fjallDefaults()` 输入 `buildConfig`,作为 [数据库适配器](https://npmcn.com/package/%40fjall/payload/#readme-database-adapter) 显示。 在第一个迁移存在之前,创建 `src/migrations/index.ts` 持有 `export const migrations = [];` 因此,导入解析度,然后生成第一个迁移 `npx payload migrate:create` 在第一个建筑之前.
3.  添加 `awsS3Storage()` 到工程的插件,并保留 `staticDir` 媒体收藏中未制作的 [S3 存储插件](https://npmcn.com/package/%40fjall/payload/#readme-s3-storage-plugin) 财务报告和审定财务报表 [有条件的静态目录](https://npmcn.com/package/%40fjall/payload/#readme-conditional-static-directory) 显示.
4.  守护运行期间的每一个数据库查询 `next build`,正如有效载荷模式页面显示的网站模板页面:a `generateStaticParams` 返回时 `[]` 何时 `isBuildTime()` 真实, 以及查询导出时的页面 `dynamic = "force-dynamic"`。 。 。 .
5.  在为 AWS 构建前请注释 `DATABASE_URL` 财务报告和审定财务报表 `NEXT_PUBLIC_SERVER_URL` 地点 `.env` 或者说 `.env.production` 摆放它们,在哪里 `.env.local` 或者说 `.env.production.local` 是的,建筑读取。 下册.j 副本 `.env` 财务报告和审定财务报表 `.env.production` 输入其独立的输出和 OpenNext 复制到服务器函数(Next.js 16.3.8 和 `@opennextjs/aws` 4.1.6, 读取),所以其中的每一个价值都与所部署的地点相符合.
6.  请检查access-date=中的日期值 (帮助) `npm ls next`,然后寻找一个 `buildCommand` 输入 `config` 目标 `fjall/<app>/open-next.config.ts`:fjall 39.x 写出没有文件,后来的 CLIs 写出 `buildCommand: "npm run build -- --webpack"`。在下.js 16 上,配置需要该行,如果缺少该行,则添加该行: Next.js 16 默认使用涡轮包装来建起,而涡轮包装建筑则指由散列名称所形成的尖锐而不能在Lambda上解决,因此每个路由回答500个(vercel/next.js issue 87737,于2026-09-28日开放;用 Next.js 16.3.3 与下 `@opennextjs/aws` 4.1.0. (中文(简体) ). 在下行.js 15上,删除该行,如果有的话, OpenNext 运行 `npm run build`: 下一个.js 15 已经用网络包构建并拒绝 `--webpack` 作为未知的选项(Next.js 15.4.11,已读).

### 建设和部署

`fjall deploy` 运行其建设步骤 `fjall/<app>`,它失败的应用程序 被设定为 `fjall create app` 摆出它。 项目根数 :

1.  安装 OpenNext 构建器 : `npm install --save-dev @opennextjs/aws@^4.1.6`。不要通过 `npx open-next`: 未安装构建器, npx 获取 `open-next` 3.1.3 取而代之的是来自登记册,超出这一范围.
    
2.  将导入地图写入项目自己的有效载荷 CLI : `./node_modules/.bin/payload generate:importmap`。 。 。 .
    
3.  构建 : `./node_modules/.bin/open-next build --config-path fjall/<app>/open-next.config.ts`没有 `--config-path`,打开后一段 `open-next.config.ts` 在项目根处.
    
4.  检查 `.open-next/server-functions/default/node_modules/sharp/package.json` 财务报告和审定财务报表 `.open-next/image-optimization-function/node_modules/sharp/package.json` 都说0.35.5 `@img/sharp-linux-arm64` 每一个。 然后检查该建筑没有与涡轮包装运行: `grep -rlE 'sharp-[0-9a-f]{8,}' .open-next/server-functions/default` 绝对不能打印。 它所打印的一个文件指由散列名所拼写出的一个涡轮包构建;设置构建命令并再构建. 于2026年10月15日与Next.js 16.3.8 和 `@opennextjs/aws` 4.1.6 在输入锐利的最小应用程序上,grep打印出涡轮包所建的服务器块,没有用于网页包;在Next.js15.4.10上的Webpack所建的Webload网站模板包也打印出任何内容.
    
    fjall 39.0.7 并后写出将尖口0.35.5放入两个功能的安装块. 一个早期CLI的应用脚手架 保留了它用脚手架的块 直到你替换它 `sharpInstallConfig` 使用有效载荷模式页给出的状态声明.
    
5.  部署: `fjall deploy <app> --skip-build`。 。 。 .
    

在每次部署改变项目代码或迁移之前,用步骤2至步骤4重建: `--skip-build` 随时随地部署 `.open-next` 别动.

## 许可证

专有——见 [自由主义](https://npmcn.com/package/%40fjall/payload/LICENSE)。 。 。 .

## 常见问题

### @fjall/payload 是什么？

Fjall AWS适配器和有效载荷CMS的公用事业

### 如何安装 @fjall/payload？

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

### @fjall/payload 支持 TypeScript 吗？

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

### @fjall/payload 支持 ESM 还是 CommonJS？

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

### @fjall/payload 需要什么版本的 Node\.js？

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

### @fjall/payload 可以商用吗？

@fjall/payload 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @fjall/payload 的下载量有多少？

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

### @fjall/payload 还在维护吗？

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