Back to Details

cors-configuration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CORS Configuration

CORS 配置

Configure secure Cross-Origin Resource Sharing for APIs and web applications.
为 API 和 Web 应用配置安全的跨源资源共享（CORS）。

Core Workflow

核心工作流程

  1. Identify origins: Define allowed origins
  2. Configure headers: Set CORS response headers
  3. Handle preflight: OPTIONS request handling
  4. Set credentials: Cookie and auth handling
  5. Limit methods: Allowed HTTP methods
  6. Test configuration: Verify CORS works
  1. 识别源地址：定义允许的源地址
  2. 配置请求头：设置 CORS 响应头
  3. 处理预检请求：OPTIONS 请求处理逻辑
  4. 配置凭据：Cookie 与身份认证处理
  5. 限制请求方法：定义允许的 HTTP 方法
  6. 测试配置：验证 CORS 功能正常

CORS Headers Reference

CORS 请求头参考

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Request-ID
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400
Access-Control-Expose-Headers: X-Request-ID, X-RateLimit-Remaining
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Request-ID
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400
Access-Control-Expose-Headers: X-Request-ID, X-RateLimit-Remaining

Express.js Configuration

Express.js 配置

Basic CORS

基础 CORS 配置

typescript
// middleware/cors.ts
import cors from 'cors';
import { Express } from 'express';

const allowedOrigins = [
  'https://app.example.com',
  'https://admin.example.com',
];

// Add development origins
if (process.env.NODE_ENV === 'development') {
  allowedOrigins.push('http://localhost:3000');
  allowedOrigins.push('http://localhost:5173');
}

export function configureCors(app: Express) {
  app.use(cors({
    origin: (origin, callback) => {
      // Allow requests with no origin (mobile apps, Postman)
      if (!origin) {
        return callback(null, true);
      }

      if (allowedOrigins.includes(origin)) {
        return callback(null, true);
      }

      callback(new Error('Not allowed by CORS'));
    },
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
    allowedHeaders: [
      'Content-Type',
      'Authorization',
      'X-Request-ID',
      'X-CSRF-Token',
    ],
    exposedHeaders: [
      'X-Request-ID',
      'X-RateLimit-Limit',
      'X-RateLimit-Remaining',
    ],
    credentials: true,
    maxAge: 86400, // 24 hours
    preflightContinue: false,
    optionsSuccessStatus: 204,
  }));
}
typescript
// middleware/cors.ts
import cors from 'cors';
import { Express } from 'express';

const allowedOrigins = [
  'https://app.example.com',
  'https://admin.example.com',
];

// 添加开发环境源地址
if (process.env.NODE_ENV === 'development') {
  allowedOrigins.push('http://localhost:3000');
  allowedOrigins.push('http://localhost:5173');
}

export function configureCors(app: Express) {
  app.use(cors({
    origin: (origin, callback) => {
      // 允许无来源的请求（如移动应用、Postman）
      if (!origin) {
        return callback(null, true);
      }

      if (allowedOrigins.includes(origin)) {
        return callback(null, true);
      }

      callback(new Error('Not allowed by CORS'));
    },
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
    allowedHeaders: [
      'Content-Type',
      'Authorization',
      'X-Request-ID',
      'X-CSRF-Token',
    ],
    exposedHeaders: [
      'X-Request-ID',
      'X-RateLimit-Limit',
      'X-RateLimit-Remaining',
    ],
    credentials: true,
    maxAge: 86400, // 24 小时
    preflightContinue: false,
    optionsSuccessStatus: 204,
  }));
}

Manual CORS Middleware

手动实现 CORS 中间件

typescript
// middleware/manual-cors.ts
import { Request, Response, NextFunction } from 'express';

interface CorsOptions {
  origins: string[];
  methods: string[];
  allowedHeaders: string[];
  exposedHeaders: string[];
  credentials: boolean;
  maxAge: number;
}

const defaultOptions: CorsOptions = {
  origins: [],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  exposedHeaders: [],
  credentials: false,
  maxAge: 86400,
};

export function createCorsMiddleware(options: Partial<CorsOptions> = {}) {
  const config = { ...defaultOptions, ...options };

  return (req: Request, res: Response, next: NextFunction) => {
    const origin = req.headers.origin;

    // Check if origin is allowed
    if (origin && config.origins.includes(origin)) {
      res.setHeader('Access-Control-Allow-Origin', origin);
    } else if (config.origins.includes('*')) {
      res.setHeader('Access-Control-Allow-Origin', '*');
    }

    // Set other CORS headers
    res.setHeader('Access-Control-Allow-Methods', config.methods.join(', '));
    res.setHeader('Access-Control-Allow-Headers', config.allowedHeaders.join(', '));

    if (config.exposedHeaders.length > 0) {
      res.setHeader('Access-Control-Expose-Headers', config.exposedHeaders.join(', '));
    }

    if (config.credentials) {
      res.setHeader('Access-Control-Allow-Credentials', 'true');
    }

    res.setHeader('Access-Control-Max-Age', String(config.maxAge));

    // Handle preflight request
    if (req.method === 'OPTIONS') {
      res.status(204).end();
      return;
    }

    next();
  };
}
typescript
// middleware/manual-cors.ts
import { Request, Response, NextFunction } from 'express';

interface CorsOptions {
  origins: string[];
  methods: string[];
  allowedHeaders: string[];
  exposedHeaders: string[];
  credentials: boolean;
  maxAge: number;
}

const defaultOptions: CorsOptions = {
  origins: [],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  exposedHeaders: [],
  credentials: false,
  maxAge: 86400,
};

export function createCorsMiddleware(options: Partial<CorsOptions> = {}) {
  const config = { ...defaultOptions, ...options };

  return (req: Request, res: Response, next: NextFunction) => {
    const origin = req.headers.origin;

    // 检查源地址是否被允许
    if (origin && config.origins.includes(origin)) {
      res.setHeader('Access-Control-Allow-Origin', origin);
    } else if (config.origins.includes('*')) {
      res.setHeader('Access-Control-Allow-Origin', '*');
    }

    // 设置其他 CORS 请求头
    res.setHeader('Access-Control-Allow-Methods', config.methods.join(', '));
    res.setHeader('Access-Control-Allow-Headers', config.allowedHeaders.join(', '));

    if (config.exposedHeaders.length > 0) {
      res.setHeader('Access-Control-Expose-Headers', config.exposedHeaders.join(', '));
    }

    if (config.credentials) {
      res.setHeader('Access-Control-Allow-Credentials', 'true');
    }

    res.setHeader('Access-Control-Max-Age', String(config.maxAge));

    // 处理预检请求
    if (req.method === 'OPTIONS') {
      res.status(204).end();
      return;
    }

    next();
  };
}

Route-Specific CORS

路由级别的 CORS 配置

typescript
// routes/api.ts
import { Router } from 'express';
import cors from 'cors';

const router = Router();

// Public endpoints - allow any origin
const publicCors = cors({
  origin: '*',
  methods: ['GET'],
});

// Private endpoints - restrict origin
const privateCors = cors({
  origin: ['https://app.example.com'],
  credentials: true,
});

// Webhook endpoints - specific origins
const webhookCors = cors({
  origin: ['https://stripe.com', 'https://github.com'],
  methods: ['POST'],
});

router.get('/public/data', publicCors, publicDataHandler);
router.post('/private/data', privateCors, privateDataHandler);
router.post('/webhooks/stripe', webhookCors, stripeWebhookHandler);

export default router;
typescript
// routes/api.ts
import { Router } from 'express';
import cors from 'cors';

const router = Router();

// 公开接口 - 允许任意源地址
const publicCors = cors({
  origin: '*',
  methods: ['GET'],
});

// 私有接口 - 限制源地址
const privateCors = cors({
  origin: ['https://app.example.com'],
  credentials: true,
});

// Webhook 接口 - 指定源地址
const webhookCors = cors({
  origin: ['https://stripe.com', 'https://github.com'],
  methods: ['POST'],
});

router.get('/public/data', publicCors, publicDataHandler);
router.post('/private/data', privateCors, privateDataHandler);
router.post('/webhooks/stripe', webhookCors, stripeWebhookHandler);

export default router;

Next.js Configuration

Next.js 配置

Middleware CORS

中间件级 CORS 配置

typescript
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const allowedOrigins = [
  'https://app.example.com',
  'https://admin.example.com',
];

if (process.env.NODE_ENV === 'development') {
  allowedOrigins.push('http://localhost:3000');
}

export function middleware(request: NextRequest) {
  const origin = request.headers.get('origin');
  const isApiRoute = request.nextUrl.pathname.startsWith('/api');

  // Only apply CORS to API routes
  if (!isApiRoute) {
    return NextResponse.next();
  }

  // Handle preflight
  if (request.method === 'OPTIONS') {
    const response = new NextResponse(null, { status: 204 });

    if (origin && allowedOrigins.includes(origin)) {
      response.headers.set('Access-Control-Allow-Origin', origin);
      response.headers.set('Access-Control-Allow-Credentials', 'true');
      response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
      response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
      response.headers.set('Access-Control-Max-Age', '86400');
    }

    return response;
  }

  // Handle actual request
  const response = NextResponse.next();

  if (origin && allowedOrigins.includes(origin)) {
    response.headers.set('Access-Control-Allow-Origin', origin);
    response.headers.set('Access-Control-Allow-Credentials', 'true');
  }

  return response;
}

export const config = {
  matcher: '/api/:path*',
};
typescript
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const allowedOrigins = [
  'https://app.example.com',
  'https://admin.example.com',
];

if (process.env.NODE_ENV === 'development') {
  allowedOrigins.push('http://localhost:3000');
}

export function middleware(request: NextRequest) {
  const origin = request.headers.get('origin');
  const isApiRoute = request.nextUrl.pathname.startsWith('/api');

  // 仅对 API 路由应用 CORS 配置
  if (!isApiRoute) {
    return NextResponse.next();
  }

  // 处理预检请求
  if (request.method === 'OPTIONS') {
    const response = new NextResponse(null, { status: 204 });

    if (origin && allowedOrigins.includes(origin)) {
      response.headers.set('Access-Control-Allow-Origin', origin);
      response.headers.set('Access-Control-Allow-Credentials', 'true');
      response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
      response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
      response.headers.set('Access-Control-Max-Age', '86400');
    }

    return response;
  }

  // 处理实际请求
  const response = NextResponse.next();

  if (origin && allowedOrigins.includes(origin)) {
    response.headers.set('Access-Control-Allow-Origin', origin);
    response.headers.set('Access-Control-Allow-Credentials', 'true');
  }

  return response;
}

export const config = {
  matcher: '/api/:path*',
};

API Route CORS

API 路由的 CORS 配置

typescript
// app/api/data/route.ts
import { NextRequest, NextResponse } from 'next/server';

const allowedOrigins = ['https://app.example.com'];

function corsHeaders(origin: string | null) {
  const headers: Record<string, string> = {};

  if (origin && allowedOrigins.includes(origin)) {
    headers['Access-Control-Allow-Origin'] = origin;
    headers['Access-Control-Allow-Credentials'] = 'true';
  }

  return headers;
}

export async function OPTIONS(request: NextRequest) {
  const origin = request.headers.get('origin');

  return new NextResponse(null, {
    status: 204,
    headers: {
      ...corsHeaders(origin),
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
      'Access-Control-Max-Age': '86400',
    },
  });
}

export async function GET(request: NextRequest) {
  const origin = request.headers.get('origin');

  const data = { message: 'Hello' };

  return NextResponse.json(data, {
    headers: corsHeaders(origin),
  });
}

export async function POST(request: NextRequest) {
  const origin = request.headers.get('origin');

  // Verify origin for mutations
  if (!origin || !allowedOrigins.includes(origin)) {
    return new NextResponse('Forbidden', { status: 403 });
  }

  const body = await request.json();
  const result = await processData(body);

  return NextResponse.json(result, {
    headers: corsHeaders(origin),
  });
}
typescript
// app/api/data/route.ts
import { NextRequest, NextResponse } from 'next/server';

const allowedOrigins = ['https://app.example.com'];

function corsHeaders(origin: string | null) {
  const headers: Record<string, string> = {};

  if (origin && allowedOrigins.includes(origin)) {
    headers['Access-Control-Allow-Origin'] = origin;
    headers['Access-Control-Allow-Credentials'] = 'true';
  }

  return headers;
}

export async function OPTIONS(request: NextRequest) {
  const origin = request.headers.get('origin');

  return new NextResponse(null, {
    status: 204,
    headers: {
      ...corsHeaders(origin),
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
      'Access-Control-Max-Age': '86400',
    },
  });
}

export async function GET(request: NextRequest) {
  const origin = request.headers.get('origin');

  const data = { message: 'Hello' };

  return NextResponse.json(data, {
    headers: corsHeaders(origin),
  });
}

export async function POST(request: NextRequest) {
  const origin = request.headers.get('origin');

  // 对修改请求验证源地址
  if (!origin || !allowedOrigins.includes(origin)) {
    return new NextResponse('Forbidden', { status: 403 });
  }

  const body = await request.json();
  const result = await processData(body);

  return NextResponse.json(result, {
    headers: corsHeaders(origin),
  });
}

Fastify Configuration

Fastify 配置

typescript
// plugins/cors.ts
import fastifyCors from '@fastify/cors';
import { FastifyInstance } from 'fastify';

export async function configureCors(fastify: FastifyInstance) {
  await fastify.register(fastifyCors, {
    origin: (origin, callback) => {
      const allowedOrigins = [
        'https://app.example.com',
        'https://admin.example.com',
      ];

      if (!origin || allowedOrigins.includes(origin)) {
        callback(null, true);
      } else {
        callback(new Error('Not allowed'), false);
      }
    },
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowedHeaders: ['Content-Type', 'Authorization'],
    exposedHeaders: ['X-Request-ID'],
    credentials: true,
    maxAge: 86400,
    preflight: true,
    strictPreflight: true,
  });
}
typescript
// plugins/cors.ts
import fastifyCors from '@fastify/cors';
import { FastifyInstance } from 'fastify';

export async function configureCors(fastify: FastifyInstance) {
  await fastify.register(fastifyCors, {
    origin: (origin, callback) => {
      const allowedOrigins = [
        'https://app.example.com',
        'https://admin.example.com',
      ];

      if (!origin || allowedOrigins.includes(origin)) {
        callback(null, true);
      } else {
        callback(new Error('Not allowed'), false);
      }
    },
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowedHeaders: ['Content-Type', 'Authorization'],
    exposedHeaders: ['X-Request-ID'],
    credentials: true,
    maxAge: 86400,
    preflight: true,
    strictPreflight: true,
  });
}

Dynamic Origin Validation

动态源地址验证

typescript
// lib/cors/validator.ts
interface CorsConfig {
  allowedOrigins: string[];
  allowedPatterns: RegExp[];
  allowSubdomains: string[];
}

const config: CorsConfig = {
  allowedOrigins: [
    'https://app.example.com',
    'https://admin.example.com',
  ],
  allowedPatterns: [
    /^https:\/\/.*\.vercel\.app$/,
    /^https:\/\/.*\.netlify\.app$/,
  ],
  allowSubdomains: [
    'example.com', // Allows *.example.com
  ],
};

export function isOriginAllowed(origin: string): boolean {
  // Check exact match
  if (config.allowedOrigins.includes(origin)) {
    return true;
  }

  // Check patterns
  for (const pattern of config.allowedPatterns) {
    if (pattern.test(origin)) {
      return true;
    }
  }

  // Check subdomains
  for (const domain of config.allowSubdomains) {
    if (origin.endsWith(`.${domain}`) || origin === `https://${domain}`) {
      return true;
    }
  }

  return false;
}

// Usage in middleware
app.use((req, res, next) => {
  const origin = req.headers.origin;

  if (origin && isOriginAllowed(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Vary', 'Origin');
  }

  next();
});
typescript
// lib/cors/validator.ts
interface CorsConfig {
  allowedOrigins: string[];
  allowedPatterns: RegExp[];
  allowSubdomains: string[];
}

const config: CorsConfig = {
  allowedOrigins: [
    'https://app.example.com',
    'https://admin.example.com',
  ],
  allowedPatterns: [
    /^https:\/\/.*\.vercel\.app$/,
    /^https:\/\/.*\.netlify\.app$/,
  ],
  allowSubdomains: [
    'example.com', // 允许所有 *.example.com 子域名
  ],
};

export function isOriginAllowed(origin: string): boolean {
  // 检查精确匹配
  if (config.allowedOrigins.includes(origin)) {
    return true;
  }

  // 检查正则匹配
  for (const pattern of config.allowedPatterns) {
    if (pattern.test(origin)) {
      return true;
    }
  }

  // 检查子域名
  for (const domain of config.allowSubdomains) {
    if (origin.endsWith(`.${domain}`) || origin === `https://${domain}`) {
      return true;
    }
  }

  return false;
}

// 在中间件中使用
app.use((req, res, next) => {
  const origin = req.headers.origin;

  if (origin && isOriginAllowed(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Vary', 'Origin');
  }

  next();
});

Credentials and Cookies

凭据与 Cookie

typescript
// Important: When using credentials
// 1. Cannot use Access-Control-Allow-Origin: *
// 2. Must specify exact origin
// 3. Must set Access-Control-Allow-Credentials: true

// Server
app.use(cors({
  origin: 'https://app.example.com', // Must be exact, not *
  credentials: true,
}));

// Client (fetch)
fetch('https://api.example.com/data', {
  credentials: 'include', // Required for cookies
  headers: {
    'Content-Type': 'application/json',
  },
});

// Client (axios)
axios.defaults.withCredentials = true;
typescript
// 重要提示：当使用凭据时
// 1. 不能设置 Access-Control-Allow-Origin: *
// 2. 必须指定精确的源地址
// 3. 必须设置 Access-Control-Allow-Credentials: true

// 服务器端配置
app.use(cors({
  origin: 'https://app.example.com', // 必须是精确地址，不能用 *
  credentials: true,
}));

// 客户端（fetch）
fetch('https://api.example.com/data', {
  credentials: 'include', // 携带 Cookie 必须设置
  headers: {
    'Content-Type': 'application/json',
  },
});

// 客户端（axios）
axios.defaults.withCredentials = true;

Security Headers Companion

安全请求头配套配置

typescript
// middleware/security.ts
import helmet from 'helmet';
import { Express } from 'express';

export function configureSecurityHeaders(app: Express) {
  app.use(helmet({
    crossOriginResourcePolicy: { policy: 'cross-origin' },
    crossOriginOpenerPolicy: { policy: 'same-origin-allow-popups' },
    crossOriginEmbedderPolicy: false, // May conflict with third-party resources
  }));

  // Additional headers
  app.use((req, res, next) => {
    // Prevent clickjacking
    res.setHeader('X-Frame-Options', 'SAMEORIGIN');

    // Prevent MIME sniffing
    res.setHeader('X-Content-Type-Options', 'nosniff');

    // XSS protection
    res.setHeader('X-XSS-Protection', '1; mode=block');

    // Referrer policy
    res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');

    next();
  });
}
typescript
// middleware/security.ts
import helmet from 'helmet';
import { Express } from 'express';

export function configureSecurityHeaders(app: Express) {
  app.use(helmet({
    crossOriginResourcePolicy: { policy: 'cross-origin' },
    crossOriginOpenerPolicy: { policy: 'same-origin-allow-popups' },
    crossOriginEmbedderPolicy: false, // 可能与第三方资源冲突
  }));

  // 额外安全请求头
  app.use((req, res, next) => {
    // 防止点击劫持
    res.setHeader('X-Frame-Options', 'SAMEORIGIN');

    // 防止 MIME 类型嗅探
    res.setHeader('X-Content-Type-Options', 'nosniff');

    // XSS 防护
    res.setHeader('X-XSS-Protection', '1; mode=block');

    // 引用策略
    res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');

    next();
  });
}

Testing CORS

CORS 测试

typescript
// tests/cors.test.ts
import request from 'supertest';
import { app } from '../src/app';

describe('CORS', () => {
  it('allows requests from allowed origins', async () => {
    const response = await request(app)
      .get('/api/data')
      .set('Origin', 'https://app.example.com');

    expect(response.headers['access-control-allow-origin']).toBe('https://app.example.com');
  });

  it('blocks requests from disallowed origins', async () => {
    const response = await request(app)
      .get('/api/data')
      .set('Origin', 'https://evil.com');

    expect(response.headers['access-control-allow-origin']).toBeUndefined();
  });

  it('handles preflight requests', async () => {
    const response = await request(app)
      .options('/api/data')
      .set('Origin', 'https://app.example.com')
      .set('Access-Control-Request-Method', 'POST')
      .set('Access-Control-Request-Headers', 'Content-Type');

    expect(response.status).toBe(204);
    expect(response.headers['access-control-allow-methods']).toContain('POST');
  });

  it('includes credentials header when configured', async () => {
    const response = await request(app)
      .get('/api/data')
      .set('Origin', 'https://app.example.com');

    expect(response.headers['access-control-allow-credentials']).toBe('true');
  });
});
typescript
// tests/cors.test.ts
import request from 'supertest';
import { app } from '../src/app';

describe('CORS', () => {
  it('允许来自授权源地址的请求', async () => {
    const response = await request(app)
      .get('/api/data')
      .set('Origin', 'https://app.example.com');

    expect(response.headers['access-control-allow-origin']).toBe('https://app.example.com');
  });

  it('阻止来自未授权源地址的请求', async () => {
    const response = await request(app)
      .get('/api/data')
      .set('Origin', 'https://evil.com');

    expect(response.headers['access-control-allow-origin']).toBeUndefined();
  });

  it('正确处理预检请求', async () => {
    const response = await request(app)
      .options('/api/data')
      .set('Origin', 'https://app.example.com')
      .set('Access-Control-Request-Method', 'POST')
      .set('Access-Control-Request-Headers', 'Content-Type');

    expect(response.status).toBe(204);
    expect(response.headers['access-control-allow-methods']).toContain('POST');
  });

  it('配置凭据时返回对应请求头', async () => {
    const response = await request(app)
      .get('/api/data')
      .set('Origin', 'https://app.example.com');

    expect(response.headers['access-control-allow-credentials']).toBe('true');
  });
});

Common Patterns

常见配置模式

typescript
// Pattern 1: Development vs Production
const corsOptions = {
  origin: process.env.NODE_ENV === 'production'
    ? ['https://app.example.com']
    : [/localhost/],
};

// Pattern 2: Environment-based configuration
const corsOptions = {
  origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
};

// Pattern 3: Wildcard subdomain
const corsOptions = {
  origin: (origin, callback) => {
    if (!origin || /\.example\.com$/.test(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed'));
    }
  },
};
typescript
// 模式 1：开发环境 vs 生产环境
const corsOptions = {
  origin: process.env.NODE_ENV === 'production'
    ? ['https://app.example.com']
    : [/localhost/],
};

// 模式 2：基于环境变量的配置
const corsOptions = {
  origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
};

// 模式 3：通配符子域名
const corsOptions = {
  origin: (origin, callback) => {
    if (!origin || /\.example\.com$/.test(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed'));
    }
  },
};

Best Practices

最佳实践

  1. Never use 
    *
    with credentials    : Use specific origins
  2. Validate dynamically: Check origins at runtime
  3. Use 
    Vary: Origin
    : For caching correctness
  4. Limit methods: Only allow necessary HTTP methods
  5. Limit headers: Only expose necessary headers
  6. Set Max-Age: Cache preflight responses
  7. Log blocked requests: Monitor for issues
  8. Test thoroughly: Cover all scenarios
  1. 不要在使用凭据时用 
    *
    ：使用具体的源地址
  2. 动态验证源地址：在运行时检查源地址合法性
  3. 添加 
    Vary: Origin
    请求头    ：确保缓存正确性
  4. 限制请求方法：只允许必要的 HTTP 方法
  5. 限制请求头：只暴露必要的响应头
  6. 设置 Max-Age：缓存预检请求响应
  7. 记录被阻止的请求：监控配置问题
  8. 全面测试：覆盖所有场景

Output Checklist

配置检查清单

Every CORS configuration should include:
  • Specific allowed origins (not wildcard with credentials)
  • Proper preflight handling (OPTIONS)
  • Credentials configuration
  • Allowed methods specification
  • Allowed headers list
  • Exposed headers configuration
  • Max-Age for preflight caching
  • Vary: Origin header
  • Development origin handling
  • Error handling for blocked requests
每个 CORS 配置都应包含以下内容：
  • 具体的授权源地址（使用凭据时不能用通配符）
  • 正确的预检请求处理（OPTIONS 方法）
  • 凭据配置
  • 允许的请求方法说明
  • 允许的请求头列表
  • 暴露的响应头配置
  • 预检请求缓存的 Max-Age 设置
  • Vary: Origin 请求头
  • 开发环境源地址处理
  • 被阻止请求的错误处理