# @ackplus/nest-auth-react 中文文档

规范地址：https://npmcn.com/package/%40ackplus/nest-auth-react/

版本：2\.18\.0
npm 元数据更新时间：2026-11-03T08:06:06.967Z
中文译文更新时间：2026-11-06T22:36:38.903Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：132 kB，89 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2025-11-22T07:37:58.561Z
- 最新版本发布：2026-11-03T08:06:06.786Z
- 近 30 天下载量：2244（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：118（近 12 个月 118 个）

## 中文简介

反应 SDK 用于 NestJS 认证 - 钩子, 守护和 Next.js 集成

## 安装

```sh
npm install @ackplus/nest-auth-react
```

也可以使用：`pnpm add @ackplus/nest-auth-react`、`yarn add @ackplus/nest-auth-react`、`bun add @ackplus/nest-auth-react`

## README

# @ackplus/nest-aut-反应

[![npm version](https://img.shields.io/npm/v/@ackplus/nest-auth-react.svg)](https://www.npmjs.com/package/@ackplus/nest-auth-react) [![npm downloads](https://img.shields.io/npm/dm/@ackplus/nest-auth-react.svg)](https://www.npmjs.com/package/@ackplus/nest-auth-react) [![license](https://img.shields.io/npm/l/@ackplus/nest-auth-react.svg)](https://www.npmjs.com/package/@ackplus/nest-auth-react)

反应提供者、钩子、卫士和头等舱Next.js App路由器帮助 [`@ackplus/nest-auth`](https://www.npmjs.com/package/@ackplus/nest-auth)无头——带来自己的UI.

> 📚 **完整文档: [ack-solutions.github.io/nst-auth/docs/resact 互联网档案馆的存檔,存档日期2013-12-02](https://ack-solutions.github.io/nest-auth/docs/react/)**

* * *

## 为什么用它

顶部的薄反射层 [`@ackplus/nest-auth-client`](https://www.npmjs.com/package/@ackplus/nest-auth-client) 这样你就能手动构建出一切: 上下文提供者, 狭义的重接接钩, 守护部件, 通过 Next.js Server 组件的路由级别守护, 以及跨塔布同步.

它无头——没有有风格的按钮,没有有观点的表格——所以它会掉入任何回放 18/19 app 或 Next.js App Router 项目,而不与你的设计系统相对抗.

## 安装

```bash
pnpm add @ackplus/nest-auth-react @ackplus/nest-auth-client
```

| 端点 | 版本数 |
| --- | --- |
| `react` | `^18.0.0 || ^19.0.0` |

## AI 编码代理

使用 Claude 代码, Codex, Cursor 或者另一个 AI 编码代理? 安装 Nest Auth 技能使其知道 SDK 的真实 API :

```bash
npx @ackplus/nest-auth-skill
```

它检测你的堆栈( 或通过) `--stack react`),并且只添加代理指令文件;您的应用程序不会被更改.

## 包括什么

| 表面 | API 密码 |
| --- | --- |
| **提供者** | `<AuthProvider>` · (委托人) `<NextAuthProvider>` (带有SSR初始状态水分) |
| **钩子** | `useNestAuth` • 妇女 `useUser` • 妇女 `useSession` • 妇女 `useAccessToken` • 妇女 `useAuthStatus` • 妇女 `useHasRole` • 妇女 `useHasPermission` |
| **警卫部分** | `<AuthGuard>` • 妇女 `<GuestGuard>` • 妇女 `<RequireRole>` • 妇女 `<RequirePermission>` |
| **人道主义协调员** | `withRequireRole` • 妇女 `withRequirePermission` (+ 数) `createRequireRoleHOC` 编号 : `createRequirePermissionHOC` 工厂) |
| **Next.js 帮助者** | `createNextAuthHelpers` 返回时 `{ getServerAuth, withAuth, createInitialState }` |
| **交叉调制同步** | `CrossTabSync` 编号 : `createCrossTabSync()` —— 说 `BroadcastChannel` 与 `localStorage` 倒计时 |

## 最小实例- SPA

```tsx
import { AuthClient } from '@ackplus/nest-auth-client';
import { AuthProvider, useNestAuth, AuthGuard, useUser } from '@ackplus/nest-auth-react';

const client = new AuthClient({ baseUrl: 'https://api.example.com' });

export default function App() {
  return (
    <AuthProvider client={client}>
      <Routes />
    </AuthProvider>
  );
}

function Dashboard() {
  return (
    <AuthGuard fallback={<a href="/login">Sign in</a>}>
      <DashboardInner />
    </AuthGuard>
  );
}

function DashboardInner() {
  const user = useUser();
  return <h1>Hello {user?.email}</h1>;
}

function LoginForm() {
  const { login, error, isLoading } = useNestAuth();
  return (
    <form onSubmit={async (e) => {
      e.preventDefault();
      await login({ credentials: { email, password } });
    }}>
      {/* … */}
      <button disabled={isLoading}>Sign in</button>
      {error && <p>{error.message}</p>}
    </form>
  );
}
```

## 最小示例 — Next.js App 路由器

```tsx
// app/layout.tsx (Server Component)
import { cookies } from 'next/headers';
import { NextAuthProvider } from '@ackplus/nest-auth-react';
import { client, authHelpers } from '@/lib/auth';

export default async function RootLayout({ children }) {
  const initialState = await authHelpers.getServerAuth(await cookies());

  return (
    <html lang="en">
      <body>
        <NextAuthProvider client={client} initialState={initialState}>
          {children}
        </NextAuthProvider>
      </body>
    </html>
  );
}
```

```ts
// app/api/private/route.ts
import { authHelpers } from '@/lib/auth';

export const GET = authHelpers.withAuth(async (req) => {
  return Response.json({ user: req.auth.user });
});
```

[Full Next.js 向导 —](https://ack-solutions.github.io/nest-auth/docs/react/nextjs/)

## 角色标识权限( L)

```tsx
import { RequireRole, RequirePermission, useHasRole } from '@ackplus/nest-auth-react';

<RequireRole role="admin" fallback={<NotAuthorized />}>
  <AdminPanel />
</RequireRole>

<RequirePermission permission={['orders.read', 'orders.write']} matchAll>
  <OrderEditor />
</RequirePermission>

// Or via hook
const isAdmin = useHasRole('admin');
```

## 文档

| 节次 | 这是什么 |
| --- | --- |
| [提供者](https://ack-solutions.github.io/nest-auth/docs/react/provider/) | `<AuthProvider>`, (中文(简体) ), `<NextAuthProvider>`,所有道具 |
| [钩子](https://ack-solutions.github.io/nest-auth/docs/react/hooks/) | 每个钩子都有回回形和回回音 |
| [警卫](https://ack-solutions.github.io/nest-auth/docs/react/guards/) | 部件+HOCs+工厂 |
| [下一个.js](https://ack-solutions.github.io/nest-auth/docs/react/nextjs/) | App 路由器 SSR 模式, `withAuth`中间软件重定向 |
| [跨标签同步](https://ack-solutions.github.io/nest-auth/docs/react/cross-tab-sync/) | 多塔布登录/日志传播 |
| [快速启动——反应](https://ack-solutions.github.io/nest-auth/docs/getting-started/quickstart-react/) | SPA 设置到结束 |
| [快速启动 — Next.js](https://ack-solutions.github.io/nest-auth/docs/getting-started/quickstart-nextjs/) | App 路由器设置到结束 |

## 配套软件包

| 软件包 | 使用时间 |
| --- | --- |
| [`@ackplus/nest-auth`](https://www.npmjs.com/package/@ackplus/nest-auth) | NestJS 后端模块 此客户端向 |
| [`@ackplus/nest-auth-client`](https://www.npmjs.com/package/@ackplus/nest-auth-client) | 香草JS客户端 这个包裹包裹 |
| [`@ackplus/nest-auth-contracts`](https://www.npmjs.com/package/@ackplus/nest-auth-contracts) | 共享的 TS 类型( 已经是一个中转分解) |

所有4个包都与同版本号一起放出. 把它们绑在同一个版本.

## 链接

-   📚 [文档](https://ack-solutions.github.io/nest-auth/)
-   💬 [问题跟踪器](https://github.com/ack-solutions/nest-auth/issues)
-   📦 [GitHub 仓库](https://github.com/ack-solutions/nest-auth)

## 许可证

[麻省理工学院](https://github.com/ack-solutions/nest-auth/blob/main/LICENSE)

## 常见问题

### @ackplus/nest-auth-react 是什么？

反应 SDK 用于 NestJS 认证 - 钩子, 守护和 Next\.js 集成

### 如何安装 @ackplus/nest-auth-react？

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

### @ackplus/nest-auth-react 支持 TypeScript 吗？

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

### @ackplus/nest-auth-react 支持 ESM 还是 CommonJS？

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

### @ackplus/nest-auth-react 可以商用吗？

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

### @ackplus/nest-auth-react 的下载量有多少？

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

### @ackplus/nest-auth-react 还在维护吗？

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