环境与 CORS 管理

跨前后端技术栈管理环境变量、API URL 和 CORS 配置的模式。

标准环境模式

# .env.local（被 gitignore，用于本地开发）
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_WS_URL=ws://localhost:3001

# 预发布环境（在 Vercel/CI 中设置）
NEXT_PUBLIC_API_URL=https://api-staging.example.com

# 生产环境（在 Vercel/CI 中设置）
NEXT_PUBLIC_API_URL=https://api.example.com

环境变量规则

✅ API 基础地址来自环境变量——绝不硬编码
✅ 客户端变量前缀使用 NEXT_PUBLIC_（Next.js）或 VITE_（Vite）
✅ 后端 URL = 仅服务端使用的环境变量（用于 SSR 调用，不暴露给浏览器）
✅ 后端 CORS：按环境明确列出允许的域名列表

❌ 生产构建中绝不使用 localhost URL
❌ 绝不使用 NEXT_PUBLIC_ 前缀暴露仅后端使用的密钥
❌ 绝不提交 .env.local（提交含占位符的 .env.example）

CORS 配置

// 后端：感知环境的 CORS
const ALLOWED_ORIGINS = {
  development: ['http://localhost:3000', 'http://localhost:5173'],
  staging: ['https://staging.example.com'],
  production: ['https://example.com', 'https://www.example.com'],
};

app.use(cors({
  origin: ALLOWED_ORIGINS[process.env.NODE_ENV || 'development'],
  credentials: true,  // 需要用于 cookie（身份认证）
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
}));

常见问题

问题 1：「浏览器报 CORS 错误，但 Postman 能正常访问」

原因： CORS 是浏览器的安全机制。Postman/curl 会跳过它。

修复方法：

后端必须返回 Access-Control-Allow-Origin: https://your-frontend.com
涉及 Cookie/身份认证时，两端都需要设置 credentials: true
确认预检 OPTIONS 请求返回了正确的响应头

问题 2：「浏览器中环境变量为 undefined」

原因： 缺少客户端访问所需的 NEXT_PUBLIC_ 或 VITE_ 前缀。

修复方法： 客户端变量必须带有框架前缀。添加新环境变量后需要重新构建（它们在构建时被嵌入）。

问题 3：「本地能正常工作，预发布环境却失败」

原因： 域名不同，缺少预发布域的 CORS 配置。

修复方法： 将预发布域名添加到 ALLOWED_ORIGINS，确认部署平台已设置相应的环境变量。

2.4 KiB Raw Permalink Blame History Unescape Escape