如何在NestJS中用Passport优雅实现混合认证策略？

针对你的需求，推荐通过自定义复合守卫结合元数据装饰器实现，既能让控制器默认启用JWT认证，又能为特定路由灵活添加API-key支持，完全避免代码重复。

步骤1：创建标记装饰器 #

先定义一个装饰器，用来标记哪些路由需要额外支持API-key认证：

import { SetMetadata } from '@nestjs/common';

// 定义元数据键
export const ALLOW_API_KEY = 'allowApiKey';
// 创建装饰器，标记路由允许API-key认证
export const AllowApiKey = () => SetMetadata(ALLOW_API_KEY, true);

步骤2：实现自定义复合守卫 #

创建一个继承自AuthGuard的自定义守卫，通过反射器读取元数据，动态选择认证策略：

import { ExecutionContext, Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import { Reflector } from '@nestjs/core';
import { ALLOW_API_KEY } from './allow-api-key.decorator';

@Injectable()
export class AuthCompositeGuard extends AuthGuard(['jwt', 'headerapikey']) {
  constructor(private readonly reflector: Reflector) {
    super();
  }

  async canActivate(context: ExecutionContext): Promise<boolean> {
    // 读取当前路由/控制器的元数据，判断是否允许API-key
    const allowApiKey = this.reflector.getAllAndOverride<boolean>(ALLOW_API_KEY, [
      context.getHandler(), // 优先读取方法级元数据
      context.getClass(),   // 其次读取控制器级元数据
    ]);

    // 如果不需要API-key，单独使用JWT守卫验证
    if (!allowApiKey) {
      const jwtGuard = new AuthGuard('jwt');
      return jwtGuard.canActivate(context);
    }

    // 如果需要API-key，使用复合策略（JWT或API-key任一通过即可）
    return super.canActivate(context);
  }
}

步骤3：在控制器中使用 #

控制器层级应用自定义守卫，默认所有路由走JWT认证；需要API-key支持的路由只需添加@AllowApiKey()装饰器：

import { Controller, Get, UseGuards } from '@nestjs/common';
import { AuthCompositeGuard } from './auth-composite.guard';
import { AllowApiKey } from './allow-api-key.decorator';

@Controller('protected')
@UseGuards(AuthCompositeGuard) // 默认所有路由受JWT保护
export class ProtectedController {
  @Get('jwt-only')
  getJwtOnlyData() {
    return { message: '仅JWT认证可访问' };
  }

  @Get('jwt-or-apikey')
  @AllowApiKey() // 额外支持API-key认证
  getFlexibleData() {
    return { message: 'JWT或API-key认证均可访问' };
  }
}

方案优势 #

• 无代码重复：控制器只需一次守卫声明，特殊路由仅需添加装饰器
• 扩展性强：后续新增认证策略时，只需修改守卫中的策略数组和元数据逻辑
• 逻辑集中：所有认证规则统一在自定义守卫中管理，便于维护

如果你需要更细粒度的控制（比如某些路由完全跳过认证），还可以扩展装饰器和守卫逻辑，添加SkipAuth之类的标记。

内容的提问来源于stack exchange，提问作者Nikolai