Vite+React+TypeScript代理配置报错：ECONNREFUSED连接被拒绝

问题背景 #

在localhost:3000根路径部署数据服务后，为解决/api请求的CORS问题，配置了Vite代理如下：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      }
    }
  }
})

执行npm run dev（命令为"dev": "vite"）后，请求http://127.0.0.1:5173/api持续报错：

9:16:44 AM [vite] http proxy error at :
Error: connect ECONNREFUSED 127.0.0.1:3000
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1595:16)

单独使用http-proxy编写代理脚本可正常运行，测试过Node.js 21.5和18.19版本，添加错误捕获后仍得到相同错误，需代理返回数据服务的正常结果。

排查步骤与解决方法 #

• 确认数据服务状态：直接访问http://localhost:3000或http://127.0.0.1:3000，验证服务是否正常响应；用端口检测工具确认3000端口被占用：

  • Windows：netstat -ano | findstr :3000
  • macOS/Linux：lsof -i :3000
    若端口未被占用，说明数据服务未启动或启动失败，先解决服务启动问题。

• 修正target地址解析：将代理配置中的target从http://localhost:3000替换为http://127.0.0.1:3000，避免localhost解析异常；同时确认数据服务绑定的IP（若服务仅绑定特定IP，target需对应匹配）。

• 检查rewrite规则合理性：当前规则会移除路径开头的/api，若数据服务的接口本身以/api开头，会导致转发路径错误。需根据实际接口结构调整规则：

  // 若接口是/api开头，取消rewrite或调整规则
  rewrite: (path) => path
  

• 排查Vite服务器网络限制：尝试在Vite配置中添加host: '127.0.0.1'，强制服务器绑定本地回环地址；同时确认本地防火墙未阻止Vite访问3000端口。

• 升级Vite版本：部分旧版Vite存在代理兼容性bug，执行以下命令升级到最新稳定版：

  npm update vite @vitejs/plugin-react
  

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