Next.js 14（App Router）MQTT连接异常：报错及不稳定排查

1. 修复bufferUtil.mask is not a function错误 #

这个错误源于ws库（mqtt.js依赖的WebSocket实现）在Next.js 14 RSC环境下的native模块兼容性问题。通过调整MQTT连接配置，强制使用纯JavaScript的WebSocket实现，避免依赖native模块：

// lib/mqtt-client.ts
import mqtt, { MqttClient } from 'mqtt';

let client: MqttClient | null = null;
let clientInitPromise: Promise<MqttClient> | null = null;

export async function getMqttClient(): Promise<MqttClient> {
  // 复用已初始化的客户端
  if (client) return client;
  // 避免重复初始化
  if (clientInitPromise) return clientInitPromise;

  clientInitPromise = new Promise((resolve, reject) => {
    const newClient = mqtt.connect('ws://my-broker-name:883', {
      reconnectPeriod: 1000,
      connectTimeout: 30 * 1000,
      keepalive: 60,
      // 关键配置：禁用native WebSocket，强制使用JS实现
      wsOptions: {
        nativeWebSocket: false,
        perMessageDeflate: false // 额外禁用压缩，减少兼容性问题
      }
    });

    newClient.on('connect', () => {
      client = newClient;
      resolve(newClient);
    });

    newClient.on('error', (err) => {
      clientInitPromise = null; // 初始化失败后允许重试
      reject(err);
    });
  });

  return clientInitPromise;
}

2. 解决客户端初始化时机问题 #

直接同步创建客户端会导致路由处理器调用时客户端未就绪（甚至为undefined）。改用异步初始化函数，确保客户端连接成功后再进行订阅操作：

在路由处理器中使用 #

// app/api/mqtt/subscribe/route.ts
import { getMqttClient } from '@/lib/mqtt-client';
import { NextResponse } from 'next/server';

export async function GET() {
  try {
    const client = await getMqttClient();
    
    // 确保客户端已连接再订阅
    if (!client.connected) {
      await new Promise(resolve => client.once('connect', resolve));
    }

    const targetTopic = 'your/target/topic';
    // 订阅主题，添加错误处理
    client.subscribe(targetTopic, (err) => {
      if (err) {
        console.error(`订阅主题 ${targetTopic} 失败:`, err);
      } else {
        console.log(`成功订阅主题 ${targetTopic}`);
      }
    });

    return NextResponse.json({ status: 'success', message: '订阅操作已执行' });
  } catch (error) {
    console.error('MQTT客户端初始化或订阅失败:', error);
    return NextResponse.json(
      { status: 'error', message: '操作失败' },
      { status: 500 }
    );
  }
}

额外注意事项 #

• 确保mqtt.js版本为最新稳定版，避免已知的兼容性bug；
• 服务器端单例客户端需要处理重连逻辑：当客户端断开时，mqtt.js会自动触发重连，但需监听reconnect事件确保状态正常；
• 在RSC中使用全局单例时，注意避免内存泄漏，可在客户端close事件中重置实例状态。

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