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

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

版本：1\.0\.0
npm 元数据更新时间：2026-10-08T11:51:55.049Z
中文译文更新时间：2026-11-07T06:01:34.669Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：71.8 kB，51 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.12\.0 \|\| \>=24
- 运行依赖：1 个
- peer 依赖：express ^4\.18\.0 \|\| ^5\.0\.0
- 首次发布：2026-06-04T08:40:55.002Z
- 最新版本发布：2026-10-08T11:51:54.650Z
- 近 30 天下载量：2690（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

Express API的 Auth0 SDK 在 JavaScript 运行时

## 安装

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

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

## README

Auth0 Express-API SDK是一个用于在Express应用程序中保护API的库.

![Release](https://img.shields.io/npm/v/@auth0/auth0-express-api) ![Downloads](https://img.shields.io/npm/dw/@auth0/auth0-express-api) [![License](https://img.shields.io/badge/license-Apache%20License%202.0-blue)](https://opensource.org/license/apache-2-0)

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

## 文档

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

## 特征

直接跳到所需的能力.

| 特性 | 它会做什么 |
| --- | --- |
| [快开始](https://npmcn.com/package/%40auth0/auth0-express-api/#readme-getting-started) | 用 `createAuth0Api` 数行 |
| [环境变量](https://npmcn.com/package/%40auth0/auth0-express-api/EXAMPLES.md#using-environment-variables) | 配置从 `AUTH0_*` env vars 而不是硬编码 |
| [保护 API 路由( X)`requiresAuth`(中文(简体) )](https://npmcn.com/package/%40auth0/auth0-express-api/#readme-protecting-api-routes) | 需要有效的无记名访问令牌 |
| [读取令牌索赔( E)`req.auth0.user`(中文(简体) )](https://npmcn.com/package/%40auth0/auth0-express-api/#readme-protecting-api-routes) | 从已核实的代号中提取的存取请求 |
| [代表用户调用另一个 API](https://npmcn.com/package/%40auth0/auth0-express-api/EXAMPLES.md#calling-another-api-on-behalf-of-the-user) | 换一个给下游API的代币 |
| [呼叫第三方 API( Token Vault)](https://npmcn.com/package/%40auth0/auth0-express-api/EXAMPLES.md#calling-a-third-party-api-with-token-vault) | 给Token Vault的来电者获取谷歌或Slack访问符 |
| [交换外部令牌( Custom Token Exchange)](https://npmcn.com/package/%40auth0/auth0-express-api/EXAMPLES.md#exchanging-an-external-token-for-an-auth0-token) | 将遗产或伙伴符号转换为 Auth0 访问符号 |
| [处理一个失败的托肯断层交换](https://npmcn.com/package/%40auth0/auth0-express-api/EXAMPLES.md#handling-a-failed-connection-exchange) | 告诉房客拒绝的错位 `isConnectionExchangeError` |
| [需要具体范围](https://npmcn.com/package/%40auth0/auth0-express-api/EXAMPLES.md#requiring-specific-scopes) | 大门路线 `scopesInclude` (匹配全部或任何) |
| [授权债权](https://npmcn.com/package/%40auth0/auth0-express-api/#readme-authorization-with-claims) | 限制路线 `claimEquals`, (中文(简体) ), `claimIncludes`, (中文(简体) ), `claimCheck` |
| [自定义符号/ 用户类型](https://npmcn.com/package/%40auth0/auth0-express-api/#readme-custom-types) | 通过模块增强键输入您的自定义要求 |
| [自定义 `fetch`](https://npmcn.com/package/%40auth0/auth0-express-api/EXAMPLES.md#configuring-a-customfetch-implementation) | 在自己获取中交换( 代理、 重试、 仪器) |

## 开始

### 1\. 安装SDK

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

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

### 3\. 注册 Auth0 特快 API 路由器

以您的快递实例注册 Auth0 Express API 路由器 .

```ts
import express from 'express';
import { createAuth0Api } from '@auth0/auth0-express-api';

const app = express();

app.use(createAuth0Api({
  domain: '<AUTH0_DOMAIN>',
  audience: '<AUTH0_AUDIENCE>',
}));
```

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

**环境变量支持**:也可以使用环境变量配置 SDK(`AUTH0_DOMAIN`, (中文(简体) ), `AUTH0_AUDIENCE`) (中文(简体) ). 见 [缩略语.md](https://github.com/auth0/auth0-express/blob/main/packages/auth0-express-api/EXAMPLES.md#using-environment-variables) 详细情况.

#### 保护 API 路由

为了保护 API 路径, 您可以使用 `requiresAuth` 中间软件 :

```ts
import { requiresAuth } from '@auth0/auth0-express-api';

app.get(
  '/protected-api',
  requiresAuth(),
  async (req, res) => {
    res.json({ message: `Hello, ${req.auth0.user!.sub}` });
  }
);
```

SDK将从信使中提取的债权暴露为 `user` 财产 `req.auth0` 对象.

#### 债权授权

除了基本的认证外,您还可以根据特定符号要求授权请求:

```ts
import {
  requiresAuth,
  claimEquals,
  claimIncludes,
  claimCheck,
  scopesInclude,
} from '@auth0/auth0-express-api';

// Check if a claim equals a specific value
app.get('/admin', requiresAuth(), claimEquals('isAdmin', true), handler);

// Check if a claim includes all specified values
app.get('/admin/edit', requiresAuth(), claimIncludes('roles', 'admin', 'editor'), handler);

// Custom validation logic
app.get('/premium', requiresAuth(), claimCheck(
  (req, token) => token.tier === 'premium' || token.roles?.includes('admin'),
  'Premium tier or admin role required'
), handler);

// Flexible scope matching - match ALL (default) or ANY
app.get('/admin/edit', requiresAuth(), scopesInclude('read:admin write:admin'), handler);
app.get('/messages', requiresAuth(), scopesInclude('read:messages read:admin', { match: 'any' }), handler);
```

见 [缩略语.md](https://github.com/auth0/auth0-express/blob/main/packages/auth0-express-api/EXAMPLES.md#authorization-with-claims) 更多的授权模式.

#### 自定义类型

为了使用自定义用户类型来代表自定义要求,您可以配置 `Token` 模块中类型 :

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

这样做将更改用户类型 `req.auth0.user` 自动对象 :

```ts
app.get(
  '/protected-api',
  requiresAuth(),
  async (req, res) => {
    res.json({ message: `Hello, ${req.auth0.user!.name}` });
  }
);
```

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

## 反馈

### 捐款

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

-   [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-express/blob/main/CONTRIBUTING.md)

### 提出问题

请提供反馈或报告错误 [提出我们的问题追踪器](https://github.com/auth0/auth0-express/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)

这个项目根据Apache许可证2.0获得许可. 见 [自由主义](https://github.com/auth0/auth0-express/blob/main/packages/auth0-express-api/LICENSE) 需要更多信息的文件.

## 常见问题

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

Express API的 Auth0 SDK 在 JavaScript 运行时

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

在项目目录运行 npm install @auth0/auth0-express-api，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：express（^4\.18\.0 \|\| ^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

### @auth0/auth0-express-api 需要什么版本的 Node\.js？

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

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

@auth0/auth0-express-api 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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