CORS 生产环境工程指南 — 从安全模型到 Edge Runtime 的完整解决方案

你大概率遇到过这个报错：Access to XMLHttpRequest at 'https://api.example.com' from origin 'http://localhost:3000' has been blocked by CORS policy。据 Sentry 2025 年度错误报告，CORS 错误是前端生产环境中排名前 5 的运行时错误，平均每 1000 个用户会话中就有 3.2 次 CORS 相关的请求失败。但大多数开发者对 CORS 的理解停留在「加个 Access-Control-Allow-Origin 头」——这在开发环境可能凑合用，到了生产环境就会踩出各种隐蔽的坑：Cookie 丢失、预检请求超时、Edge Runtime 配置不生效、Safari 的 SameSite 策略差异……

📌 记住： CORS 不是一个「需要绕过的限制」，而是一个安全机制。正确理解它的安全模型，比记住任何配置模板都重要。

🔐 一、CORS 安全模型深度解析

1.1 同源策略的三层防线

大多数教程只告诉你「协议 + 域名 + 端口相同才算同源」，但同源策略（Same-Origin Policy）实际上有三层防线，每一层的规则不同：

⚠️ 警告： CORS 只管第二层（网络请求）。它不解决 DOM 访问问题（那是 window.postMessage 的事），也不解决 Cookie 问题（那是 SameSite 属性的事）。很多人把 Cookie 丢失归咎于 CORS，方向就错了。

1.2 简单请求 vs 预检请求：触发条件的真相

浏览器把跨域请求分为两类，触发条件远比大多数文章描述的复杂：

简单请求（Simple Request） 必须同时满足以下所有条件：

• 方法为 GET、HEAD 或 POST
• 仅包含安全的请求头：Accept、Accept-Language、Content-Language、Content-Type
• Content-Type 仅限 application/x-www-form-urlencoded、multipart/form-data、text/plain

任何一条不满足，就是预检请求（Preflight Request）——浏览器先发一个 OPTIONS 请求「探路」。

// ❌ 错误写法：这个请求会触发预检
fetch('https://api.example.com/data', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',  // 不是简单 Content-Type
    'Authorization': 'Bearer xxx',       // 不是安全请求头
    'X-Request-ID': '12345'              // 自定义请求头
  },
  body: JSON.stringify({ key: 'value' })
})
// 浏览器实际发出的请求序列：
// 1. OPTIONS /data (预检) → 等待服务端响应 CORS 头
// 2. POST /data (实际请求) → 只有预检通过后才发出

// ✅ 正确理解：预检请求的完整流程
// 浏览器自动发出的 OPTIONS 请求：
// OPTIONS /data HTTP/1.1
// Origin: http://localhost:3000
// Access-Control-Request-Method: POST
// Access-Control-Request-Headers: content-type,authorization,x-request-id
//
// 服务端必须返回：
// Access-Control-Allow-Origin: http://localhost:3000
// Access-Control-Allow-Methods: POST, GET, OPTIONS
// Access-Control-Allow-Headers: content-type, authorization, x-request-id
// Access-Control-Max-Age: 86400  ← 缓存预检结果，避免重复请求

💡 提示： 预检请求的性能代价不可忽视。每次预检都会增加一个完整的 HTTP 往返（RTT），在高延迟网络下可能增加 100-300ms 延迟。Access-Control-Max-Age 是关键优化手段——设置为 86400（24 小时）可以让浏览器缓存预检结果，避免重复请求。

1.3 各浏览器的 Max-Age 上限差异

这是一个很多人不知道的坑：不同浏览器对 Access-Control-Max-Age 的最大值限制不同。

⚠️ 警告： Safari 的 5 分钟上限是个大坑！如果你的服务端设置了 Max-Age: 86400，Chrome 和 Firefox 会缓存 2 小时 / 24 小时，但 Safari 只缓存 5 分钟。在 Safari 用户占比高的场景下（比如 C 端产品），预检请求的频率会显著增加。

🔧 二、生产环境 CORS 配置实战

2.1 Node.js 服务端配置（Express / Fastify / Hono）

很多开发者用 cors 中间件一把梭，但生产环境需要精细控制。以下是三个主流框架的正确配置方式：

// express-cors.mjs — Express 生产级 CORS 配置
import express from 'express'

const app = express()

// 生产环境白名单 — 永远不要用 '*' 配合 credentials
const ALLOWED_ORIGINS = [
  'https://jsjson.com',
  'https://www.jsjson.com',
  'https://admin.jsjson.com'
]

app.use((req, res, next) => {
  const origin = req.headers.origin

  // 只允许白名单中的源
  if (ALLOWED_ORIGINS.includes(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin)
  }

  // 凭证模式 — 必须设置为 'true'，不能省略
  res.setHeader('Access-Control-Allow-Credentials', 'true')

  // 允许的请求头 — 明确列出，不要用 '*'
  res.setHeader('Access-Control-Allow-Headers',
    'Content-Type, Authorization, X-Request-ID, X-Trace-ID')

  // 允许的 HTTP 方法
  res.setHeader('Access-Control-Allow-Methods',
    'GET, POST, PUT, PATCH, DELETE, OPTIONS')

  // 暴露自定义响应头 — 让前端 JS 能读取这些头
  res.setHeader('Access-Control-Expose-Headers',
    'X-Request-ID, X-Total-Count, X-Rate-Limit-Remaining')

  // 预检缓存 — 配合浏览器上限设置
  res.setHeader('Access-Control-Max-Age', '300') // Safari 友好

  // 预检请求直接返回 204
  if (req.method === 'OPTIONS') {
    return res.status(204).end()
  }

  next()
})

// hono-cors.mjs — Hono 框架 CORS 配置（Edge Runtime 友好）
import { Hono } from 'hono'
import { cors } from 'hono/cors'

const app = new Hono()

// Hono 内置 cors 中间件 — 支持动态 origin
app.use('/api/*', cors({
  origin: (origin) => {
    // 动态白名单检查
    const allowed = [
      'https://jsjson.com',
      'https://www.jsjson.com'
    ]
    return allowed.includes(origin) ? origin : ''
  },
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowHeaders: ['Content-Type', 'Authorization'],
  exposeHeaders: ['X-Total-Count'],
  maxAge: 300,
  credentials: true
}))

💡 提示： Hono 的 cors 中间件天然适配 Edge Runtime（Cloudflare Workers、Deno Deploy、Vercel Edge），因为它不依赖 Node.js 的 req/res 对象。如果你的 API 部署在 Edge 上，优先选 Hono。

2.2 Cookie 凭证模式的完整配置链

这是 CORS 最容易出错的环节——前端、后端、浏览器三端的配置必须完全一致，任何一环缺失都会导致 Cookie 不发送。

// 前端请求 — 必须显式声明 credentials: 'include'
const response = await fetch('https://api.jsjson.com/user/profile', {
  credentials: 'include',  // 关键！不设置则不发送 Cookie
  headers: {
    'Content-Type': 'application/json'
  }
})

// ❌ 错误写法：默认值是 'same-origin'，跨域时不发 Cookie
fetch('https://api.jsjson.com/user/profile')
// 这个请求不会携带 Cookie，即使后端配置了 CORS

完整的凭证模式配置检查清单：

⚠️ 警告： 当使用 credentials: 'include' 时，Access-Control-Allow-Origin 不能设为 *，必须是具体的源地址。这是 CORS 规范的硬性要求——浏览器会直接拒绝响应，不给任何回旋余地。

2.3 Nginx 反向代理 CORS 配置

在很多生产架构中，Nginx 作为反向代理层处理 CORS，比在应用层处理更高效：

# nginx-cors.conf — Nginx 生产级 CORS 配置
server {
    listen 443 ssl;
    server_name api.jsjson.com;

    # 预检请求的映射变量
    map $http_origin $cors_origin {
        default "";
        "https://jsjson.com" $http_origin;
        "https://www.jsjson.com" $http_origin;
        "https://admin.jsjson.com" $http_origin;
    }

    location /api/ {
        # 动态设置 CORS 头 — 只对白名单源生效
        if ($cors_origin != "") {
            add_header 'Access-Control-Allow-Origin' $cors_origin always;
            add_header 'Access-Control-Allow-Credentials' 'true' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
            add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-Request-ID' always;
            add_header 'Access-Control-Expose-Headers' 'X-Total-Count' always;
            add_header 'Access-Control-Max-Age' 300 always;
        }

        # 预检请求直接返回 — 不转发到后端
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin' $cors_origin;
            add_header 'Access-Control-Allow-Credentials' 'true';
            add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
            add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type';
            add_header 'Access-Control-Max-Age' 300;
            add_header 'Content-Length' 0;
            return 204;
        }

        proxy_pass http://backend:3000;
    }
}

⚠️ 警告： Nginx 的 add_header 指令有一个常见陷阱：如果在 if 块内使用 add_header，外层的 add_header 会被忽略。这意味着如果你在外层设置了安全头（如 X-Content-Type-Options），当进入 if 块时它们会消失。解决方案是使用 ngx_headers_more 模块，或者把所有头都放在同一个 if 块内。

🚀 三、Edge Runtime 与现代架构的 CORS 策略

3.1 Cloudflare Workers CORS 配置

Edge Runtime 的 CORS 处理与传统 Node.js 有本质区别——没有 req.headers.origin 的便利，需要用 Web API 原生方式处理：

// cloudflare-workers-cors.js — Cloudflare Workers CORS 完整配置
const ALLOWED_ORIGINS = new Set([
  'https://jsjson.com',
  'https://www.jsjson.com'
])

export default {
  async fetch(request, env, ctx) {
    const origin = request.headers.get('Origin')
    const isAllowed = ALLOWED_ORIGINS.has(origin)

    // 构建 CORS 响应头
    const corsHeaders = {
      'Access-Control-Allow-Origin': isAllowed ? origin : '',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
      'Access-Control-Allow-Credentials': 'true',
      'Access-Control-Max-Age': '300',
      'Vary': 'Origin'  // 关键：告诉 CDN 按 Origin 缓存
    }

    // 预检请求
    if (request.method === 'OPTIONS') {
      return new Response(null, { status: 204, headers: corsHeaders })
    }

    // 实际请求
    const response = await handleRequest(request, env)

    // 将 CORS 头添加到响应
    const newResponse = new Response(response.body, response)
    Object.entries(corsHeaders).forEach(([key, value]) => {
      newResponse.headers.set(key, value)
    })

    return newResponse
  }
}

// nextjs-middleware-cors.js — Next.js Edge Middleware CORS 配置
import { NextResponse } from 'next/server'

const ALLOWED_ORIGINS = [
  'https://jsjson.com',
  'https://www.jsjson.com'
]

export function middleware(request) {
  const origin = request.headers.get('origin')
  const isAllowed = origin && ALLOWED_ORIGINS.includes(origin)

  // 预检请求
  if (request.method === 'OPTIONS') {
    return new NextResponse(null, {
      status: 204,
      headers: {
        'Access-Control-Allow-Origin': isAllowed ? origin : '',
        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
        'Access-Control-Max-Age': '300'
      }
    })
  }

  // 正常请求 — 在响应上附加 CORS 头
  const response = NextResponse.next()
  if (isAllowed) {
    response.headers.set('Access-Control-Allow-Origin', origin)
  }

  return response
}

// 只匹配 API 路由
export const config = {
  matcher: '/api/:path*'
}

3.2 CORS 与 CDN 缓存的冲突

这是一个高级但常见的生产问题：当你的 API 响应被 CDN 缓存时，第一个请求的 Access-Control-Allow-Origin 会被缓存下来，后续不同源的请求拿到的可能是错误的 Origin。

用户 A (来自 jsjson.com) → CDN 缓存 → 响应头: Allow-Origin: jsjson.com ✅
用户 B (来自 admin.jsjson.com) → CDN 缓存命中 → 响应头: Allow-Origin: jsjson.com ❌

解决方案是设置 Vary: Origin 响应头：

// 告诉 CDN：按 Origin 请求头分别缓存
response.headers.set('Vary', 'Origin')

⚠️ 警告： Vary: Origin 会让 CDN 按不同的 Origin 值分别缓存响应，这会降低缓存命中率。如果你只有一个固定源，可以不用 Vary；如果支持多个源，必须设置，否则会出现上述缓存污染问题。

💡 四、CORS 调试与常见踩坑

4.1 系统化调试流程

CORS 报错的错误信息往往不够具体。以下是系统化的调试流程：

// cors-debug.js — CORS 调试辅助脚本
async function debugCORS(url, options = {}) {
  console.group('🔍 CORS 调试信息')
  console.log('目标 URL:', url)
  console.log('当前 Origin:', window.location.origin)

  try {
    const response = await fetch(url, {
      ...options,
      credentials: 'include'
    })

    console.log('✅ 请求成功')
    console.log('响应状态:', response.status)

    // 检查 CORS 相关响应头
    const corsHeaders = [
      'access-control-allow-origin',
      'access-control-allow-credentials',
      'access-control-allow-methods',
      'access-control-allow-headers',
      'access-control-expose-headers',
      'access-control-max-age',
      'vary'
    ]

    console.group('响应头:')
    corsHeaders.forEach(header => {
      const value = response.headers.get(header)
      console.log(`${header}: ${value ?? '❌ 未设置'}`)
    })
    console.groupEnd()

    // 检查是否能读取自定义响应头
    const canReadCustomHeader = response.headers.get('x-request-id')
    console.log('自定义头 X-Request-ID:', canReadCustomHeader ?? '❌ 无法读取（未在 Expose-Headers 中声明）')

  } catch (error) {
    console.error('❌ 请求失败:', error.message)

    // 常见错误分类
    if (error.message.includes('Failed to fetch')) {
      console.warn('💡 可能原因: 1) 服务端未返回 CORS 头 2) 网络不通 3) 证书错误')
    }
    if (error.message.includes('blocked by CORS')) {
      console.warn('💡 可能原因: 1) Origin 不匹配 2) 缺少 Allow-Credentials 3) 预检失败')
    }
  }

  console.groupEnd()
}

// 使用方式
debugCORS('https://api.jsjson.com/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ test: true })
})

4.2 六大常见踩坑与解决方案

4.3 同端口不同协议的隐蔽问题

一个特别隐蔽的场景：开发环境中，前端用 http://localhost:3000，API 用 https://localhost:8443。虽然域名相同，但协议不同（http vs https），仍然是跨源。

// ❌ 这是跨源请求！协议不同
// 前端: http://localhost:3000
fetch('https://localhost:8443/api/data')  // 跨源！

// ✅ 解决方案 1: 统一协议
// 开发环境也用 HTTPS（推荐用 mkcert 生成本地证书）
fetch('https://localhost:3000/api/data')  // 同源

// ✅ 解决方案 2: 用 Vite 代理（开发环境）
// vite.config.ts
export default {
  server: {
    proxy: {
      '/api': {
        target: 'https://localhost:8443',
        changeOrigin: true,
        secure: false  // 允许自签名证书
      }
    }
  }
}
// 前端请求 /api/data → Vite 代理到 https://localhost:8443/api/data
// 对浏览器来说是同源请求，不触发 CORS

🔐 五、CORS 安全加固

5.1 反射 Origin 攻击

很多教程教的「反射 Origin」配置是个安全漏洞：

// ❌ 危险写法：反射任何 Origin
app.use((req, res, next) => {
  res.setHeader('Access-Control-Allow-Origin', req.headers.origin)
  res.setHeader('Access-Control-Allow-Credentials', 'true')
  next()
})
// 攻击者可以在 evil.com 发起请求，拿到用户的 Cookie！

// ✅ 安全写法：严格白名单验证
app.use((req, res, next) => {
  const origin = req.headers.origin
  if (ALLOWED_ORIGINS.includes(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin)
    res.setHeader('Access-Control-Allow-Credentials', 'true')
  }
  // 不在白名单内的 Origin 不设置任何 CORS 头 → 浏览器自动拒绝
  next()
})

5.2 CORS 与 CSRF 防护的协同

📌 记住： CORS 不是 CSRF 防护。CORS 只阻止 JavaScript 读取跨源响应，但不能阻止表单提交（<form> 的 POST 是简单请求，不受 CORS 限制）。生产环境必须同时使用 CORS + CSRF Token。

// CORS + CSRF 双重防护
app.use((req, res, next) => {
  // CORS 头（如上配置）
  // ...

  // CSRF 防护：验证自定义请求头
  // 简单请求不能携带自定义头，所以有自定义头的请求一定经过了 CORS 预检
  if (['POST', 'PUT', 'DELETE'].includes(req.method)) {
    const csrfToken = req.headers['x-csrf-token']
    if (!verifyCSRFToken(csrfToken)) {
      return res.status(403).json({ error: 'Invalid CSRF token' })
    }
  }

  next()
})

📊 六、方案对比与选型建议

⚡ 关键结论： 如果你的前后端可以部署在同一个域名下（用 Nginx 反向代理 /api 到后端），这是最优方案——完全避免 CORS 问题，零额外开销。如果必须跨域，Edge Runtime 处理 CORS 是 2026 年的最佳实践。

✅ 总结与最佳实践

CORS 看似简单，但在生产环境中有大量细节需要处理。以下是核心要点：

1. ✅ 永远使用白名单，不要反射 Origin 或使用 *
2. ✅ Vary: Origin 是 CDN 缓存场景的必需品
3. ✅ Access-Control-Max-Age: 300 是 Safari 兼容的安全值
4. ✅ Cookie 凭证需要三端一致：前端 credentials: 'include' + 后端 Allow-Credentials: true + Cookie SameSite=None; Secure
5. ❌ 不要用 CORS 替代 CSRF 防护
6. ❌ 不要在反射 Origin 时不验证白名单
7. ⚠️ Edge Runtime 必须使用 Web API（new Response()），不能用 Node.js 的 res.setHeader()

相关工具推荐：

• 🔧 jsjson.com CORS 测试工具 — 在线检测 CORS 配置
• 🔧 Mozilla Observatory — HTTP 安全头检测
• 🔧 CORS Anywhere — 开发环境 CORS 代理（仅用于开发）
• 🔧 Hono — Edge Runtime 友好的 Web 框架，内置 CORS 中间件