Nginx中API跨域请求的错误监控与Sentry集成配置指南-Nginx-PHP中文网

真正的跨域错误监控必须从前端出发，因nginx无法捕获浏览器静默拦截、failed to fetch等客户端运行时错误；需前端用try/catch、axios拦截器、unhandledrejection统一捕获并上报至sentry，再结合nginx日志辅助归因。

nginx中api跨域请求的错误监控与sentry集成配置指南

在 Nginx 中直接处理 API 跨域请求的错误监控存在天然限制——Nginx 本身不执行 JavaScript，也不捕获前端发起的跨域失败（如 CORS 拒绝、预检失败、网络中断等），这些错误实际发生在浏览器端。因此，真正的跨域错误监控必须从前端出发，再通过合适的上报机制（如 Sentry）收集，并辅以 Nginx 日志作为后端侧的补充验证。

为什么不能只靠 Nginx 日志监控跨域错误

Nginx 日志（如 error_log 或 access_log）能记录：预检请求（OPTIONS）被拒绝、CORS 头未正确返回、源不匹配导致的 403/405 响应等服务端问题。但它无法记录以下典型跨域失败场景：

浏览器因缺少 Access-Control-Allow-Origin 等响应头而静默拦截响应（控制台报错但无 HTTP 状态码）
前端 fetch / axios 请求抛出 TypeError: Failed to fetch（常见于预检失败或网络策略拦截）
证书错误、DNS 失败、混合内容（HTTP/HTTPS）等非 HTTP 协议层问题
用户禁用 CORS 插件或使用特殊代理环境导致的本地调试异常

这些都属于客户端运行时错误，必须由前端 JavaScript 捕获并主动上报。

前端跨域错误的可靠捕获方式

在应用入口或请求封装层（如 Axios 拦截器）中统一监听和上报跨域相关异常：

对所有 API 请求使用 try/catch 包裹 fetch 或 Promise-based 请求库调用
检查响应状态：!response.ok 或 response.status >= 400，并读取 response.url 和 response.redirected 辅助判断是否跨域跳转失败
捕获全局未处理 Promise 拒绝：window.addEventListener('unhandledrejection', ...)，筛选含 fetch、Failed to fetch、CORS、NetworkError 等关键词的 reason
补充检查 navigator.onLine 和请求 URL 协议/域名，区分真实跨域问题与离线或配置错误

示例（Axios）：

axios.interceptors.response.use(
  res => res,
  error => {
    if (error.request && !error.response) {
      // 请求已发出但无响应（可能 CORS 预检失败、网络中断）
      Sentry.captureException(new Error(`CORS Network Error: ${error.request.url}`));
    } else if (error.response?.status === 0) {
      // 某些环境（如 iOS WebView）返回 status 0 表示跨域拒绝
      Sentry.captureException(new Error(`CORS Blocked: ${error.config.url}`));
    }
    throw error;
  }
);

Sentry 配置要点（聚焦跨域上下文）

让 Sentry 上报携带足够诊断信息，避免“看到错误却不知哪个接口、哪个域名、哪个浏览器出问题”：

在 Sentry.init() 中启用 tracingOptions: { trackComponents: true }（若用 React/Vue）便于定位组件级请求源
为每个上报添加 extra 字段：apiUrl、requestMethod、origin、referer、userAgent
设置 environment 和 release，区分测试/生产环境及版本，快速比对跨域策略变更影响
开启 sendDefaultPii: false，避免敏感 Header（如 Authorization）被意外上传

注意：Sentry 默认不采集请求 body 和响应内容，如需调试响应头缺失问题，可在捕获时手动附加 response.headers（需确保不含敏感字段）。

Nginx 侧可做的协同优化

虽不直接监控前端错误，但 Nginx 可增强可观测性，辅助归因：

在 location 块中记录 OPTIONS 请求及关键响应头：
log_format cors '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_origin" "$http_access_control_request_method"';

为 API 接口统一添加严格 CORS 头（避免漏配）：

add_header 'Access-Control-Allow-Origin' '$http_origin' always;<br>add_header 'Access-Control-Allow-Methods' 'GET,POST,PUT,DELETE,OPTIONS' always;<br>add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization' always;<br>add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;