# @auth0/auth0-fastify-api 中文文档

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

版本：1\.3\.0
npm 元数据更新时间：2026-07-14T10:25:53.157Z
中文译文更新时间：2026-11-07T05:55:57.446Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：58.8 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-03-28T14:35:33.518Z
- 最新版本发布：2026-05-18T14:38:24.863Z
- 近 30 天下载量：107049（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 2 个）

## 中文简介

Auth0 SDK 用于在 JavaScript 运行时快速化 API

## 安装

```sh
npm install @auth0/auth0-fastify-api
```

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

## README

Auth0快取-API SDK是一个用于保护API在快取应用中的库.

![Release](https://img.shields.io/npm/v/@auth0/auth0-fastify-api) ![Downloads](https://img.shields.io/npm/dw/@auth0/auth0-fastify-api) [![License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT)

📚 [文档](https://npmcn.com/package/%40auth0/auth0-fastify-api/#readme-documentation) - 🚀 [开始](https://npmcn.com/package/%40auth0/auth0-fastify-api/#readme-getting-started) - 💬 [反馈](https://npmcn.com/package/%40auth0/auth0-fastify-api/#readme-feedback)

## 文档

-   [实例](https://github.com/auth0/auth0-fastify/blob/main/packages/auth0-fastify-api/EXAMPLES.md) - 不同用法的例子.
-   [Docs 站点](https://auth0.com/docs) - 探索我们的文件网站 了解更多关于Auth0.

## 开始

### 1\. 安装SDK

```shell
npm i @auth0/auth0-fastify-api
```

这个库需要Node.js 20 LTS和较新的LTS版本.

### 3\. 为 API 注册 Auth0 快捷插件

将 Auth0 与 Fastify 实例一起注册为 API 的快取插件 .

```ts
import fastifyAuth0Api from '@auth0/auth0-fastify-api';

const fastify = Fastify({
  logger: true,
});

fastify.register(fastifyAuth0Api, {
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
});
```

这个 `AUTH0_DOMAIN` 可从 [Auth0 剪贴板](https://manage.auth0.com/) 一旦你创造了API. 这个 `AUTH0_AUDIENCE` 是正在调用的 API 的标识符。 您可以在 Auth0 仪表板的 API 部分中找到这个 .

#### 保护 API 路由

为了保护 API 路径, 您可以使用 SDK 的 `requireAuth()` 前汉德勒中的方法 :

```ts
fastify.register(() => {
  fastify.get(
    '/protected-api',
    {
      preHandler: fastify.requireAuth(),
    },
    async (request: FastifyRequest, reply) => {
      return `Hello, ${request.user.sub}`;
    }
  );
});
```

SDK将从信使中提取的债权暴露为 `user` 财产 `FastifyRequest` 对象. 为了使用自定义用户类型来代表自定义要求,您可以配置 `Token` 模块中类型 :

```ts
declare module '@auth0/auth0-fastify-api' {
  interface Token {
    id: number;
    name: string;
    age: number;
  }
}
```

这样做将更改用户类型 `FastifyRequest` 自动对象 :

```ts
fastify.register(() => {
  fastify.get(
    '/protected-api',
    {
      preHandler: fastify.requireAuth(),
    },
    async (request: FastifyRequest, reply) => {
      return `Hello, ${request.user.name}`;
    }
  );
});
```

> \[大  
> 以上是用无记名符号保护API路由,而不是使用会话保护服务器侧渲染路由.

### DPoP( 证明 )

DPoP将访问令牌绑定在一个特定的客户端的密钥对上,防止被窃取的令牌被攻击者重放. SDK以三种模式支持DPop:

-   **`allowed`** (默认) : 接受 Bearer 和 DPop 绑定符 .
-   **`required`**:仅接受DPoP捆绑的活字符号;拒绝熊克活字符号.
-   **`disabled`**: DPoP被忽略; 仅以熊为主的行为.

```ts
import fastifyAuth0Api from '@auth0/auth0-fastify-api';

const fastify = Fastify({ logger: true });

fastify.register(fastifyAuth0Api, {
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
  dpop: { mode: 'required' },
});
```

当 DPOP 启用时,客户端发送 :

1.  一个 `Authorization: DPoP <access_token>` 页眉( 代替 `Bearer`) (中文(简体) ).
2.  A 类 `DPoP` 包含与请求方法和 URL 绑定的 JWT 证据的头条 .

SDK 自动从请求中取出 DPop 证明, 并对照访问符验证它 `cnf.jkt` ,并核实证明与当前 HTTP 方法和 URL 匹配.

关于完整的配置参考文献和错误处理细节,参见 [EXAMPLES.md中的DPOP部分](https://github.com/auth0/auth0-fastify/blob/main/packages/auth0-fastify-api/EXAMPLES.md#dpop-demonstration-of-proof-of-possession)。 。 。 .

### 顶端交换

使用 `fastify.auth0Client.getTokenOnBehalfOf()` 当您快速化 API 需要代表同一用户调用下游 API时,例如在 MCP 服务器中. 该方法在保留用户身份的同时,将所接收到的访问令牌换成被放入下游API范围的新信使.

`getTokenOnBehalfOf()` 需要保密客户。 注册插件为 `clientId` 财务报告和审定财务报表 `clientSecret` (或 `clientAssertionSigningKey` 用于客户断言认证).

```ts
import fastifyAuth0Api from '@auth0/auth0-fastify-api';

const fastify = Fastify({ logger: true });

fastify.register(fastifyAuth0Api, {
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
  clientId: '<AUTH0_CLIENT_ID>',
  clientSecret: '<AUTH0_CLIENT_SECRET>',
});

fastify.register(() => {
  fastify.post(
    '/schedule-meeting',
    {
      preHandler: fastify.requireAuth(),
    },
    async (request: FastifyRequest) => {
      // request.getToken() returns the raw JWT without the `Bearer ` prefix.
      const obo = await fastify.auth0Client!.getTokenOnBehalfOf(request.getToken()!, {
        audience: 'https://calendar-api.example.com',
        scope: 'calendar:read calendar:write',
      });

      const response = await fetch('https://calendar-api.example.com/meetings', {
        method: 'POST',
        headers: { authorization: `Bearer ${obo.accessToken}` },
        body: JSON.stringify(request.body),
      });

      return response.json();
    }
  );
});
```

关于包括处理出错、行为索赔检查和下游核查员模式在内的全程通行情况,请参见 [顶端交换](https://github.com/auth0/auth0-fastify/blob/main/packages/auth0-fastify-api/EXAMPLES.md#on-behalf-of-token-exchange) 节 [缩略语.md](https://github.com/auth0/auth0-fastify/blob/main/packages/auth0-fastify-api/EXAMPLES.md)。 。 。 .

## 反馈

### 捐款

我们赞赏反馈和对这次再投资的贡献! 在开始前,请阅读以下内容:

-   [Auth0的一般贡献准则](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
-   [Auth0 行为守则准则](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
-   [这个Repo的贡献指南](https://github.com/auth0/auth0-fastify/blob/main/CONTRIBUTING.md)

### 提出问题

请提供反馈或报告错误 [提出我们的问题追踪器](https://github.com/auth0/auth0-fastify/issues)。 。 。 .

## 脆弱性报告

请不要在公共 GitHub 问题跟踪器上报告安全漏洞 。 这个 [负责任的披露程序](https://auth0.com/responsible-disclosure-policy) 详细说明披露安全问题的程序.

## 什么是奥特?

![Auth0 Logo](https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png)

Auth0是一个易于执行,可适应的认证和授权平台. 学习更多退房 [为什么是Auth0?](https://auth0.com/why-auth0)

这个项目根据麻省理工学院的许可证获得许可。 见 [自由主义](https://github.com/auth0/auth0-fastify/blob/main/packages/auth0-fastify-api/LICENSE) 需要更多信息的文件.

## 常见问题

### @auth0/auth0-fastify-api 是什么？

Auth0 SDK 用于在 JavaScript 运行时快速化 API

### 如何安装 @auth0/auth0-fastify-api？

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

### @auth0/auth0-fastify-api 支持 TypeScript 吗？

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

### @auth0/auth0-fastify-api 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @auth0/auth0-fastify-api 可以商用吗？

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

### @auth0/auth0-fastify-api 的下载量有多少？

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

### @auth0/auth0-fastify-api 还在维护吗？

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