Next.js本地开发WebSocket代理配置问题求助

问题概述 #

本地搭建Next.js开发环境，已通过Docker配置Postgres和WSProxy容器，但执行npm run dev时出现ECONNREFUSED错误，WebSocket连接地址异常为wss://localhost/v2，请求未到达WSProxy容器，排查neonConfig配置后仍未解决。

错误详情 #

Error fetching recipes: ErrorEvent {
  [Symbol(kTarget)]: WebSocket {
    _events: [Object: null prototype] {
      error: [Function],
      message: [Function],
      close: [Function],
      open: [Function]
    },
    _eventsCount: 4,
    _maxListeners: undefined,
    _binaryType: 'arraybuffer',
    _closeCode: 1006,
    _closeFrameReceived: false,
    _closeFrameSent: false,
    _closeMessage: <Buffer >,
    _closeTimer: null,
    _extensions: {},
    _paused: false,
    _protocol: '',
    _readyState: 3,
    _receiver: null,
    _sender: null,
    _socket: null,
    _bufferedAmount: 0,
    _isServer: false,
    _redirects: 0,
    _autoPong: true,
    _url: 'wss://localhost/v2',
    _req: null,
    [Symbol(shapeMode)]: false,
    [Symbol(kCapture)]: false
  },
  [Symbol(kType)]: 'error',
  [Symbol(kError)]: AggregateError [ECONNREFUSED]: 
      at internalConnectMultiple (node:net:1117:18)
      at afterConnectMultiple (node:net:1684:7)
      at TCPConnectWrap.callbackTrampoline (node:internal/async_hooks:130:17) {
    code: 'ECONNREFUSED',
    [errors]: [ [Error], [Error] ]
  },
  [Symbol(kMessage)]: ''
}

排查与解决步骤 #

1. 确认neonConfig的实际配置值 #

从API路由的日志输出中检查neonConfig.wsProxy：

• 正确值应为不带协议的WSProxy地址，比如localhost:5433
• 如果日志显示wsProxy为undefined或错误值，检查.env.local文件是否正确设置环境变量：

  NEON_WS_PROXY=localhost:5433
  

  确保Next.js能正确加载该变量（重启开发服务生效）

2. 修正neonConfig初始化逻辑 #

在数据库配置文件（如lib/db.js）或API路由顶部，明确配置neonConfig：

import { neonConfig } from '@neondatabase/serverless';

// 从环境变量读取wsProxy，禁止添加协议
neonConfig.wsProxy = process.env.NEON_WS_PROXY;
// 本地开发必须禁用安全WebSocket，否则会强制使用wss协议
neonConfig.useSecureWebSocket = false;

3. 检查Docker容器端口映射 #

用docker ps查看WSProxy容器的端口映射，确认主机端口与容器端口正确绑定：

• 正确映射示例：0.0.0.0:5433->5433/tcp
• 如果未配置端口映射，修改docker-compose.yml：

  services:
    wsproxy:
      image: neontech/wsproxy:latest
      ports:
        - "5433:5433"
      environment:
        - POSTGRES_HOST=postgres
        - POSTGRES_PORT=5432
    postgres:
      image: postgres:latest
      ports:
        - "5432:5432"
      environment:
        - POSTGRES_USER=your_user
        - POSTGRES_PASSWORD=your_password
        - POSTGRES_DB=your_db
  

4. 验证网络连通性 #

• 主机运行Next.js时，执行telnet localhost 5433测试WSProxy端口是否可访问
• 若Next.js运行在Docker容器中，进入容器执行ping wsproxy验证与WSProxy容器的网络连通性

5. 检查Postgres容器状态 #

用docker logs postgres查看Postgres容器日志，确认服务正常启动，且WSProxy配置的POSTGRES_HOST、POSTGRES_PORT与Postgres容器的设置一致

错误原因分析 #

日志中显示WebSocket地址为wss://localhost/v2，说明：

• useSecureWebSocket被设为true，强制使用wss协议
• wsProxy未正确配置，导致默认连接localhost的443端口（而非WSProxy的5433端口），最终触发ECONNREFUSED错误

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