# @fastify/aws-lambda 中文文档

规范地址：https://npmcn.com/package/%40fastify/aws-lambda/

版本：6\.4\.2
npm 元数据更新时间：2026-10-10T10:01:36.304Z
中文译文更新时间：2026-11-14T11:15:05.614Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：35.1 kB，8 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-06-04T17:51:08.834Z
- 最新版本发布：2026-10-10T10:01:35.918Z
- 近 30 天下载量：1700902（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 6 个）

## 中文简介

被aws-serverless-express所启发,与有注入功能的快活合作.

## 安装

```sh
npm install @fastify/aws-lambda
```

也可以使用：`pnpm add @fastify/aws-lambda`、`yarn add @fastify/aws-lambda`、`bun add @fastify/aws-lambda`

## README

# 导言

[![CI](https://github.com/fastify/aws-lambda-fastify/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/aws-lambda-fastify/actions/workflows/ci.yml) [![NPM version](https://img.shields.io/npm/v/@fastify/aws-lambda.svg?style=flat)](https://www.npmjs.com/package/@fastify/aws-lambda)

受守则启发 [无服务器表达式](https://github.com/CodeGenieApp/serverless-express) 图书馆定制 [快捷化](https://fastify.dev/) 网络框架.

**不使用内部套接字,使用 Fastify 的 [注入](https://fastify.dev/docs/latest/Guides/Testing/#testing-with-http-injection) 函数.**

**看来 [快点](https://github.com/fastify/aws-lambda-fastify#%EF%B8%8Fsome-basic-performance-metrics)** _(如名称所暗示)_ **比起来 [无服务器表达式](https://github.com/CodeGenieApp/serverless-express) 财务报告和审定财务报表 [aws- server- fastify (英语)](https://github.com/benMain/aws-serverless-fastify) 😉**

## 安装

```bash
$ npm i @fastify/aws-lambda
```

## 选项

**@ fastify/aws-lambda (法语)** 可通过下列方式选择: `awsLambdaFastify(app, options)`

| 属性 | 说明 | 默认值 |
| --- | --- | --- |
| 二进制MimeTypes | 矩阵 `Content-Type` 要作为二进制处理的值( API Gateway 的基准64- 编码)。 见 [二进制回复](https://npmcn.com/package/%40fastify/aws-lambda/#readme-binary-responses)。 。 。 . | `[]` |
| 执行Base64 | 函数 `(res) => boolean` 决定反应机构是否应该采用基础64编码。 省略时,内置默认基数64-encode 以非识别值响应 `Content-Encoding` (即说. `gzip`, (中文(简体) ), `br`, (中文(简体) ), `deflate`, (中文(简体) ), `zstd`见 [二进制回复](https://npmcn.com/package/%40fastify/aws-lambda/#readme-binary-responses)。 。 。 . | `undefined` _(跌回一个) `Content-Encoding`\-意识到默认)_ |
| 禁用Base64 编码 | 禁用响应的基础64编码并省略 `isBase64Encoded` 属性。 何时 `undefined`,当 `payloadAsStream` 实值 `true` 而请求并非来自ALB. | `undefined` |
| 序列化 Lambda 参数 | 在 http 页眉中激活 Lambda 事件和背景的序列 `x-apigateway-event` `x-apigateway-context` | `false` _(曾经是) `true` 用于 <v2.0.0)_ |
| 装饰请求 | 用 Lambda 事件和上下文装饰封条请求 `request.awsLambda.event` `request.awsLambda.context` | `true` |
| 装饰 属性Name | 请求装饰的默认属性名称 | `awsLambda` |
| 调用后等待 ForEmpty EventLoop | 见: [正式文件](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-context.html) | `undefined` |
| 保留 | 保留 API 网关 URL 的舞台部分 | `false` |
| 路径 | 使用定义的路径Paremeter作为路径(即:. `'proxy'`(中文(简体) ) | `false` |
| 解析Comma分离的QueryParams | 用逗号将查询字符串分析成一系列值。 使用逗号时影响查询字符串解析器的行为 [有效载荷格式版本 2.0](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html#http-api-develop-integrations-lambda.proxy-format) | `true` |
| 有效载荷AsStream | 如果设定为真实, 响应是流并可用 `awslambda.streamifyResponse` | `false` |
| 复数数值 | 如果使用带有多值标题属性的 ALB 设置为真 | `false` |

## 二进制回复

API Gateway需要知道一个响应机构何时是二进制,这样它就可以被基数64-编码在线上(`isBase64Encoded: true` 在Lambda返回有效载荷. **@ fastify/aws-lambda (法语)** 通过两个互补路径来决定这一点——至少一个匹配触发基础64编码:

-   **`binaryMimeTypes`** - 与答复相符 `Content-Type` 面对一个允许入境者。 当二进制-性是内容类型本身的属性(例如. `application/octet-stream`, (中文(简体) ), `image/png`, (中文(简体) ), `application/zip`) (中文(简体) ).
-   **`enforceBase64`** ——这个功能随响应而来. 当二进制 - 性质取决于其它事物时使用此功能 `Content-Type` - 最常见的是当身体是 **压缩** (二进制字节)但内容类型本身类似文本(例如. `application/json` 与 `Content-Encoding: br`) (中文(简体) ).

何时 `enforceBase64` 被省略,该基数64-encode中的内置默认踢出任何非识别响应 `Content-Encoding`。 。 。 . **因此压缩的响应( A)`gzip`, (中文(简体) ), `br`, (中文(简体) ), `deflate`, (中文(简体) ), `zstd`,.)在盒子里工作——你不需要自己为普通案件写回调.**

### 示例——让压缩后的响应自动通过

```js
const fastify = require('fastify')
const compress = require('@fastify/compress')
const awsLambdaFastify = require('@fastify/aws-lambda')

const app = fastify()
app.register(compress, { global: true, encodings: ['br', 'gzip'] })
app.get('/', (req, reply) => reply.send({ hello: 'world' }))

// Responses gain Content-Encoding: br|gzip, and the default behaviour
// auto-base64-encodes them for API Gateway. No extra option needed.
exports.handler = awsLambdaFastify(app)
```

### 示例 — 在默认值上添加自定义规则

```js
exports.handler = awsLambdaFastify(app, {
  binaryMimeTypes: ['application/octet-stream', 'image/png'],
  // Custom rule for binary detection. Note: when you pass enforceBase64,
  // it REPLACES the built-in Content-Encoding default — it doesn't compose.
  // Re-implement the compression check yourself if you still want it.
  enforceBase64: (res) => {
    if (res.headers['content-type'] === 'application/x-protobuf') return true
    const enc = res.headers['content-encoding']
    return !!enc && enc !== 'identity'
  }
})
```

## 示例

### 羊肉酱

```js
const awsLambdaFastify = require('@fastify/aws-lambda')
const app = require('./app')

const proxy = awsLambdaFastify(app)
// or
// const proxy = awsLambdaFastify(app, { binaryMimeTypes: ['application/octet-stream'], serializeLambdaArguments: false /* default is true */ })

exports.handler = proxy
// or
// exports.handler = (event, context, callback) => proxy(event, context, callback)
// or
// exports.handler = (event, context) => proxy(event, context)
// or
// exports.handler = async (event, context) => proxy(event, context)
```

### 应用程序.js

```js
const fastify = require('fastify')

const app = fastify()
app.get('/', (request, reply) => reply.send({ hello: 'world' }))

if (require.main === module) {
  // called directly i.e. "node app"
  app.listen({ port: 3000 }, (err) => {
    if (err) console.error(err)
    console.log('server listening on 3000')
  })
} else {
  // required as a module => executed on aws lambda
  module.exports = app
}
```

当执行你的羊肉达功能时 我们不需要听一个特定的端口, 所以,我们只是输出 `app` 在这种情况下. 这个 [`lambda.js`](https://github.com/fastify/aws-lambda-fastify#lambdajs) 文件将使用此导出 .

当你像往常一样执行快速化应用程序时, 即说. `node app.js` _(检测结果可能是 `require.main === module`(中文(简体) )_, (中文(简体) ), 您通常可以听取您的端口,所以您仍然可以在本地运行您的快感功能.

### #

#### Lambda 论点

原本的Lambda事件和上下文通过Fastify请求传递,可以像这样被使用:

```js
app.get('/', (request, reply) => {
  const event = request.awsLambda.event
  const context = request.awsLambda.context
  // ...
})
```

_如果您不喜欢, 您可以设置 : `decorateRequest` 选项到 `false`。 。 。 ._

或者,原始的lambda事件和上下文通过信头传递,并可以像这样使用,如果设置 `serializeLambdaArguments` 选项到 `true`数字 :

```js
app.get('/', (request, reply) => {
  const event = JSON.parse(decodeURIComponent(request.headers['x-apigateway-event']))
  const context = JSON.parse(decodeURIComponent(request.headers['x-apigateway-context']))
  // ...
})
```

#### 低温起步时间

自兹 [AWS Lambda现在能够使用ECMAScript模块](https://aws.amazon.com/blogs/compute/using-node-js-es-modules-and-top-level-await-in-aws-lambda/) 在节点.js 14 运行时,您可以在使用时降低寒冷的起步间隔 [备付货币](https://aws.amazon.com/blogs/compute/new-for-aws-lambda-predictable-start-up-times-with-provisioned-concurrency/) 感谢顶级等待功能.

我们可以用这个叫 [`fastify.ready()`](https://fastify.dev/docs/latest/Reference/Server/#ready) 在 Lambda 处理器功能外的函数,像这样:

```js
import awsLambdaFastify from '@fastify/aws-lambda'
import app from './app.js'
export const handler = awsLambdaFastify(app)
await app.ready() // needs to be placed after awsLambdaFastify call because of the decoration: https://github.com/fastify/aws-lambda-fastify/blob/main/index.js#L9
```

_[给](https://github.com/fastify/aws-lambda-fastify/issues/89) 您可以找到讨论此特性的近似问题._

#### 支持反应流`payloadAsStream`(中文(简体) )

```js
import awsLambdaFastify from '@fastify/aws-lambda'
import { promisify } from 'node:util'
import stream from 'node:stream'
import app from './app.js'

const pipeline = promisify(stream.pipeline)
const proxy = awsLambdaFastify(app, { payloadAsStream: true })
export const handler = awslambda.streamifyResponse(async (event, responseStream, context) => {
  const { meta, stream } = await proxy(event, context)
  responseStream = awslambda.HttpResponseStream.from(responseStream, meta)
  await pipeline(stream, responseStream)
})
await app.ready() // https://github.com/fastify/aws-lambda-fastify/issues/89
```

_[给](https://github.com/fastify/aws-lambda-fastify/issues/154) 您可以找到讨论此特性的近似问题._

## \*一些基本业绩指标

**@fastify/aws-lambda(装饰请求:虚假)** 页:1 **56 892项行动/秒** ±3.73%(79次抽样)

**@ fastify/aws-lambda (法语)** 页:1 **56 571项行动/sec** ±3.52%(82次抽样)

**@fastify/aws-lambda(序列化Lambda Arguments: true)** 页:1 **56 499项行动/sec** ±3.56%(76次抽样)

**[无服务器 - http](https://github.com/dougmoscrop/serverless-http)** 页:1 **45 867起行动/sec** ±4.42%(83次抽样)

**[aws- server- fastify (英语)](https://github.com/benMain/aws-serverless-fastify)** 页:1 **17 937起行动/事件** ±1.83%(86次抽样)

**[无服务器表达式](https://github.com/CodeGenieApp/serverless-express)** 页:1 **16 647项行动/sec** ±2.88%(87次抽样)

最快的是,我们 **@fastify/aws-lambda(装饰请求:虚假), @fastify/aws-lambda**

#### 考虑

-   对于一次可能看不到几分钟流量的应用程序,你可以看到 [开始冷](https://aws.amazon.com/blogs/compute/container-reuse-in-lambda/)
-   只有无国籍人
-   API Gateway有29秒的超时,而Lambda最长的执行时间为15分钟. (使用应用程序负载平衡器没有超时限制,所以Lambda最大执行时间是相关的)
-   如果您在Fastify(即连接、快递、Koa、Restana、Sails、Hapi、Restify)之外使用另一个网络框架,或者想要使用一个更通用的无服务器代理框架,请查看: [无服务器 - http](https://github.com/dougmoscrop/serverless-http) 或者说 [无服务器适应器](https://github.com/H4ad/serverless-adapter)

#### 谁在用?

[![locize is using @fastify/aws-lambda](https://raw.githubusercontent.com/fastify/aws-lambda-fastify/main/images/logos/locize.png)](https://www.locize.com/)

* * *

本页面所显示的标志是各自组织的财产,属于 与@fastify/aws-lambda(麻省理工学院)相同.

## 常见问题

### @fastify/aws-lambda 是什么？

被aws-serverless-express所启发,与有注入功能的快活合作\.

### 如何安装 @fastify/aws-lambda？

在项目目录运行 npm install @fastify/aws-lambda，或使用 pnpm add / yarn add / bun add。

### @fastify/aws-lambda 支持 TypeScript 吗？

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

### @fastify/aws-lambda 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @fastify/aws-lambda 可以商用吗？

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

### @fastify/aws-lambda 的下载量有多少？

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

### @fastify/aws-lambda 还在维护吗？

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