Next.js 配置接口跨域代理转发全攻略

一、跨域问题与代理转发的必要性

在前后端分离开发中，浏览器同源策略会阻止前端应用直接访问不同源的API接口。例如，前端运行在http://localhost:3000，而后端API部署在http://api.example.com时，浏览器会因跨域限制拒绝请求。此时，开发者面临两种选择：

1. 修改后端配置添加CORS头（需后端配合）
2. 通过代理服务器转发请求（前端自主可控）

Next.js作为服务端渲染框架，其开发服务器默认不支持直接代理请求。通过配置代理转发，开发者可以在开发阶段将API请求转发到目标服务器，既规避了跨域问题，又能模拟真实生产环境的数据流。

二、Next.js代理配置的两种实现方案

方案一：基于自定义服务器的代理配置

Next.js允许通过自定义Node.js服务器来扩展功能，这是实现代理转发的核心方法。

1. 创建自定义服务器文件

在项目根目录新建server.js文件：

const { createServer } = require('http')
const { parse } = require('url')
const next = require('next')
const { createProxyMiddleware } = require('http-proxy-middleware')
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()
app.prepare().then(() => {
  createServer(async (req, res) => {
    const parsedUrl = parse(req.url, true)
    // 配置代理规则
    const proxyOptions = {
      target: 'https://api.example.com', // 目标API地址
      changeOrigin: true,
      pathRewrite: { '^/api': '' }, // 重写路径（可选）
      onProxyRes: (proxyRes) => {
        // 可在此修改响应头（如添加CORS头）
      }
    }
    // 匹配需要代理的路径
    if (parsedUrl.pathname.startsWith('/api')) {
      createProxyMiddleware(proxyOptions)(req, res, () => {})
      return
    }
    handle(req, res, parsedUrl)
  }).listen(3000, (err) => {
    if (err) throw err
    console.log('> Ready on http://localhost:3000')
  })
})

2. 安装依赖并启动

npm install http-proxy-middleware
node server.js

3. 配置要点解析

• 路径匹配：通过pathname.startsWith('/api')识别需要代理的请求
• 目标配置：target字段指定后端API地址
• 路径重写：pathRewrite可移除路径前缀（如将/api/users转为/users）
• 生产环境适配：需在package.json中配置不同环境的启动脚本

方案二：使用Next.js中间件（13.4+版本）

Next.js 13.4引入的中间件系统提供了更优雅的解决方案。

1. 创建中间件文件

在middleware.js中配置：

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl
  // 匹配API路径
  if (pathname.startsWith('/api')) {
    const apiUrl = new URL(`https://api.example.com${pathname}`)
    // 克隆请求并修改目标
    const newRequest = new Request(apiUrl, {
      method: request.method,
      headers: request.headers,
      body: request.body
    })
    return NextResponse.rewrite(newRequest)
  }
  return NextResponse.next()
}
export const config = {
  matcher: '/api/:path*' // 匹配所有/api开头的路径
}

2. 配置优势

• 无额外依赖：使用Next.js内置功能
• 边缘函数支持：可部署到Vercel等边缘计算平台
• 类型安全：TypeScript支持更完善

三、生产环境部署注意事项

1. 环境变量管理

建议通过环境变量区分不同环境的代理配置：

// server.js示例
const API_BASE_URL = process.env.API_BASE_URL || 'https://api.example.com'

2. 安全加固措施

• 限制代理路径：避免开放所有路径的代理
• 请求验证：在中间件中添加身份验证
• 速率限制：防止API被滥用
• HTTPS强制：生产环境必须使用HTTPS

3. 性能优化建议

• 连接池管理：重用HTTP连接
• 缓存策略：对静态数据实施缓存
• 错误处理：完善代理失败时的降级方案

四、常见问题解决方案

问题1：代理后Cookie未传递

原因：未配置changeOrigin或cookieDomainRewrite
解决方案：

const proxyOptions = {
  target: 'https://api.example.com',
  changeOrigin: true,
  cookieDomainRewrite: {
    '*': 'localhost' // 开发环境适配
  }
}

问题2：WebSocket代理失败

解决方案：使用ws: true选项：

const proxyOptions = {
  target: 'ws://api.example.com',
  ws: true,
  // 其他配置...
}

问题3：路径重写不生效

检查点：

1. 确认pathRewrite的正则表达式正确
2. 检查目标服务器是否接受重写后的路径
3. 调试时打印实际请求URL

五、进阶配置技巧

1. 多目标代理配置

// 根据路径前缀代理到不同服务
const proxyMap = {
  '/auth': 'https://auth.example.com',
  '/data': 'https://data.example.com'
}
// 在中间件中实现
const target = proxyMap[pathname.split('/')[1]]
if (target) {
  // 代理逻辑...
}

2. 请求/响应修改

// 中间件中修改请求头
const modifiedHeaders = new Headers(request.headers)
modifiedHeaders.set('X-Custom-Header', 'value')
// 修改响应头（需在自定义服务器中）
onProxyRes: (proxyRes) => {
  proxyRes.headers['x-powered-by'] = 'Next.js Proxy'
}

3. 日志与监控

// 记录代理请求
console.log(`Proxying ${request.method} ${request.url} to ${target}`)
// 集成监控系统（如Sentry）
import * as Sentry from '@sentry/nextjs'
// 在错误处理中捕获代理异常

六、最佳实践总结

1. 开发生产分离：使用环境变量区分配置
2. 最小权限原则：只代理必要的路径
3. 安全先行：始终验证代理目标
4. 性能监控：跟踪代理请求的耗时
5. 文档完善：记录代理规则变更历史

通过合理配置接口跨域代理转发，开发者可以显著提升开发效率，同时为生产环境部署打下坚实基础。Next.js提供的灵活配置方案，使得无论是小型项目还是企业级应用，都能找到适合的代理实现方式。