AIStacker
Web

概览

CORS 报错调试 (跨域资源共享)

根据请求方式、自定义请求头、凭证模式与返回头,快速判断浏览器端的 CORS 是否会失败。

分类 hub

Web

问题

5

FAQ

3

Browser-side CORS triage

CORS Header Checker

Check whether a browser request will pass CORS based on the request method, custom headers, credentials mode, and the response headers your API currently returns.

Request context

Response headers

Verdict

Blocked by browser CORS policy

Preflight
Required
Requested headers
2
Allowed methods
3
Browser reasoning
Wildcard origin cannot be used with credentials

Browsers reject credentialed requests when Access-Control-Allow-Origin is '*' . Reflect the exact origin instead.

This request triggers a browser preflight

A browser will send OPTIONS first because the method or headers are outside the simple-request rules.

Credentials mode raises the CORS bar

If your frontend sends cookies or auth-bearing credentialed requests, the response headers must be much stricter than the public '*' pattern.

What usually fixes the mismatch
  • Reflect the exact frontend origin instead of returning * when credentials are involved.
  • Make sure the preflight response explicitly allows the real method and every custom request header the browser asked for.
  • Debug the browser request as two steps: preflight first, actual response second. Many teams only inspect the final API handler.

可以解决的问题

为什么我的 API 在 Postman 中正常工作,但在浏览器中却出现 CORS 错误?

浏览器在将响应暴露给 JavaScript 之前会强制执行 CORS,而 Postman 和 curl 则不会。这意味着 HTTP 响应在技术上可能是有效的,但在浏览器中仍然无法使用,因为返回的 CORS 响应头与请求源、方法、自定义请求头或凭据模式不匹配。

为什么 Access-Control-Allow-Origin 星号在携带凭据时会失败?

携带凭据的浏览器请求比公共匿名请求需要更严格的 CORS 约定。如果前端发送 Cookie 或其他凭据状态,浏览器将拒绝 `Access-Control-Allow-Origin: *`,并期望一个具体的允许源。

我如何知道到底是哪个请求头破坏了我的预检请求?

将浏览器想要发送的请求头与 `Access-Control-Allow-Headers` 逐一进行对比。失败通常是由单个缺失的自定义请求头引起的,例如 `authorization`、`x-api-key` 或从未被显式允许的 JSON 内容类型。

如果浏览器想要发送 PATCH 或 DELETE 但 Allow-Methods 不包含它会怎样?

浏览器会在预检阶段停止,并且永远不会发送真实请求。这就是为什么方法不匹配通常看起来像是后端路由坏了,即使路由处理器根本没有收到请求。

为什么在前端代码相同的情况下,CORS 在本地可以工作但在生产环境中失败?

生产环境通常会引入额外的代理、CDN、身份验证层或 Ingress 规则,这些规则会重写或删除本地服务器直接返回的请求头。前端代码可能相同,但浏览器看到的有效 CORS 响应头已不再相同。

典型使用流程

该工作流相关指南

Supporting guides that connect this tool to the broader category workflow.

打开分类 hub

是什么

CORS 报错调试 (跨域资源共享) 是什么

跨域资源共享 (CORS) 检查工具可以帮助您解决浏览器调试中最关键的问题:浏览器是否会允许此请求通过,还是会先在策略层拦截它?与其逐个查阅 CORS 响应头并靠猜,不如在一个地方对比请求方法、自定义请求头、凭据模式和返回的响应头。

这在 API 在 Postman 或 curl 中正常工作但在浏览器中失败的情况下尤其有用。在这种情况下,后端在传输层可能没问题,但由于 CORS 约定不完整或内部不一致,浏览器仍然会拦截响应。

如何使用

如何使用CORS 报错调试 (跨域资源共享)

输入前端源 (Origin)、请求方法以及浏览器将发送的任何自定义请求头。然后填写您的 API 或网关当前返回的响应头,特别是 `Access-Control-Allow-Origin`、`Access-Control-Allow-Methods` 和 `Access-Control-Allow-Headers`。

检查器将告诉您浏览器是否将该请求视为简单请求或预检请求、是否允许该来源,以及预检响应是否确实授予了您所要求的请求方法和请求头。

使用示例

使用示例

场景:
前端源: https://app.aistacker.dev
方法: GET
请求头: authorization, x-client-version
允许源: *
允许方法: GET, POST, OPTIONS
允许头: authorization, x-client-version
携带凭据: true

结果:
浏览器会拦截该请求,因为当 `Access-Control-Allow-Credentials` 为 `true` 时,`Access-Control-Allow-Origin` 不能使用通配符 `*`。请返回具体的源地址。

常见使用场景

常见使用场景

1. 解释为什么 API 调用在 curl 中成功但在浏览器中失败。

2. 检查某个自定义请求头是否是预检请求 (Preflight) 失败的真实原因。

3. 验证对于您使用的请求模式,`Access-Control-Allow-Origin: *` 是否安全。

4. 当网关重写或删除 CORS 响应头时,对比本地成功与生产环境失败的情况。

常见问题

常见问题

为什么请求在 Postman 中可以工作,但在浏览器中却失败了?v
Postman 和 curl 不受浏览器 CORS 强制执行模型的约束。服务器在 HTTP 层面可能响应成功,但如果返回的 CORS 响应头不满足浏览器对该请求的策略,浏览器仍会拦截响应。
是否每个跨域请求都会触发预检?v
不是。使用安全方法和简单请求头的简单请求可以跳过预检。一旦您引入自定义请求头、JSON 内容类型或非简单方法(如 PUT 或 PATCH),浏览器就更有可能先发送一个 OPTIONS 预检请求。
为什么当启用凭据时,通配符 Allow-Origin 会失效?v
当 `Access-Control-Allow-Origin` 为 `*` 时,浏览器会拒绝携带凭据的 CORS 响应。一旦涉及凭据,响应通常必须返回具体的允许源,而不是使用通配符模式。