Vite代理报错ECONNREFUSED ::1:3000，API转发失败求助

错误分析 #

报错connect ECONNREFUSED ::1:3000说明Vite代理无法连接到3000端口的后端服务，核心原因是代理请求的目标地址无法建立连接，可能是后端未正常运行、localhost解析为IPv6但后端未监听IPv6，或是代理配置存在问题。

解决方案步骤 #

1. 确认后端服务状态 #

• 直接在浏览器或Postman中访问http://localhost:3000/api/auth/signup（用POST方法携带测试参数），如果无法访问，先启动后端服务并确保它在3000端口正常运行。
• 若后端实际运行在其他端口，修改vite.config.js中的target地址为对应端口。

2. 替换localhost为127.0.0.1 #

部分环境下localhost会优先解析为IPv6地址::1，如果后端仅监听IPv4的127.0.0.1，就会导致连接拒绝。修改vite.config.js的代理配置：

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

export default defineConfig({
  server:{
    proxy:{
      '/api' :{
        target:'http://127.0.0.1:3000', // 替换为127.0.0.1
        secure: false,
        changeOrigin : true,
        ws:true,
      },
    },
  },
  plugins: [react()],
})

3. 添加路径重写（如果需要） #

如果后端API的实际路径是/auth/signup而非/api/auth/signup，需要在代理配置中添加rewrite规则移除前端请求的/api前缀：

'/api' :{
  target:'http://127.0.0.1:3000',
  secure: false,
  changeOrigin : true,
  ws:true,
  rewrite: (path) => path.replace(/^\/api/, '') // 添加路径重写规则
},

4. 重启Vite开发服务器 #

修改vite.config.js后，必须重启Vite服务才能使配置生效。

5. 检查后端请求处理逻辑（可选） #

如果代理连接成功但仍返回500错误，需要排查后端是否正确处理了请求，比如参数校验、数据库连接、业务逻辑报错等问题；同时确认changeOrigin: true已开启，避免后端的主机验证拦截请求。

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