# @auth0/nextjs-auth0 中文文档

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

版本：4\.33\.0
npm 元数据更新时间：2026-10-22T14:25:30.561Z
中文译文更新时间：2026-11-07T05:50:23.927Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.3 MB，187 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：6 个
- peer 依赖：next ^14\.2\.35 \|\| ~15\.0\.7 \|\| ~15\.1\.11 \|\| ~15\.2\.8 \|\| ~15\.3\.8 \|\| ~15\.4\.10 \|\| ~15\.5\.9 \|\| ^16\.0\.10，react ^18\.0\.0 \|\| ~19\.0\.1 \|\|  ~19\.1\.2 \|\| ^19\.2\.1，react-dom ^18\.0\.0 \|\| ~19\.0\.1 \|\| ~19\.1\.2 \|\| ^19\.2\.1
- 首次发布：2019-09-17T12:31:37.677Z
- 最新版本发布：2026-10-22T14:25:29.382Z
- 近 30 天下载量：4614167（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：146（近 12 个月 33 个）

## 中文简介

下一个.js SDK

## 安装

```sh
npm install @auth0/nextjs-auth0
```

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

## README

![Auth0 Next.js SDK Banner](https://cdn.auth0.com/website/sdks/banners/nextjs-auth0-banner.png)

Auth0 Next.js SDK是一个用于在Next.js应用程序中执行用户认证的库.

[![Auth0 Next.js SDK Release](https://img.shields.io/npm/v/@auth0/nextjs-auth0)](https://www.npmjs.com/package/@auth0/nextjs-auth0) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/auth0/nextjs-auth0) ![Auth0 Next.js SDK Downloads](https://img.shields.io/npm/dw/@auth0/nextjs-auth0) [![Auth0 Next.js SDK License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT)

📚 [文档](https://npmcn.com/package/%40auth0/nextjs-auth0/#readme-documentation) - 🚀 [开始](https://npmcn.com/package/%40auth0/nextjs-auth0/#readme-getting-started) - 💻 [API 参考](https://auth0.github.io/nextjs-auth0/) - 💬 [反馈](https://npmcn.com/package/%40auth0/nextjs-auth0/#readme-feedback)

## 文档

-   [快速启动](https://auth0.com/docs/quickstart/webapp/nextjs) - 我们的指南,将Auth0 添加到您的 Next.js 应用程序.
-   [实例](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md) - 很多例子 用于你不同的使用案例.
-   [匿名会话](https://npmcn.com/package/%40auth0/nextjs-auth0/docs/anonymous-sessions.md) - 启用带有访问符和元数据的登录前身份.
-   [警卫](https://github.com/auth0/nextjs-auth0/blob/main/SECURITY.md) - 一些重要的安全通知,你应该检查.
-   [Docs 站点](https://auth0.com/docs) - 探索我们的文件网站 了解更多关于Auth0.

## 开始

### 1\. 安装SDK

```shell
npm i @auth0/nextjs-auth0
```

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

### 2\. 增加环境变量

将以下环境变量添加到您的 `.env.local` 文件 :

```env
AUTH0_DOMAIN=
AUTH0_CLIENT_ID=
AUTH0_CLIENT_SECRET=
AUTH0_SECRET=
APP_BASE_URL= # optional for dynamic preview environments
```

这个 `AUTH0_DOMAIN`, (中文(简体) ), `AUTH0_CLIENT_ID`,以及 `AUTH0_CLIENT_SECRET` 可从 [Auth0 剪贴板](https://manage.auth0.com/) 一旦你创建了一个应用程序. **此申请必须是 `Regular Web Application`**。 。 。 .

这个 `AUTH0_SECRET` 是用于加密会话和交易 cookie 的密钥。 您可以使用 `openssl`数字 :

```shell
openssl rand -hex 32
```

这个 `APP_BASE_URL` 您的应用程序正在运行的 URL 。 本地开发时,这种情况最为常见 `http://localhost:3000`。 。 。 . 如果您省略, SDK 会在运行时从收到的请求主机中推断出基础 URL .

> \[大  
> 您需要在 Auth0 应用程序中通过 [Auth0 剪贴板](https://manage.auth0.com/)数字 :
> 
> -   添加 `http://localhost:3000/auth/callback` 名单 **允许召回 URL**
> -   添加 `http://localhost:3000` 名单 **允许登录 URL**
> 
> 当使用动态主机( 预览环境) 时, 请在 Auth0 应用程序中注册相应的调用和登录 URL .

#### 动态基础 URL( 预览部署)

预览环境`Vercel`, (中文(简体) ), `Netlify`,可以省略 `APP_BASE_URL` 并让 SDK 在运行时从收到的请求主机中推断基础 URL 。 这使得动态预览 URL 在不附加配置的情况下工作 .

如果您知道启动时的基础 URL( 例如稳定生产域), 设置 `appBaseUrl` 或者说 `APP_BASE_URL` 到一个绝对的 URL。 不支持逗号分隔的值 .

由于主机头是不信任的输入,Auth0的"允许回调"URL是这个模式中的安全网:如果所推断的主机没有注册,Auth0拒绝授权请求.

示例(动力学):

```ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client();
```

示例(静态):

```ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client({
  appBaseUrl: "https://app.example.com"
});
```

> \[注\]  
> 在生产过程中依赖动态基站URL时,SDK会执行安全的cookie. 如果您明确设定 `AUTH0_COOKIE_SECURE=false`, (中文(简体) ), `session.cookie.secure=false`,或 `transactionCookie.secure=false`,SDK抛出 `InvalidConfigurationError`。 。 。 .

### 3\. 创建 Auth0 SDK 客户端

创建 Auth0 客户端实例 。 此实例将被导入并用于任何您需要访问服务器上的认证方法的地方 .

将以下内容添加到命名的文件 `lib/auth0.ts`数字 :

```ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client();
```

> \[注\] Auth0Client 自动使用安全默认来管理认证 cookie. 对于高级用例,可以通过提供自己的配置来自定义交易 cookie 行为. 见 [交易 Cookie 配置](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#transaction-cookie-configuration) 详细情况.

### 4\. 添加认证中间软件

Next.js中的认证请求使用中间软件或代理文件在网络边界被截获.  
根据您的 Next.js 版本, 跟踪下面的设置 .

#### \\ 在下一个.js 15

创建一个 `middleware.ts` 在项目根中的文件 :

```ts
import type { NextRequest } from "next/server";

import { auth0 } from "./lib/auth0"; // Adjust path if your auth0 client is elsewhere

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    /*
     * Match all request paths except for:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico, sitemap.xml, robots.txt (metadata files)
     */
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)"
  ]
};
```

> \[注\]  
> 如果你用一个 `src/` 目录,该 `middleware.ts` 文件必须在 `src/` 目录.

#### \\ 在下一个.js 16

Next.js 16引入了名为代理.ts的新公约,取代了中件.ts. 这一变化更好地代表了网络截取边界,统一了请求处理 对于边缘和节点运行时间.

在工程的根部创建代理. ts文件( 或者将您现有的中间软件重命名为代理. ts) :

```ts
import { auth0 } from "./lib/auth0";

export async function proxy(request: Request) { // Note that proxy uses the standard Request type
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)"
  ]
};
```

> \[大  
> 从开始 **下一个.js 16**,用于处理认证边界的建议文件为 **`proxy.ts`**。您仍可继续使用 **`middleware.ts`** 对于后向相容性,将在 **边缘运行时间** 在下一个.js 16. 然而,这是 **已贬值** 用于节点运行时间,并将在未来发布中被删除.
> 
> 新的代理层也会在路由管中稍早地执行,以确保您的匹配器模式不会与其他代理或中间软件路径相冲突.
> 
> 此外,边缘运行时间现在采用更严格的头和饼干验证,  
> 因此避免设置非字符串饼干值或无效的标题格式.

> \[大 这个宽广的中件匹配器对于滚动会话和安全特性至关重要. 关于滚动会话停用时的情景,见 [会话配置](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#session-configuration) 备选办法.

您现在可以通过将用户重定向到您的应用程序来开始认证您的用户 `/auth/login` 路径 :

```tsx
import { auth0 } from "./lib/auth0"; // Adjust path if your auth0 client is elsewhere

export default async function Home() {
  const session = await auth0.getSession();

  if (!session) {
    return (
      <main>
        <a href="/auth/login?screen_hint=signup">Sign up</a>
        <a href="/auth/login">Log in</a>
      </main>
    );
  }

  return (
    <main>
      <h1>Welcome, {session.user.name}!</h1>
    </main>
  );
}
```

> \[大  
> 默认 `<Link href="/auth/login">` 安全 —— SDK 检测 AUTO 前置信头并返回 `204 No Content` 没有写交易饼干。 避免 `<Link href="/auth/login" prefetch={true}>` (FullL preftch):它不会发送可被检测到的预取信头,因此SDK无法将其与真实的导航区分开来,并将开始登录流. 使用平面 `<a>` 标记或 `<Link prefetch={false}>` 如果您需要在所有预选模式中安全。 见 [防止“ 431 请求标题字段太大” 出错](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#preventing-431-request-header-fields-too-large-errors) 详细情况.

## 自定义客户端

您可以使用以下选项自定义客户端:

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| 域名 | `string | DomainResolver` | 租户的 Auth0 域名( 例如 : `example.us.auth0.com`) (中文(简体) ). 接受静态字符串或 `DomainResolver` 函数用于 [多个自定义域](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#multiple-custom-domains-mcd)后退至 `AUTH0_DOMAIN` 环境变量. |
| 客户端ID | `string` | Auth0 客户端 ID 。 如果未指定,将从 `AUTH0_CLIENT_ID` 环境变量. |
| 客户端加密 | `string` | Auth0客户秘密 如果未指定,将从 `AUTH0_CLIENT_SECRET` 环境变量. |
| 授权 参数 | `AuthorizationParameters` | 传递给 `/authorize` 终点 见 [通过授权参数](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#passing-authorization-parameters) 更多细节. |
| 客户端签名键 | `string` 或者说 `CryptoKey` | 专用密钥 `private_key_jwt` 客户。 这也可以通过 `AUTH0_CLIENT_ASSERTION_SIGNING_KEY` 环境变量. |
| 客户端签名 | `string` | 用于签名客户端断言JWT的算法. 这也可以通过下列途径提供: `AUTH0_CLIENT_ASSERTION_SIGNING_ALG` 环境变量. |
| 应用程序 | `string` | 您应用程序的 URL( 例如: `http://localhost:3000`) (中文(简体) ). 如果未指定,将从 `APP_BASE_URL` 环境变量或运行时从请求主机推断. |
| 登录战略 | `"auto" | "oidc" | "v2"` | 登出端点选择策略. `"auto"` (默认)在可用时使用 OIDC 登录, 返回到 `/v2/logout`。 。 。 . `"oidc"` 总是使用 OIDC 登录. `"v2"` 总是使用 `/v2/logout` 支持通配符 URL 的结束点 。 见 [配置登录战略](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#configuring-logout-strategy) 详细情况. |
| 包括 IdTokenHint InOIDCLogout Url 数据 | `boolean` | 配置是否包含 `id_token_hint` 在 OIDC 为隐私登录 URL 中。 默认为 `true` (建议. 何时 `false`,将 PII 从登录 URL 中排除,但减少 DoS 保护。 见 [OIDC 登录隐私配置](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#oidc-logout-privacy-configuration) 详细情况. |
| 隐藏 | `string` | 一个32字节,六字码的秘密 用于加密饼干。 如果未指定,将从 `AUTH0_SECRET` 环境变量. |
| 签名返回到 Path | `string` | 将用户重定向到成功认证后的路径 。 默认为 `/`。 。 。 . |
| 第二届会议 | `SessionConfiguration` | 配置会话超时以及是否使用滚动会话,包括 a `beforeSessionRolled` 预先确定每个请求有选择地滚动会话。 见 [会话配置](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#session-configuration) 财务报告和审定财务报表 [选择性滚动会议](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#selectively-rolling-sessions) 其他细节。 还允许配置饼干属性,例如 `domain`, (中文(简体) ), `path`, (中文(简体) ), `secure`, (中文(简体) ), `sameSite`,以及 `transient`未指定时,可以使用 `AUTH0_COOKIE_*` 环境变量。 说明: `httpOnly` 总是 `true`。见 [Cookie 配置](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#cookie-configuration) 详细情况. |
| 启用 Parallel 交易 | `boolean` | 通过使用每个流量独特的交易 cookie来启用对多个并行认证流量的支持. 何时 `true` (default),每次认证尝试都会得到自己的交易 cookie,并带有独特的状态后缀. 何时 `false`,使用单一的共享交易 cookie,可能导致与同时进行认证尝试相冲突. 见 [交易 Cookie 配置](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#transaction-cookie-configuration) 详细情况. |
| 交易库 | `TransactionCookieOptions` | 为认证流配置交易 cookie 管理 。 你可以控制饼干过期 和其他饼干选项。 见 [交易 Cookie 配置](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#transaction-cookie-configuration) 详细情况. |
| 届会之前 | `BeforeSessionSavedHook` | 一种在持续之前操纵会话的方法。 见 [届会之前](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#beforesessionsaved) 其他细节. |
| 回电 | `OnCallbackHook` | 尝试认证后处理错误或管理重定向的方法 。 见 [回电](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#oncallback) 其他细节. |
| 届会 | `SessionStore` | 自定义会话存储执行用于持续会话到数据存储 。 见 [数据库会议](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#database-sessions) 其他细节. |
| 请求认证 | `boolean` | 配置 SDK 在与授权服务器通信时使用被推后的授权请求(PAR)协议. |
| 路线 | `Routes` | 配置认证路径 。 见 [自定义路线](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#custom-routes) 其他细节. |
| 允许无安全请求 | `boolean` | 允许向授权服务器提出不安全的请求 。 这在对本地不支持TLS的模拟OIDC供应商进行测试时可能有用. 此选项只能在 `NODE_ENV` 未设定为 `production`。 。 。 . |
| httpTimeout 时间 | `number` | 用于认证请求的 HTTP 超时的整数值, 以毫秒计 。 默认为 `5000` 毫秒 |
| 启用远程 | `boolean` | 选择退出将库名称和版本通过 `Auth0-Client` 头曰. 默认为 `true`。 。 。 . |
| 使用软件 | `boolean` | 启用 DPoP( Posession 演示) , 以加强安全 。 启用后,客户端将生成DPop证书,用于表示请求和保护资源请求. 默认为 `false`。 。 。 . |
| dpopKeyPair (英语) | `DpopKeyPair` | ES256密钥对用于DPoP验证生成. 如果不提供, SDK 将试图从 `AUTH0_DPOP_PUBLIC_KEY` 财务报告和审定财务报表 `AUTH0_DPOP_PRIVATE_KEY` 环境变量。 密钥必须使用 PEM 格式 . |
| dpop 选项 | `DpopOptions` | 配置 DPop 计时验证 。 支助 `clockSkew` (只是假设当前时间)和 `clockTolerance` (验证容忍)。 也可以通过 `AUTH0_DPOP_CLOCK_SKEW` 财务报告和审定财务报表 `AUTH0_DPOP_CLOCK_TOLERANCE` 环境变量。 见 [DPop 时钟验证](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#dpop-clock-validation) 详细情况. |
| 诺斯 | `string` | CSP在弹出回调 HTML 回复中为内置脚本提供非ce. 提供时, `<script>` 外交部弹出召回的标签包括: `nonce="..."` 属性用于严格遵守内容安全政策。 仅在使用时需要 `mfa.challengeWithPopup()` 一个CSP,可以屏蔽内置脚本. |
| 发现缓存 | `DiscoveryCacheOptions` | 配置 OIDC 发现元数据缓存 [多个自定义域](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#discovery-cache-configuration)。控制 TTL 和最大缓存发行器. |

### 自定义 Auth 处理器

虽然认证路径由中间软件自动处理,但您仍然可以通过两种主要方法自定义认证流:

-   **在认证处理器前运行自定义代码**: 截取中间软件中的认证路由, 在认证动作前添加自定义逻辑
-   **认证后运行代码**: 使用 `onCallback` 认证完成后添加自定义逻辑的钩头

其他定制选项包括:

-   通过查询参数或静态配置登录参数
-   使用 `beforeSessionSaved` 钩子
-   使用查询参数登录重定向

> \[大 在自定义 auth 处理器时,总是验证用户输入(特别是重定向 URL),以防止安全漏洞,如打开重定向. 在可能的情况下使用相对的URL,并实施适当的输入消毒.

**快速启动**: 详细的例子和从v3逐步迁移的模式,见 [自定义 Auth 处理器](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#customizing-auth-handlers)。 。 。 .

## 会话 Cookie 配置

您可以指定以下环境变量来配置会话 cookie :

```env
AUTH0_COOKIE_DOMAIN=
AUTH0_COOKIE_PATH=
AUTH0_COOKIE_TRANSIENT=
AUTH0_COOKIE_SECURE=
AUTH0_COOKIE_SAME_SITE=
AUTH0_DPOP_PUBLIC_KEY=
AUTH0_DPOP_PRIVATE_KEY=
AUTH0_DPOP_CLOCK_SKEW=
AUTH0_DPOP_CLOCK_TOLERANCE=
```

### DPop 配置

Auth0 下一个.js SDK 支持 **DPoP( 证明 )** 用于加强OAuth 2.0安全。 DPoP将访问令牌绑定为密码密钥对,防止令牌被窃取并重放攻击.

#### 快速启动

**备选案文1:环境变量**

```env
# Enable DPoP and provide ES256 key pair
AUTH0_DPOP_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----"
AUTH0_DPOP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQ...
-----END PRIVATE KEY-----"
```

```ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client({
  useDPoP: true
  // Keys loaded automatically from environment variables
});
```

**备选案文2:程序配置**

```ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";
import { generateKeyPair } from "oauth4webapi";

const dpopKeyPair = await generateKeyPair("ES256");

export const auth0 = new Auth0Client({
  useDPoP: true,
  dpopKeyPair,
  dpopOptions: {
    clockTolerance: 30,  // Allow 30s clock difference
    retry: {
      delay: 100,        // 100ms retry delay
      jitter: true       // Add randomness
    }
  }
});
```

#### 编写 DPOP 保护请求

```ts
// Create a fetcher - DPoP inherited from global configuration
const fetcher = await auth0.createFetcher(req, {
  baseUrl: "https://api.example.com"
  // useDPoP is inherited from Auth0Client config
});

// Make authenticated requests with automatic DPoP proof generation
const response = await fetcher.fetchWithAuth("/protected-resource", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ data: "example" })
});
```

**DPoP 继承行为**

创建于 `createFetcher` 从您自动继承全局 DPOP 配置 `Auth0Client` 举个例子.

这种继承模式遵循与Auth0-spa-js相同的行为,为Auth0 SDKs提供一致的开发者经验.

DPoP的完整文件、实例和最佳做法见 [DPOP 实例](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#dpop-demonstrating-proof-of-possession)。 。 。 .

#### 高级: 时钟验证配置

为 DPop 证书配置时间验证, 以处理客户端和服务器之间的时钟差异 :

```ts
export const auth0 = new Auth0Client({
  useDPoP: true,
  dpopKeyPair: await generateKeyPair("ES256"),
  dpopOptions: {
    clockSkew: 120,      // Adjust for local clock being 2 minutes behind
    clockTolerance: 45   // Allow 45 seconds tolerance for validation
  }
});
```

或者通过环境变量配置 :

```env
AUTH0_DPOP_CLOCK_SKEW=300        # Clock adjustment in seconds
AUTH0_DPOP_CLOCK_TOLERANCE=90    # Tolerance in seconds
```

客户配置中也有相应的对应方。 见 [Cookie 配置](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#cookie-configuration) 更多细节.

### 我的账户和我的组织的 API 代理处理器

SDK为Auth0的"My Account"和"My Organization Management API"提供内置代理支持,允许安全浏览器启动请求,同时维护服务器侧DPoP认证和令牌管理.

#### 如何运作

代理处理器自动截取请求到 `/me/*` 财务报告和审定财务报表 `/my-org/*` 在 Next.js 应用程序中将路径转发给相应的 Auth0 API,并附有适当的认证头。 此执行后端的Frontend( BFF) 模式:

-   鼠标和 DPOP 密钥留在服务器上
-   访问符自动检索或刷新
-   为每个请求生成 DPop 证明
-   会话更新透明进行

#### 配置

配置 API 的受众和范围 :

```ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client({
  useDPoP: true,
  authorizationParameters: {
    audience: "urn:your-api-identifier",
    scope: {
      [`https://${process.env.AUTH0_DOMAIN}/me/`]: "profile:read profile:write",
      [`https://${process.env.AUTH0_DOMAIN}/my-org/`]: "org:read org:write"
    }
  }
});
```

#### 客户端用户端

通过代理路径提出请求 :

```tsx
// My Account API
const response = await fetch("/me/v1/profile", {
  headers: { "scope": "profile:read" }
});

// My Organization API
const response = await fetch("/my-org/organizations", {
  headers: { "scope": "org:read" }
});
```

这个 `scope` 页眉指定了所需的范围。 SDK检索到一个有适当受众和范围的访问符,然后用认证头转发请求.

完整的文档、示例和与UI组件的集成模式,参见 [我的账户和我的组织的 API 代理处理器](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#proxy-handler-for-my-account-and-my-organization-apis)。 。 。 .

## 基础路径

您的 Next.js 应用程序可能被配置为使用一个基础路径(例如: `/dashboard`)——这通常通过设置 `basePath` 选项 `next.config.js` 文档。 要配置 SDK 以使用基准路径, 您还需要设置 `NEXT_PUBLIC_BASE_PATH` 用于安装认证路径的环境变量.

例如,如果 `NEXT_PUBLIC_BASE_PATH` 环境变量设定为 `/dashboard`,SDK将挂载认证路径 `/dashboard/auth/login`, (中文(简体) ), `/dashboard/auth/callback`, (中文(简体) ), `/dashboard/auth/profile`等 (中文(简体) ).

> \[注\] 我们不建议使用 `NEXT_PUBLIC_BASE_PATH` 环境变量与 `APP_BASE_URL` 包含路径组件。 如果您的应用程序被配置为使用基准路径, 您应该设置 `APP_BASE_URL` 转到应用程序的根 URL(例如: `https://example.com`并使用 `NEXT_PUBLIC_BASE_PATH` 指定基础路径的环境变量(例如: `/dashboard`) (中文(简体) ).

## 配置验证

SDK 在初始化时对所需的配置选项进行验证 `Auth0Client`。下列选项是强制性的,必须通过构建器选项或环境变量提供:

-   `domain` (或 `AUTH0_DOMAIN` 环境变量)
-   `clientId` (或 `AUTH0_CLIENT_ID` 环境变量)
-   `secret` (或 `AUTH0_SECRET` 环境变量)
-   要么:
    -   `clientSecret` (或 `AUTH0_CLIENT_SECRET` 环境变量),OR
    -   `clientAssertionSigningKey` (或 `AUTH0_CLIENT_ASSERTION_SIGNING_KEY` 环境变量)

如果缺少其中任何需要的选项,SDK会发出警告并附上详细信息,解释缺少哪些选项以及如何提供.

`appBaseUrl` 是可选的;如果省略,SDK会在运行时从请求主机中推断出.

## 多个自定义域( MCD)

SDK支持用户针对同一租户上的多个Auth0自定义域进行认证. 传出 a `DomainResolver` 函数为 `domain` 选项以启用每个请求域解析 :

```ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client({
  domain: ({ headers }) => {
    const host = headers.get("host") ?? "";
    if (host.startsWith("brand1.")) return "auth.brand1.com";
    return "auth.default.com";
  }
});
```

完整的文档、配置选项和示例见 [EXAMPLES.md中的多自定义域](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#multiple-custom-domains-mcd)。 。 。 .

## 路线

SDK挂载路线如下:

1.  `/auth/login`: 用户将重新定向启动认证交易的登录路径
2.  `/auth/logout`: 必须添加到您的 Auth0 应用程序允许的日志 URL 的日志路径
3.  `/auth/callback`: 必须在 Auth0 应用程序允许的回调 URL 中添加的回调路由
4.  `/auth/profile`: 检查用户会话并返回其属性的路由
5.  `/auth/access-token`: 检查用户会话并返回访问令牌的路由( 如果有刷新令牌, 将自动刷新)
6.  `/auth/backchannel-logout`: 将接收到一个 `logout_token` 当配置的后通道日志启动器发生时
7.  `/auth/connect`: 连接额外账户到当前用户会话的路由
8.  `/auth/mfa/authenticators`: 列出当前用户注册的外交部认证器的路径
9.  `/auth/mfa/challenge`: 为特定验证人启动外交部质疑的路线
10.  `/auth/mfa/verify`: 核实外交部挑战反应和加快会议进度的路线
11.  `/auth/mfa/associate`: 为当前用户注册一个新的 MFA 认证符的路径
12.  `/auth/passwordless/start`: 发送 OTP 代码或魔法链接到用户的电子邮件或电话号码
13.  `/auth/passwordless/verify`: 核查检察官办公室代码并创建会话
14.  `/auth/passwordless/otp/challenge`:请检察官办公室提供数据库连接用户(电子邮件或电话)
15.  `/auth/passwordless/otp/token`: 交换 a `auth_session` + OTP 值和创建会话
16.  `/auth/passkey/register`: 为新用户注册获取 WebAuthn 证书创建挑战
17.  `/auth/passkey/challenge`: 为已有用户登录获取 WebAuthn 证书断言挑战
18.  `/auth/passkey/get-token`: 校验 WebAuthn 证书并创建会话

> \[注\] 无密码路线( E)`/auth/passwordless/start` 财务报告和审定财务报表 `/auth/passwordless/verify`(b) 支助 **电子邮件检察官办公室**, (中文(简体) ), **短消息检察官办公室**,以及 **魔法链接** 使用专用的无密码连接的流量。 对于魔法链接,用户点击电子邮件链接并被重定向到 `/auth/callback` ——不需要单独核查步骤. 魔法链接需要 `allow_magiclink_verify_without_session` 租户旗. 见 [无密码认证](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#passwordless-authentication) 在 EXAMPLES.md 中,用于完整的设置和使用细节.

> \[注\] 无密码的DBOTP路线(`/auth/passwordless/otp/challenge` 财务报告和审定财务报表 `/auth/passwordless/otp/token`与标准合作 **数据库连接** 配置为 `email_otp` 或者说 `phone_otp` ——非专用无密码连接. 使用 `passwordless.challengeWithEmail()`, (中文(简体) ), `passwordless.challengeWithPhoneNumber()`,以及 `passwordless.loginWithOtp()` 从 `@auth0/nextjs-auth0/client`。见 [数据库连接上的无密码检察官办公室](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#passwordless-otp-on-database-connections) 在 EXAMPLES.md 中,用于完整的设置和使用细节.

> \[注\] 密码路由执行 WebAuthn 仪式服务器侧. 使用 `passkey` 单吨从 `@auth0/nextjs-auth0/client` 完全一次性通知`passkey.signup()`, (中文(简体) ), `passkey.login()`),或者单独调用每条路线进行分步控制. 见 [指南/passkeys.md中的密码认证](https://github.com/auth0/nextjs-auth0/blob/main/guides/passkeys.md) 完整设置和使用细节.

> \[注\]  
> 这个 `/auth/access-token` 响应包括 `token`, (中文(简体) ), `expires_at` (纪元后秒), `expires_in` (TTL 秒),可选 `scope`选择 `token_type`如果您正在使用客户端助手 `getAccessToken()`,它默认只返回符号字符串;通过 `{ includeFullResponse: true }` 以获得完整的应答有效载荷.

> \[TIP\]  
> 您可以在访问符过期前稍稍刷新 `tokenRefreshBuffer` (秒数) `Auth0Client` 配置 .

> \[大  
> 这个 `/auth/access-token` 路由默认启用,但只有在客户端需要访问符时才有必要. 如果这不是你需要的东西,你可以通过设置来禁用这个终点 `enableAccessTokenEndpoint` 改为 `false`。 。 。 .

## 上游 IdP 的会话过期

对于企业连接,上游身份提供者可以限制用户的会话寿命. 当连接被配置以遵守时, Auth0 包含 a `session_expiry` 在 ID 符号 (通过 Post- Login 动作设置, 值必须是 Unix 秒) 中, SDK 在每次读取时执行此上限 。 一旦到达, `getSession()` 返回时 `null`, (中文(简体) ), `useUser()` 反映登录状态,以及 `getAccessToken()` 丢出一个 `AccessTokenError` 有代码 `session_expired`。如果上限在登录时已经存在,回调会立即拒绝。 假设一个会话在登录后总是存在的 Apps 应当添加无效检查并重定向回登录.

详情见 [上游 IdP 的会话过期](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md#session-expiry-from-the-upstream-idp) (原始内容存档于2017-09-29). in EXAMPLES.md.

## 实验中心

> \[注\] 实验中心通过SDKs的支持目前正在早期访问中. 要请求访问此功能, 请联系您的 Auth0 代表 .

[实验中心](https://auth0.com/docs/customize/experiment-center/overview) 允许您测试您的登录流量。 通过通过强制执行特定变体 `experiment_id` 财务报告和审定财务报表 `variation_id` 每个日志, 作为查询参数 `/auth/login` 或经由 `startInteractiveLogin`数字 :

```html
<a href="/auth/login?experiment_id=<EXPERIMENT_ID>&variation_id=<VARIATION_ID>">
  Log in
</a>
```

关于使用指导、分部定位和测试模式,见 [向导/实验中心实验中心](https://github.com/auth0/nextjs-auth0/blob/main/guides/experiment-center.md)。 。 。 .

## 反馈

### 捐款

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

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

### 提出问题

请提供反馈或报告错误 [提出我们的问题追踪器](https://github.com/auth0/nextjs-auth0/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/nextjs-auth0/blob/main/LICENSE) 需要更多信息的文件.

## 常见问题

### @auth0/nextjs-auth0 是什么？

下一个\.js SDK

### 如何安装 @auth0/nextjs-auth0？

在项目目录运行 npm install @auth0/nextjs-auth0，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（^14\.2\.35 \|\| ~15\.0\.7 \|\| ~15\.1\.11 \|\| ~15\.2\.8 \|\| ~15\.3\.8 \|\| ~15\.4\.10 \|\| ~15\.5\.9 \|\| ^16\.0\.10）、react（^18\.0\.0 \|\| ~19\.0\.1 \|\|  ~19\.1\.2 \|\| ^19\.2\.1）、react-dom（^18\.0\.0 \|\| ~19\.0\.1 \|\| ~19\.1\.2 \|\| ^19\.2\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @auth0/nextjs-auth0 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/auth0\_\_nextjs-auth0 是否存在。

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

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

### @auth0/nextjs-auth0 可以商用吗？

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

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

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

### @auth0/nextjs-auth0 还在维护吗？

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