Next.js项目中实现API路由跨域(CORS)的完整指南

什么是API路由和CORS

Next.js框架内置了API路由功能，允许开发者在项目中直接创建后端API接口，无需单独搭建服务器。这种全栈能力让前端开发者能够快速构建完整的应用。

CORS(跨源资源共享)是一种安全机制，它决定了浏览器是否允许来自不同源的请求访问当前页面的资源。在现代Web开发中，由于前后端分离的架构模式，正确处理CORS问题至关重要。

为什么需要CORS处理

当你的Next.js应用提供API服务，而前端页面可能部署在不同域名下时，浏览器会执行同源策略检查。如果没有正确配置CORS头，浏览器会阻止跨域请求，导致API调用失败。

实现步骤详解

1. 创建API路由

在Next.js项目中，任何放在pages/api目录下的文件都会自动成为API端点。例如创建一个pages/api/hello.js文件：

export default function handler(req, res) {
  res.status(200).json({ name: 'John Doe' })
}

2. 添加CORS中间件

使用流行的cors包可以轻松处理CORS问题。首先安装依赖：

npm install cors
# 或
yarn add cors

然后在API路由中引入并使用：

import Cors from 'cors'

// 初始化cors中间件
const cors = Cors({
  methods: ['GET', 'HEAD'],
})

// 辅助方法用于等待中间件执行
function runMiddleware(req, res, fn) {
  return new Promise((resolve, reject) => {
    fn(req, res, (result) => {
      if (result instanceof Error) {
        return reject(result)
      }
      return resolve(result)
    })
  })
}

async function handler(req, res) {
  // 运行中间件
  await runMiddleware(req, res, cors)
  
  // 业务逻辑
  res.json({ message: 'Hello Everyone!' })
}

export default handler

3. 配置CORS选项

cors中间件支持多种配置选项，常见的有：

const cors = Cors({
  origin: [
    'http://example.com',
    'http://localhost:3000'
  ],  // 允许的源
  methods: ['GET', 'POST', 'PUT'],  // 允许的方法
  allowedHeaders: ['Content-Type'],  // 允许的头部
  credentials: true,  // 是否允许发送cookie
})

4. 处理预检请求(OPTIONS)

对于复杂请求(如带有自定义头部的请求)，浏览器会先发送OPTIONS预检请求。cors中间件会自动处理这些请求。

实际开发建议

1. 环境区分：开发环境和生产环境可能需要不同的CORS配置
2. 白名单管理：维护一个允许访问的域名白名单
3. 安全考虑：不要简单地设置为origin: '*'，这会带来安全风险
4. 性能优化：对于频繁调用的API，考虑缓存CORS头

常见问题解决

1. CORS错误依然出现：检查中间件是否正确应用，确认没有其他中间件覆盖了CORS头
2. 凭证问题：如果需要发送cookie，确保设置了credentials: true
3. 自定义头部：在allowedHeaders中添加你的自定义头部

替代方案

除了使用cors包，你也可以手动设置响应头：

res.setHeader('Access-Control-Allow-Origin', 'http://yourdomain.com')
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT')
res.setHeader('Access-Control-Allow-Headers', 'Content-Type')

手动设置提供了更细粒度的控制，但需要处理更多细节。

总结

Next.js的API路由配合CORS中间件，为开发者提供了便捷的全栈开发体验。正确配置CORS不仅解决了跨域问题，还能保证应用的安全性。在实际项目中，应根据具体需求选择合适的CORS策略，平衡开发便利性和安全性。