Nuxt3项目中Vite开发环境代理配置不生效问题排查

问题描述 #

我有一个Nuxt3 Web应用，需要将/whatever路径的请求代理到localhost:3033。按照Vite官方文档配置了vite.server.proxy，nuxt.config.ts代码如下：

export default defineNuxtConfig({
    vite: {
        server: {
            proxy: {
                '/whatever': 'http://localhost:3033/',
            }
        }
    }
})

重启yarn dev后，访问http://localhost:3000/whatever时：

• 空项目中仅显示“Welcome to Nuxt”页面
• 开启pages:true的主项目中返回404错误

可能的原因及解决方法 #

1. Nuxt路由处理优先级高于Vite代理 #

Nuxt3的请求处理流程中，会先经过自身的路由系统：

• 空项目未启用pages时，Nuxt会将所有未匹配到的请求 fallback 到根组件，直接返回默认的“Welcome to Nuxt”页面，根本不会触发Vite代理。
• 启用pages:true后，Nuxt会去pages目录查找对应路由，找不到则返回404，同样跳过代理环节。

2. 代理配置缺少关键参数 #

原配置仅指定了目标地址，缺少路径重写和跨域处理的必要参数，即使代理触发也可能无法正确转发请求。

解决方法：优化Vite代理配置 #

修改nuxt.config.ts中的代理配置，添加rewrite和changeOrigin参数，确保请求能绕过Nuxt路由触发代理：

export default defineNuxtConfig({
  vite: {
    server: {
      proxy: {
        '/whatever': {
          target: 'http://localhost:3033',
          changeOrigin: true, // 解决跨域问题
          rewrite: (path) => path.replace(/^\/whatever/, '') // 重写路径，去掉前缀后转发到目标服务
        }
      }
    }
  }
})

替代方案：使用Nuxt Server Middleware代理 #

如果Vite代理仍不生效，可以改用Nuxt的Server Middleware实现代理，这种方式优先级更高，能确保请求被正确转发：

1. 安装依赖：

yarn add http-proxy-middleware

2. 在server/middleware目录下创建proxy.ts文件：

import { createProxyMiddleware } from 'http-proxy-middleware'

export default defineEventHandler((event) => {
  return createProxyMiddleware({
    target: 'http://localhost:3033',
    changeOrigin: true,
    pathRewrite: { '^/whatever': '' }
  })(event.node.req, event.node.res)
})

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