NestJS gRPC连接微服务报14 UNAVAILABLE无连接建立错误

问题场景 #

调用NestJS微服务gRPC接口时抛出无连接错误，已核对客户端、服务端配置的监听地址、gRPC包名、proto文件路径完全一致，调用仍失败。

相关代码与日志 #

客户端gRPC注册代码 #

imports: [
    ClientsModule.register([
        {
            name: 'UsersService',
            transport: Transport.GRPC,
            options: {
                url: 'localhost:50051',
                package: 'users',
                protoPath: 'path/to/proto',
            }
        }
    ])
],

Users微服务启动代码 #

async function bootstrap() {
    const app = await NestFactory.createMicroservice(
        UsersModule,
        {
            transport: Transport.GRPC,
            options: {
                url: 'localhost:50051',
                package: 'users',
                protoPath: 'path/to/proto',
            }
        },
    )
}

错误日志 #

[Nest] 3644  - 12.06.2022, 22:11:54   ERROR [ExceptionsHandler] 14 UNAVAILABLE: No connection established
Error: 14 UNAVAILABLE: No connection established
    at Object.callErrorFromStatus (C:\Users\123\Desktop\projects\syntx\api-gateway\node_modules\@grpc\grpc-js\src\call.ts:81:24)
    at Object.onReceiveStatus (C:\Users\123\Desktop\projects\syntx\api-gateway\node_modules\@grpc\grpc-js\src\client.ts:351:36)
    at Object.onReceiveStatus (C:\Users\123\Desktop\projects\syntx\api-gateway\node_modules\@grpc\grpc-js\src\client-interceptors.ts:462:34)
    at Object.onReceiveStatus (C:\Users\123\Desktop\projects\syntx\api-gateway\node_modules\@grpc\grpc-js\src\client-interceptors.ts:424:48)
    at C:\Users\123\Desktop\projects\syntx\api-gateway\node_modules\@grpc\grpc-js\src\call-stream.ts:330:24
    at processTicksAndRejections (node:internal/process/task_queues:78:11)

排查解决步骤 #

• 优先检查微服务启动逻辑：你贴出的服务端代码存在两个致命问题，直接导致服务根本没有启动监听端口：
  1. 定义完bootstrap函数后没有执行该函数，代码运行时不会进入启动逻辑
  2. 函数内创建微服务实例后，没有调用await app.listen()触发端口绑定
     修正后的最小可用启动代码如下：

  async function bootstrap() {
      const app = await NestFactory.createMicroservice(
          UsersModule,
          {
              transport: Transport.GRPC,
              options: {
                  url: 'localhost:50051',
                  package: 'users',
                  protoPath: 'path/to/proto',
              }
          },
      )
      await app.listen(); // 启动端口监听
  }
  bootstrap(); // 执行启动函数
  

  改完重启微服务，看到Nest输出微服务启动成功的日志后再尝试调用，90%的场景下这个问题就能解决。
• 端口占用校验：如果修正启动代码后仍报错，执行对应系统命令检查50051端口占用情况：
  • Windows：命令行运行netstat -ano | findstr :50051
  • Mac/Linux：终端运行lsof -i:50051
    确认占用50051端口的进程是你启动的Users微服务，没有被其他程序抢占端口，也不存在服务启动报错导致端口绑定失败的情况。
• 本地地址解析问题修复：Windows环境下localhost可能默认解析为IPv6地址::1，但部分版本的gRPC-js默认只绑定IPv4地址，会出现连接不通的情况，把客户端和服务端配置里的url从localhost:50051改成127.0.0.1:50051再重试。
• 拦截规则排查：检查本地防火墙、系统全局代理、抓包工具（Charles、Fiddler等）是否拦截了本地50051端口的TCP请求，这类拦截会直接打断gRPC连接建立流程。
• 启动顺序校验：必须等Users微服务完全启动、端口进入监听状态后，再启动API网关服务发起调用。如果需要提升服务容错能力，可以在gRPC客户端配置中增加keepalive和重试参数，避免服务短暂不可用时直接抛错。

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