Next.js API请求如何配置HTTP代理？多类尝试方案均未生效

已尝试方案的核心问题 #

• 第一次尝试：在 src/pages/api/proxy/[...slug].js 直接调用 http-proxy-middleware，运行时报 TypeError: Object(...) is not a function。故障原因是 http-proxy-middleware v2.0+ 版本移除了默认导出的调用方式，直接裸写调用会出现上下文不匹配、导出形式不兼容的问题。
• 第二次尝试：在 next.config.js 中配置 rewrites 规则转发请求到本地5000端口后端，配置完全不生效。故障原因有两个：一是 next.config.js 的修改不会触发热更新，配置写完没重启服务就不会加载；二是 pages/api 目录下的同路径路由优先级高于 rewrites 规则，存在同路径空文件时代理规则会被直接拦截。
• 第三次尝试：使用 next-http-proxy-middleware 搭建代理，配置后无法正常生效。故障原因是该包的默认示例把路由写在通用页面路径下，会接管所有前端页面请求，本身不适合做API代理场景，且包对新版本Next.js的兼容性较差，没有清晰的配置边界。
• 第四次尝试：用Express+Next.js自定义服务器实现代理，方案本身能跑通，但把代理逻辑和Next.js进程绑定在同一个Express实例中，不符合前后端独立部署的要求。

符合独立部署要求的修正方案 #

方案1：修正原生 rewrites 配置（零额外依赖） #

这个方案不需要引入第三方包，也不需要自定义服务器，Next.js和后端服务完全独立运行，仅在Next.js服务层做请求转发，修正点：

1. 删除 pages/api 目录下所有和代理路径重合的文件，避免路由优先级覆盖
2. 调整 rewrites 配置结构，把代理规则放到优先级最高的 beforeFiles 数组中，确保规则在所有页面路由匹配前生效，修正后的配置示例：

   // next.config.js
   module.exports = {
     async rewrites() {
       return {
         beforeFiles: [
           {
             source: '/api/:path*',
             destination: 'http://localhost:5000/:path*'
           }
         ],
         afterFiles: [],
         fallback: []
       }
     }
   }
   

3. 配置修改完成后，完全停止Next.js进程重新启动，不要依赖热更新加载配置。

方案2：修正API路由内的代理实现（适合自定义代理逻辑场景） #

如果需要自定义代理的请求头、过滤规则，不想用原生rewrites，可以直接在API路由中实现代理，修正点：

1. 安装和Next.js API路由上下文兼容的http-proxy-middleware版本，避免最新版本的兼容问题：

   npm install http-proxy-middleware@1.6.5
   

2. 调整路由文件的调用方式，适配Next.js的请求响应结构，修正后的代码示例（文件路径pages/api/proxy/[...slug].js）：

   const { createProxyMiddleware } = require('http-proxy-middleware');
   
   const apiProxy = createProxyMiddleware({
     target: 'http://localhost:5000',
     changeOrigin: true,
     pathRewrite: { '^/api/proxy': '' },
     secure: false,
     logLevel: 'silent',
   });
   
   export default function handler(req, res) {
     return new Promise((resolve, reject) => {
       apiProxy(req, res, (err) => {
         if (err) {
           reject(err)
           res.status(500).json({ error: '代理转发失败' })
           return
         }
         resolve()
       })
     })
   }
   

这个方案完全在Next.js自带的API路由能力范围内实现，不需要额外启动Express服务，前后端依然保持独立部署的两个进程。

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