# @auth0/auth0-nuxt 中文文档

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

版本：1\.3\.0
npm 元数据更新时间：2026-10-28T06:47:39.286Z
中文译文更新时间：2026-11-07T05:57:16.054Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：397 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-10-16T12:03:49.804Z
- 最新版本发布：2026-10-28T06:47:38.879Z
- 近 30 天下载量：10809（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 6 个）

## 中文简介

在 JavaScript 运行时间为 Nuxt 应用程序认证 SDK

## 安装

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

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

## README

![Auth0-Nuxt](https://npmcn.com/package/%40auth0/auth0-nuxt/assets/images/banner.png)

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

![Stage: GA Release](https://img.shields.io/badge/stage-ga-brightgreen) ![Release](https://img.shields.io/npm/v/@auth0/auth0-nuxt) ![Downloads](https://img.shields.io/npm/dw/@auth0/auth0-nuxt) [![License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT)

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

## 文档

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

## 开始

### 1\. 安装SDK

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

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

### 2\. 登记 Auth0 努克特模块

Auth0 Nuxt 模块在 `nuxt.config.js` 文件,连同运行时配置.

```js
{
  modules: ['@auth0/auth0-nuxt'],
  runtimeConfig: {
    auth0: {
      domain: '<AUTH0_DOMAIN>', // is overridden by NUXT_AUTH0_DOMAIN environment variable
      clientId: '<AUTH0_CLIENT_ID>', // is overridden by NUXT_AUTH0_CLIENT_ID environment variable
      clientSecret: '<AUTH0_CLIENT_SECRET>', // is overridden by NUXT_AUTH0_CLIENT_SECRET environment variable
      sessionSecret: '<SESSION_SECRET>', // is overridden by NUXT_AUTH0_SESSION_SECRET environment variable
      appBaseUrl: '<APP_BASE_URL>', // is overridden by NUXT_AUTH0_APP_BASE_URL environment variable
    },
  },
}
```

这个 `AUTH0_DOMAIN`, (中文(简体) ), `AUTH0_CLIENT_ID`,以及 `AUTH0_CLIENT_SECRET` 可以在创建应用程序后从 Auth0 Dashboard 获得. 此应用程序必须是常规 Web 应用程序 .

这个 `SESSION_SECRET` 是用于加密会话 cookie 的密钥。 您可以使用 opensl 生成一个秘密 :

```bash
openssl rand -hex 64
```

这个 `APP_BASE_URL` 您的应用程序正在运行的 URL 。 当本地开发时,这最常见的是http://localhost:30.

> \[大  
> 您需要在 Auth0 应用程序中通过 [Auth0 剪贴板](https://manage.auth0.com/)数字 :
> 
> -   添加 `http://localhost:3000/auth/callback` 名单 **允许召回 URL**
> -   添加 `http://localhost:3000` 名单 **允许登录 URL**

#### 路线

Nuxt Web 应用程序的 SDK 挂载了 5 主要路线 :

1.  `/auth/login`: 用户将被重定向启动认证交易的登录路径. 支持添加一个 `returnTo` 登录后返回特定 URL 的查询字符串参数 .
2.  `/auth/logout`: 必须添加到您的 Auth0 应用程序允许的日志 URL 的日志路径
3.  `/auth/callback`: 必须在 Auth0 应用程序允许的回调 URL 中添加的回调路由
4.  `/auth/backchannel-logout`: 将接收到一个 `logout_token` 配置时 [后通道登录](https://auth0.com/docs/authenticate/login/logout/back-channel-logout) 启动发生
5.  `/auth/profile`: 返回当前用户对浏览器的要求, 已服务 `Cache-Control: no-store`。这就是流行 `useUser()` 选择退出 SSR 用户写入的路由(参见 [第5节](https://npmcn.com/package/%40auth0/auth0-nuxt/#readme-5-controlling-the-ssr-user-write)) (中文(简体) ).

要禁用此行为, 您可以设置 `mountRoutes` 选项到 `false` 当注册模块时( 默认为真实) :

```ts
modules: [['@auth0/auth0-nuxt', { mountRoutes: false }]]
```

或者,如果想要更改用于挂起的端点路径,可以指定 `routes` 选项 :

```ts
modules: [['@auth0/auth0-nuxt', { 
  routes: { 
    login: '/custom-auth/login',
    logout: '/custom-auth/logout',
    callback: '/custom-auth/callback',
    backchannelLogout: '/custom-auth/backchannel-logout',
    profile: '/custom-auth/profile',
  }
}]]
```

### 3\. 添加登录和停用

当使用内置挂载路由时,用户可以被重定向到 `/auth/login` 启动登录流程,并 `/auth/logout` 以登录.

```html
<a href="/auth/logout">Log out</a>
<a href="/auth/login">Log in</a>
```

需要的时候,也可以通过 `returnTo` 查询字符串参数到登录路径,以便在登录成功后将用户重定向到特定的URL.

在不使用内置路线时,您要给SDK打电话 `startInteractiveLogin()`, (中文(简体) ), `completeInteractiveLogin()` 财务报告和审定财务报表 `logout()` 方法通过 `useAuth0()` 可编译, 可在您的 Nuxt 应用程序的服务器侧上下文中获取 :

```ts
// server/routes/auth/login.js
export default defineEventHandler(async (event) => {
  const auth0Client = useAuth0(event);
  const authorizationUrl = await auth0Client.startInteractiveLogin(
    {
      authorizationParams: {
        // Custom URL to redirect back to after login to handle the callback.
        // Make sure to configure the URL in the Auth0 Dashboard as an Allowed Callback URL.
        redirect_uri: 'http://localhost:3000/auth/callback',
      }
    }
  );

  sendRedirect(event, authorizationUrl.href);
});

// server/routes/auth/callback.js
export default defineEventHandler(async (event) => {
  const auth0Client = useAuth0(event);
  await auth0Client.completeInteractiveLogin(
    new URL(event.node.req.url as string, 'http://localhost:3000')
  );

  sendRedirect(event, 'https://localhost:3000');
});

// server/routes/auth/logout.js
export default defineEventHandler(async (event) => {
  const auth0Client = useAuth0(event);
  const returnTo = 'https://localhost:3000';
  const logoutUrl = await auth0Client.logout(
    { returnTo: returnTo.toString() }
  );

  sendRedirect(event, logoutUrl.href);
});
```

有了这些,你可以打电话 `auth/login` 财务报告和审定财务报表 `auth/logout` 以登录应用程序中的用户.

### 4\. 保护路线

#### 4.1 路由中软件

为了保护Nuxt路线,你可以使用SDK的 `useUser()` 自定义路由中间软件中的可相容方法. 这将检查是否有用户, 如果没有, 则将其重定向到登录页面 :

```ts
// middleware/auth.ts
import { useUser } from '@auth0/auth0-nuxt';

export default defineNuxtRouteMiddleware((to, from) => {
  const session = useUser();

  if (!session.value) {
    return navigateTo(`/auth/login?returnTo=${to.path}`);
  }
});
```

> \[入声\]  
> 您可以用任何您想要的检查来替换上面的检查, 例如检查特定的用户请求 .

有了中间的软件,你可以保护路线 通过添加到 `middleware` 相应的 Nuxt 路由的属性 :

```html
<script setup>
definePageMeta({
  middleware: [ 'auth' ],
});
</script>
```

#### 4.2 服务器中间软件

此外,您还可以使用服务器中间软件,通过使用该软件来保护服务器端已渲染的路由 `useAuth0` 服务器侧可堆放 。 此中间软件将检查用户是否被认证, 如果不是, 则将其重定向到登录页面 :

```ts
// server/middleware/auth.ts
export default defineEventHandler(async (event) => {
  const url = getRequestURL(event);

  if (url.pathname === '/private') {
    const auth0Client = useAuth0(event);
    const session = await auth0Client.getSession();
    if (!session) {
      return sendRedirect(event, `/auth/login?returnTo=${url.pathname}`);
    }
  }
});
```

> \[大  
> 上述例子既是为了通过会话保护路线,也不是为了使用无记名标志的API路线.

### 5\. 控制安全部门改革用户的写作

`useUser()` 由 `useState`,将 Nuxt 序列化为 `__NUXT__` 服务器上 HTML 的有效载荷 。 如果从共享缓存中提供HTML,则可以将一个访客的债权交付给另一个.

**此 SDK 无法检测您的响应是如何被缓存的 .** `Cache-Control` 按请求时间设置 `setHeader`并按你的CDN进行缓存, `Netlify-CDN-Cache-Control`)是两者都看不见的. 如果你从共享缓存中提供认证的路径,你必须自己选择这些路径. **默认是 `ssrUser: true`,所以一个缓存的认证路径没有 `ssrUser: false` 规则泄露.** 默认是 `true` 保持不破烂.

按路线规则选择出线 :

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/blog/**': { swr: 3600, auth0: { ssrUser: false } },
  },
});
```

或设定每条路由的默认值,并选择单个路由返回:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  auth0: { ssrUser: false },
  routeRules: {
    '/account': { auth0: { ssrUser: true } },
  },
});
```

一个路由规则总是胜过模块选项,它胜过内置默认 `true`。选择退出的路由使 HTML 和水合物匿名 `useUser()` 在浏览器中从 `/auth/profile`,则服务 `Cache-Control: no-store`。 。 。 .

> \[大 **不保护选择的退出路径 `useUser()` 路由中间软件 [第4.1节](https://npmcn.com/package/%40auth0/auth0-nuxt/#readme-41-route-middleware)。 。 。 .** 在选择的退出路径中, SSR 期间故意没有用户, 所以中间软件可以看到 `session.value` 即使是对登录用户来说也是空的,并重定向到 `/auth/login`. Auth0 然后将它们返回到同一个路径,这再次使得匿名——无限重定向回路.
> 
> 用服务器中间软件保护这些路由 [第4.2节](https://npmcn.com/package/%40auth0/auth0-nuxt/#readme-42-server-middleware) 换句话说 它从H3活动中读取会议内容,而H3活动没有受到影响 `ssrUser`区别在于: `ssrUser: false` 删除用户从 _生成的有效载荷_,不是从会议.

Nuxt 不将模块的类型拉入您的 `nuxt.config`类型程序,用于自动完成 `auth0` 路由规则键,将此添加到 `.d.ts` 在您的项目中 :

```ts
declare module 'nitropack' {
  interface NitroRouteConfig {
    auth0?: { ssrUser?: boolean };
  }
}

declare module 'nitropack/types' {
  interface NitroRouteConfig {
    auth0?: { ssrUser?: boolean };
  }
}

export {};
```

该规则在运行时读取,无论是否键入.

客户端水合一次运行在app init上,而不是在每个导航上:SSR写给用户的插件是"无"(no-op;没有),被获取的用户会携带过后期导航. 这么说吧 `ssrUser: false` 控制缓存的 HTML 中哪些区域,而不是用户在运行中的应用程序中是否可见.

`mountRoutes: false` 不停止此请求: 客户端仍然获取配置路径, 而模块没有在此获取答案 。 自动挂载配置文件处理器, 或任何答题( a 404 或 call- all- page 的 HTML ) 都无要求, 插件忽略了它, 选择的退出路由保持匿名 。 完全不提出要求,设置 `hydrateUser: false`。 。 。 .

> \[尖叫声\] 如果您按自己的路径挂载,请为这条路径添加一条规则:
> 
> ```ts
> routeRules: { '/your/profile/path': { cache: false } }
> ```
> 
> Nitro的处理器缓存由没有会话 cookie 的路径按键,所以像通配符 `'/**': { swr: 60 }` 将满足一个用户对下一个用户的要求。 SDK已经为自己的配置路径设置了此功能.

### 6\. 请求调取一个调取API

如果您需要代表用户调用 API, 请指定 `audience` 参数用于注册插件。 这将使SDK在用户登录时为指定的受众请求访问令牌.

```ts
runtimeConfig: {
  auth0: {
    domain: '<AUTH0_DOMAIN>', // is overridden by NUXT_AUTH0_DOMAIN environment variable
    clientId: '<AUTH0_CLIENT_ID>', // is overridden by NUXT_AUTH0_CLIENT_ID environment variable
    clientSecret: '<AUTH0_CLIENT_SECRET>', // is overridden by NUXT_AUTH0_CLIENT_SECRET environment variable
    sessionSecret: '<SESSION_SECRET>', // is overridden by NUXT_AUTH0_SESSION_SECRET environment variable
    appBaseUrl: '<APP_BASE_URL>', // is overridden by NUXT_AUTH0_APP_BASE_URL environment variable
    audience: '<AUTH0_AUDIENCE>', // is overridden by NUXT_AUTH0_AUDIENCE environment variable
  },
}
```

这个 `AUTH0_AUDIENCE` 是您要调用的 API 的标识符。 您可以在 Auth0 仪表板的 API 部分中找到这个 .

通过使用 `getAccessToken` 使用服务器侧可替换 `useAuth0`数字 :

```ts
const auth0Client = useAuth0(event);
const accessTokenResult = await auth0Client.getAccessToken();
// You can now use `accessTokenResult.accessToken`
```

### 7\. 钥匙

用户可以注册并登录密码(指纹,面部扫描或安全密钥)而不是密码,签注可以先用一次性代码验证电子邮件地址和电话号码. 模块没有为此挂起路径 。 您添加了三条呼叫的服务器路由 `useAuth0(event).passkey`因此,你自己的验证, 费率限制和机器人检查坐在他们面前:

```ts
const auth0 = useAuth0(event);

// 1. Start. Return `authnParamsPublicKey` to the browser, which runs `navigator.credentials.create()` or `.get()`.
const { authnParamsPublicKey, verificationRequired } = await auth0.passkey.startSignup({ email, realm });
// or, for a login: const { authnParamsPublicKey } = await auth0.passkey.startLogin({ realm });

// 2. Complete. The browser sends the credential (and the one-time codes) back: the SDK exchanges it for tokens and
//    writes the session.
await auth0.passkey.complete({ credential, verification });
```

密码 [自定义域](https://auth0.com/docs/customize/custom-domains),该应用程序使用客户端保密方法与 **密码** grant),以及与Passkey认证方法的数据库连接. 见 [使用密码登录和签名](https://github.com/auth0/auth0-nuxt/blob/main/packages/auth0-nuxt/EXAMPLES.md#login-and-signup-using-passkeys) 路线、处理错误和如何保护这些路线,以及 [密码例应用](https://github.com/auth0/auth0-nuxt/tree/main/examples/example-nuxt-passkeys) 用于运行整个流量的一页.

## 反馈

### 捐款

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

-   [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)

### 提出问题

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

## 常见问题

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

在 JavaScript 运行时间为 Nuxt 应用程序认证 SDK

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

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

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

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

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

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

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

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

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

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

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

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