Next.js跨域代理配置指南：从原理到实战

一、跨域问题的本质与解决方案

在Web开发中，浏览器同源策略（Same-Origin Policy）是保障安全的重要机制，但这也给前后端分离架构的开发带来挑战。当Next.js前端应用（通常运行在http://localhost:3000）需要访问不同源的API（如http://api.example.com）时，浏览器会直接拦截请求并抛出CORS错误。

1.1 传统解决方案的局限性

• CORS配置：需要后端配合设置Access-Control-Allow-Origin等响应头，但开发阶段可能无法修改后端配置
• JSONP：仅支持GET请求，无法处理复杂业务场景
• Nginx反向代理：需要额外配置服务器，增加部署复杂度

1.2 代理转发的核心优势

Next.js内置的代理功能通过在开发服务器层面转发请求，完美规避了浏览器同源限制：

1. 前端代码保持原始API地址，无需修改
2. 开发环境无需后端配合即可解决跨域
3. 与生产环境部署解耦，保持代码一致性

二、开发环境代理配置详解

2.1 基础配置步骤

在项目根目录创建或修改next.config.js文件：

module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: `http://api.example.com/:path*`,
      }
    ]
  }
}

关键参数说明：

• source：定义匹配前端请求的路径模式，:path*表示捕获所有路径参数
• destination：指定代理目标地址，支持环境变量注入

2.2 高级配置场景

场景1：多API代理

module.exports = {
  async rewrites() {
    return [
      {
        source: '/auth-api/:path*',
        destination: 'https://auth.example.com/:path*'
      },
      {
        source: '/data-api/:path*',
        destination: 'https://data.example.com/:path*'
      }
    ]
  }
}

场景2：路径重写

当API路径与前端请求路径不一致时：

{
  source: '/legacy-api/v1/:path*',
  destination: 'https://api.example.com/v2/:path*'
}

2.3 环境变量集成

创建.env.local文件：

API_BASE_URL=https://dev.api.example.com

修改配置：

module.exports = {
  env: {
    API_BASE_URL: process.env.API_BASE_URL
  },
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: `${process.env.API_BASE_URL}/:path*`
      }
    ]
  }
}

三、生产环境部署策略

3.1 服务器端代理配置

Nginx配置示例

location /api/ {
  proxy_pass http://backend-service;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
}

优势分析

• 统一处理所有跨域请求
• 可添加缓存、负载均衡等高级功能
• 与CDN集成更顺畅

3.2 无服务器架构方案

在Vercel/Netlify等平台部署时：

1. 环境变量配置：

   API_URL=https://prod.api.example.com

2. 自定义服务器（如需要）：

   // pages/api/proxy.js
   export default async function handler(req, res) {
     const apiRes = await fetch(`${process.env.API_URL}${req.url}`);
     const data = await apiRes.json();
     res.status(200).json(data);
   }

四、常见问题与解决方案

4.1 代理失效排查

1. 检查配置顺序：确保rewrites在next.config.js中正确定义
2. 验证目标服务：使用curl直接测试API是否可访问
3. 查看网络请求：浏览器开发者工具中确认请求是否被正确转发

4.2 性能优化建议

1. 请求合并：对频繁调用的小API进行批量处理

2. 缓存策略：

   const { cache } = require('next/cache');
   async function fetchWithCache(url) {
     const cacheKey = `api:${url}`;
     const cached = await cache.get(cacheKey);
     if (cached) return JSON.parse(cached);
     const res = await fetch(url);
     const data = await res.json();
     cache.set(cacheKey, JSON.stringify(data), { ttl: 60 });
     return data;
   }

4.3 安全最佳实践

1. 限制代理路径：避免开放/等宽泛路径
2. 请求验证：

   module.exports = {
     async rewrites() {
       return [
         {
           source: '/api/:path*',
           destination: (params, req) => {
             if (!req.headers.authorization) {
               return '/api/error?message=Unauthorized';
             }
             return `http://api.example.com/${params.path}`;
           }
         }
       ]
     }
   }

五、完整示例项目结构

my-next-app/
├── next.config.js
├── .env.local
├── pages/
│   ├── api/
│   │   └── proxy.js  # 自定义代理端点（可选）
│   └── index.js
└── utils/
    └── apiClient.js  # 封装请求逻辑

apiClient.js示例：

export async function fetchData(path, options = {}) {
  try {
    const response = await fetch(`/api/${path}`, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

六、进阶技巧

6.1 动态代理目标

结合环境变量实现多环境切换：

const getApiBaseUrl = () => {
  if (process.env.NODE_ENV === 'production') {
    return process.env.PROD_API_URL;
  }
  return process.env.DEV_API_URL || 'http://localhost:4000';
};
module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: `${getApiBaseUrl()}/:path*`
      }
    ]
  }
}

6.2 请求日志记录

module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: async (params, req) => {
          console.log(`Proxying request to /${params.path}`, {
            method: req.method,
            headers: req.headers
          });
          return `http://api.example.com/${params.path}`;
        }
      }
    ]
  }
}

七、总结与最佳实践

1. 开发阶段优先使用next.config.js代理：简化调试流程
2. 生产环境采用基础设施代理：Nginx/Cloudflare等更可靠
3. 保持配置一致性：开发/测试/生产环境使用相同API路径
4. 实施监控：记录代理失败请求以便快速定位问题
5. 定期审查配置：随着API版本升级及时更新代理规则

通过合理配置Next.js的代理功能，开发者可以构建出既符合安全规范又高效灵活的前后端分离应用。这种解决方案不仅简化了开发流程，更为后续的运维和扩展奠定了坚实基础。