Nest.js gRPC服务端错误码无法正确映射至客户端求助

使用Nest.js开发gRPC应用时，服务端抛出状态码为3（INVALID_ARGUMENT）和5（NOT_FOUND）的RpcException，但客户端始终捕获到状态码为2（UNKNOWN）的错误。无论是否使用Observable，问题都存在；此前功能正常，怀疑与依赖库版本有关。尝试直接抛出RpcException或基础Error均无效，期望客户端能接收到正确的3或5状态码。

可能的解决方案 #

1. 规范RpcException的构造方式 #

必须使用gRPC官方状态码枚举而非直接传数字构造异常，否则Nest.js无法正确映射到标准gRPC状态码：

import { RpcException } from '@nestjs/microservices';
import { status } from '@grpc/grpc-js';

// 正确示例
throw new RpcException({
  code: status.INVALID_ARGUMENT, // 不要直接写数字3
  message: '参数格式错误',
});

直接传数字会导致Nest无法识别状态码类型，最终返回UNKNOWN。

2. 锁定兼容的依赖版本 #

如果是升级依赖后出现问题，大概率是版本不兼容。重点对齐以下包的版本：

• @nestjs/microservices
• @grpc/grpc-js
• @grpc/proto-loader

推荐一组经过验证的兼容版本：

{
  "@nestjs/microservices": "^10.0.0",
  "@grpc/grpc-js": "^1.9.0",
  "@grpc/proto-loader": "^0.7.8"
}

调整版本后执行npm install或yarn install，重启服务测试。

3. 检查全局异常过滤器的逻辑 #

如果自定义了gRPC全局异常过滤器，需确保它正确传递原始异常的状态码，避免强制覆盖为UNKNOWN：

import { Catch, RpcExceptionFilter, ArgumentsHost } from '@nestjs/common';
import { RpcException } from '@nestjs/microservices';
import { status } from '@grpc/grpc-js';

@Catch(RpcException)
export class GrpcExceptionFilter implements RpcExceptionFilter<RpcException> {
  catch(exception: RpcException, host: ArgumentsHost) {
    const ctx = host.switchToRpc();
    const error = exception.getError();
    // 保留原始状态码，不要硬编码为UNKNOWN
    return ctx.getRpcServer().sendError({
      code: error.code || status.UNKNOWN,
      message: error.message || '未知错误',
    });
  }
}

4. 验证Proto文件的定义 #

确保proto文件中没有自定义与gRPC标准状态码冲突的枚举，比如：

// 错误示例：自定义枚举覆盖标准码
enum ErrorCode {
  INVALID_ARGUMENT = 1003;
}

// 正确做法：直接使用gRPC标准状态码，无需自定义

客户端依赖proto文件解析状态码，自定义枚举会导致标准码无法被识别，进而解析为UNKNOWN。

5. 排查异常拦截逻辑 #

检查服务端的中间件、拦截器是否捕获了RpcException并重新抛出普通Error——这种操作会丢失gRPC状态码信息，导致Nest无法正确映射。确保异常始终以RpcException的形式抛出，且未被上层逻辑篡改。

调试技巧 #

• 在服务端抛出异常时，打印exception.getError()的完整内容，确认code字段是否为目标状态码；
• 使用grpcurl等gRPC调试工具直接调用服务端接口，查看原始返回的状态码，排除客户端代码的问题。

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