# @alpha018/nestjs-firebase-auth 中文文档

规范地址：https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/

版本：4\.0\.0
npm 元数据更新时间：2026-10-24T02:45:58.479Z
中文译文更新时间：2026-11-07T04:15:45.294Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：275 kB，74 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：7 个
- 首次发布：2024-09-03T06:03:20.545Z
- 最新版本发布：2026-10-24T02:45:58.098Z
- 近 30 天下载量：2053（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 9 个）

## 中文简介

网点JS Firebase 库和基于角色的守护器,用于具有一些实用功能的认证

## 安装

```sh
npm install @alpha018/nestjs-firebase-auth
```

也可以使用：`pnpm add @alpha018/nestjs-firebase-auth`、`yarn add @alpha018/nestjs-firebase-auth`、`bun add @alpha018/nestjs-firebase-auth`

## README

# NestJS 消防基地管理局

[![Nest Logo](https://docs.nestjs.com/assets/logo_text.svg)](https://nestjs.com/)

### NestJS 使用Firebase admin SDK的Firebase Auth护照策略,其中包括用于使用的Firebase SDK库.

**[请检查wiki的完整文档和指南!](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/docs/wiki/Home.md)**

 [![Built with NestJS](https://img.shields.io/badge/built%20with-NestJs-red.svg)](https://nestjs.com/)[![Test Status](https://github.com/Alpha018/nestjs-firebase-auth/actions/workflows/test.yml/badge.svg) ](https://github.com/Alpha018/nestjs-firebase-auth/actions)[![GitHub stars](https://img.shields.io/github/stars/Alpha018/nestjs-firebase-auth?style=social)](https://github.com/Alpha018/nestjs-firebase-auth)

## 目录

-   [安装](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-installation)
-   [使用量](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-usage)
    -   [导入模块](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-import-the-module)
    -   [参数选项](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-parameter-options)
    -   [Auth 守护无作用验证](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-auth-guard-without-role-validation)
    -   [Auth 守护与角色验证](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-auth-guard-with-role-validation)
    -   [基于索赔的授权(良好)](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-claim-based-authorization-fine-grained)
    -   [具有方法级授权的主计长级认证](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-controller-level-authentication-with-method-level-authorization)
    -   [补充资料](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-additional-information)
-   [移徙指南(v2.0.0)](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-migration-guide-v200)
-   [移徙指南(v1.9.x)](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-migration-guide-v19x)
-   [文档](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-documentation)
-   [资源](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-resources)
-   [保持联系](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-stay-in-touch)
-   [许可证](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-license)

> **v2.0.0中的突破变化:** 现在需要的最小节点.js版本 **22.12 对**,则 捆绑的消防基地管理员SDK已移至 **页:1**见 [v 2.0.0 移徙指南](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/#readme-migration-guide-v200) 升级前.

## 安装

```bash
npm i @alpha018/nestjs-firebase-auth firebase-admin
```

## 使用量

### 导入模块

要在应用程序中使用 Firebase 认证,请将模块导入您的主模块 .

```ts
import { FirebaseAdminModule } from '@alpha018/nestjs-firebase-auth';

@Module({
  imports: [
    ...
      FirebaseAdminModule.forRootAsync({
        imports: [ConfigModule],
        useFactory: (configService: ConfigService) => ({
          // SELECT ONLY ONE: BASE64 OR OPTIONS (Firebase Options)!
          base64: configService.get('FIREBASE_SERVICE_ACCOUNT_BASE64'), // Base64 encoded service account JSON string
          options: {}, // Use this if not using base64
          auth: {
            config: {
              extractor: ExtractJwt.fromAuthHeaderAsBearerToken(), // Choose your extractor from the Passport library
              checkRevoked: true, // Set to true if you want to check for revoked Firebase tokens
              validateRole: true, // Set to true if you want to validate user roles
              useLocalDecode: true, // Set to true to resolve roles and claims locally from the token, without a Firebase call
              rolesClaimKey: 'user_roles' // Set the name of the key within the Firebase custom claims that stores user roles
            },
          },
        }),
        inject: [ConfigService],
      }),
    ...
  ],
})
```

## 参数选项

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `base64` | `string` | 对\* | Base64编码服务账户JSON字符串. 需要时,如果 `options` 未提供. |
| `options` | `object` | 对\* | Firebase Admin SDK 配置选项. 需要时,如果 `base64` 未提供. |
| `auth.config.extractor` | `function` | 可选 | 护照库中的自定义提取器功能,用于从请求中提取令牌. |
| `auth.config.checkRevoked` | `boolean` | 可选 | 设定为 `true` 以检查Firebase标志是否已被撤销。 默认为 `false`。 。 。 . |
| `auth.config.validateRole` | `boolean` | 可选 | 设定为 `true` 使用 Firebase 自定义要求验证用户角色。 默认为 `false`。 。 。 . |
| `auth.config.useLocalDecode` | `boolean` | 可选 | 设定为 `true` 以已经从 JWT 符号解码的值验证角色和索赔,而不是从 Firebase 取出。 默认为 `false`。 。 。 . **说明:** 更新债权时,以前发行的令牌可能仍然含有过时的值并仍然有效. |
| `auth.config.useLocalRoles` | `boolean` | 可选 | 设定为 `true` 在 JWT 标志内使用本地自定义要求验证用户角色。 默认为 `false`。 。 。 . **说明:** 更新索赔要求时,以前发行的代币可能仍然包含过时的角色并仍然有效. (折旧、使用) `useLocalDecode`(中文(简体) ) |
| `auth.config.rolesClaimKey` | `string` | 可选 | Firebase自定义中的密钥名称声称存储了用户角色. 默认为 `'roles'`。这使得您可以自定义自定义对象中的角色属性名称. |
| `auth.config.claimsClaimKey` | `string` | 可选 | Firebase自定义中的密钥名称声称存储有精细纹饰的索赔. 默认为 `'permissions'`。 。 。 . **说明:** Firebase 封顶所有自定义索赔的合并大小, 序列化后为 ~ 1 000 字节, 共享 `rolesClaimKey`, (中文(简体) ), `claimsClaimKey`还有其他东西存放在那里。 由于许多索赔涉及多个领域,因此使用简短的索赔代码而不是冗长的描述性字符串来保留在该预算之下. |

### Auth 守护无作用验证

为了在不验证用户角色的情况下保护一个端点,使用Auth Guard来确保Firebase用户的令牌是有效的.

```ts
import { Auth, FirebaseProvider } from '@alpha018/nestjs-firebase-auth';

export class AppController {
  constructor(
    private readonly firebaseProvider: FirebaseProvider,
  ) {}

  @Auth() // This line protects your endpoint with Firebase Auth
  @Get()
  mainFunction() {
    return 'Hello World';
  }
}
```

### Auth 守护与角色验证

为了执行基于角色的访问控制,需要在Firebase设置基于角色的自定义索赔. 以下是您如何为用户设定角色 `setClaimsRoleBase`数字 :

```ts
import { FirebaseProvider } from '@alpha018/nestjs-firebase-auth';

enum Roles {
  ADMIN,
  USER,
}

@Controller('')
export class AppController {
  constructor(
    private readonly firebaseProvider: FirebaseProvider,
  ) {}

  @Get()
  async setUserRoles() {
    await this.firebaseProvider.setClaimsRoleBase<Roles>(
      'some-firebase-uid', // The UID of the user you want to set roles for
      [Roles.ADMIN]
    );
    return { status: 'ok' }
  }
}
```

然后,使用带有角色验证的Auth Guard来检查用户是否有访问端点的必要权限:

```ts
import { Roles } from '@alpha018/nestjs-firebase-auth';
enum Roles {
  ADMIN,
  USER,
}

@Controller('')
export class AppController {
  constructor(
    private readonly firebaseProvider: FirebaseProvider,
  ) {}

  @Roles(Roles.ADMIN, Roles.USER) // This line checks the custom claims of the Firebase user AND ensures the user is authenticated (implicitly applies FirebaseGuard)
  @Get()
  mainFunction() {
    return 'Hello World';
  }
}
```

### 基于索赔的授权(良好)

`@RequireClaims` 检查访问比角色更细:用户必须持有 **每个** 所列索赔,没有 只有一个 它读取一个单独的自定义要求密钥( :`permissions` 默认情况下,可通过 `claimsClaimKey`) (中文(简体) ).

```ts
import { FirebaseProvider } from '@alpha018/nestjs-firebase-auth';

enum UsersClaim {
  READ = 'users:read',
  WRITE = 'users:write',
}

@Controller('')
export class AppController {
  constructor(
    private readonly firebaseProvider: FirebaseProvider,
  ) {}

  @Get()
  async setUserClaims() {
    await this.firebaseProvider.setClaimsPermissionBase<UsersClaim>(
      'some-firebase-uid', // The UID of the user you want to set claims for
      [UsersClaim.READ, UsersClaim.WRITE],
    );
    return { status: 'ok' }
  }
}
```

然后,使用 `@RequireClaims` 以检查用户是否持有访问端点所需的所有要求:

```ts
import { RequireClaims } from '@alpha018/nestjs-firebase-auth';

enum UsersClaim {
  READ = 'users:read',
  WRITE = 'users:write',
}

@Controller('')
export class AppController {
  @RequireClaims(UsersClaim.READ, UsersClaim.WRITE) // Requires BOTH claims AND ensures the user is authenticated (implicitly applies FirebaseGuard)
  @Get()
  mainFunction() {
    return 'Hello World';
  }
}
```

`@RequireClaims` 属于一般性质,因此来自不同领域的债权(`UsersClaim`, (中文(简体) ), `InvoicesClaim`, (中文(简体) ), `ReportsClaim`,.)可以共存,作为普通字符串在同一自定义请求数组中. 也结合了 在单一路线上发挥作用和制定政策 `@Auth({ roles, claims, policies })`。 。 。 .

### 具有方法级授权的主计长级认证

您可以使用 `@Auth()` ,然后使用 `@Roles()`。该库被优化,以防止在此情况下进行冗余符号验证.

```ts
import { Auth, Roles } from '@alpha018/nestjs-firebase-auth';

enum AppRoles {
  ADMIN,
  USER,
}

@Auth() // Protects all routes in this controller (ensures valid token)
@Controller('users')
export class UsersController {
  
  @Get('profile')
  getProfile() {
    // Accessible by any authenticated user
    return { status: 'ok' };
  }

  @Roles(AppRoles.ADMIN) // Adds specific authorization requirement
  @Get('admin-dashboard')
  getAdminDashboard() {
    // Accessible ONLY by authenticated users with ADMIN role
    return { status: 'secure' };
  }
}
```

### 补充资料

要在受保护的路由中检索已解码的ID Token和角色要求,请使用 `@FirebaseUser` 财务报告和审定财务报表 `@FirebaseRolesClaims` 参数装饰.

```ts
import {
  FirebaseProvider,
  FirebaseUser,
  FirebaseRolesClaims,
  Roles,
} from '@alpha018/nestjs-firebase-auth';

import { DecodedIdToken } from 'firebase-admin/auth';

enum Roles {
  ADMIN,
  USER,
}

@Controller('')
export class AppController {
  constructor(
    private readonly firebaseProvider: FirebaseProvider,
  ) {}

  @Roles(Roles.ADMIN, Roles.USER)
  @Get()
  async mainFunction(
    @FirebaseUser() user: DecodedIdToken,
    @FirebaseRolesClaims() claims: Roles[],
  ) {
    return {
      user,
      claims
    };
  }
}
```

#### 差异 `@FirebaseUser` 财务报告和审定财务报表 `@FirebaseRolesClaims`

> **说明:** 从版本开始 `>=1.7.x`,这两个装饰器明确分开,以避免混淆(见 [问题11](https://github.com/Alpha018/nestjs-firebase-auth/issues/11):

-   `@FirebaseUser()` • 返回 **已完全解码的令牌** (单位:千美元)`DecodedIdToken`) (中文(简体) ).
-   `@FirebaseRolesClaims()` - 仅返回 **自定义角色索赔** (作用/许可)为用户定义.

这种分离确保了开发者既可以独立访问原始的Firebase用户对象,也可以独立访问角色/要求信息.

## 移徙指南(v2.0.0)

`v2.0.0` 将捆绑的 Firebase 管理器 SDK 从 v13 升级到 **页:1**。这个图书馆的 API 是 不变; 断开变化来自 SDK :

| 变动 | 需要采取的行动 |
| --- | --- |
| 最小节点Js现在 `22.12` | 更新运行时间——节点20是寿命结束 |
| `auth` 名称空格从 `firebase-admin` 根号 | 导入 `DecodedIdToken` 从 `firebase-admin/auth` |

**包括杰斯特配置在内的全部细节都在 [移徙指南](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/docs/wiki/guides/Migrations.md)。 。 。 .**

## 移徙指南(v1.9.x)

为了提高语义上的清晰度和开发者的经验,对警卫的直接使用被贬低,更倾向于描述性的装饰. 截止 `v3.0.0`, (中文(简体) ), `RolesGuard` 与公众 `FirebaseGuard` 已完全去除出口——见 [移徙指南](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/docs/wiki/guides/Migrations.md#removal-of-deprecated-guards-and-decorators)。 。 。 .

### 1\. 替换 `RolesGuard` 与 `@Roles`

**在 v3. 0.0 中被删除 :**

```ts
@UseGuards(FirebaseGuard) // or alone if global
@RolesGuard(Roles.ADMIN)
```

**新途径 :**

```ts
@Roles(Roles.ADMIN)
```

_说明: `@Roles` 自动应用认证守护._

* * *

### 2\. 替换 `UseGuards(FirebaseGuard)` 与 `@Auth`

**在 v3. 0.0 中被删除 :**

```ts
@UseGuards(FirebaseGuard)
```

**新途径 :**

```ts
@Auth()
```

* * *

### 为什么移民?

-   **更好的可读性**数字 : `@Auth` 对 `@UseGuards(FirebaseGuard)` 明确表明意图.
-   **最佳业绩**: 新的装饰器使用一个最优化的后卫来防止在编组控制器和方法时进行冗余的符号验证检查.

## 文档

欲了解更详细的情况、指南和先进实例,请访问 [工程维基](https://npmcn.com/package/%40alpha018/nestjs-firebase-auth/docs/wiki/Home.md)。 。 。 .

## 资源

请检查date=中的日期值 (帮助) NestJS工作时可能有用的资源:

-   访问 [NestJS 文档](https://docs.nestjs.com/) 了解更多的框架.
-   可视化您的应用图并实时与 NestJS 应用交互 [NestJS Devtools (英语)](https://devtools.nestjs.com/)。 。 。 .

## 保持联系

-   作者 - 翻译 [托马斯·阿雷格里](https://github.com/Alpha018)

## 许可证

巢为 [麻省理工学院执照](https://github.com/nestjs/nest/blob/master/LICENSE)。 。 。 .

## 常见问题

### @alpha018/nestjs-firebase-auth 是什么？

网点JS Firebase 库和基于角色的守护器,用于具有一些实用功能的认证

### 如何安装 @alpha018/nestjs-firebase-auth？

在项目目录运行 npm install @alpha018/nestjs-firebase-auth，或使用 pnpm add / yarn add / bun add。

### @alpha018/nestjs-firebase-auth 支持 TypeScript 吗？

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

### @alpha018/nestjs-firebase-auth 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @alpha018/nestjs-firebase-auth 需要什么版本的 Node\.js？

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

### @alpha018/nestjs-firebase-auth 可以商用吗？

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

### @alpha018/nestjs-firebase-auth 的下载量有多少？

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

### @alpha018/nestjs-firebase-auth 还在维护吗？

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