1. 从一次真实的接口调试失败说起那天下午我正在调试一个前后端分离的项目。前端用Vue跑在localhost:8080后端用Spring Boot跑在localhost:8081。一个简单的用户列表查询接口前端代码写得清清楚楚axios的配置也检查了好几遍但每次点击按钮浏览器控制台就弹出一个刺眼的红色错误Access to XMLHttpRequest at http://localhost:8081/api/users from origin http://localhost:8080 has been blocked by CORS policy: No Access-Control-Allow-Origin header is present on the requested resource.相信很多开发者无论是前端、后端还是全栈对这个错误信息都再熟悉不过了。它就像一堵无形的墙横亘在本地开发、联调测试甚至生产环境部署的各个环节。这堵墙的名字就是同源策略而CORSCross-Origin Resource Sharing跨域资源共享则是官方为我们开的一扇“门”。但为什么要有这堵墙这扇门怎么开才安全开错了又会有什么风险今天我就结合自己踩过的无数个坑从原理到实战把CORS这件事彻底讲透让你下次再遇到时不仅能快速解决更能明白背后的所以然。2. 同源策略浏览器安全体系的基石在深入CORS之前我们必须先理解它的对立面——同源策略。这不是浏览器的“故意刁难”而是现代Web安全的生命线。2.1 什么是“源”一个被误解的概念“同源”指的是两个URL的协议Protocol、域名Host和端口Port必须完全相同。只要有一个不同就是“跨源”Cross-Origin也就是我们常说的“跨域”。举个例子https://www.example.com/page.html与https://www.example.com/api/data同源协议、域名、端口都相同。https://www.example.com与http://www.example.com不同源协议不同https vs http。https://www.example.com与https://api.example.com不同源域名不同主域 vs 子域。https://www.example.com:80与https://www.example.com:443不同源端口不同80 vs 443即使80端口通常省略。这里有一个常见的误解很多人认为“不同子域名”不算跨域或者“同一个公司的不同服务”不算跨域。从浏览器的安全视角看这完全是跨域。www.example.com和api.example.com对于浏览器来说就是两个完全独立、互不信任的“源”。2.2 同源策略限制了哪些操作同源策略主要限制了三类行为DOM访问限制来自不同源的脚本无法读取或修改另一个源的页面DOM。这防止了恶意网站通过iframe嵌入银行页面并窃取输入信息。网络请求限制通常通过XMLHttpRequest或Fetch API发起的跨源HTTP请求会被浏览器拦截。这正是我们最常见的CORS错误场景。客户端存储访问限制Cookie、LocalStorage、IndexedDB等数据默认只能被同源页面访问。为什么要有这些限制想象一个场景你登录了mail.example.com的邮箱然后不小心访问了一个恶意网站。如果没有同源策略这个恶意网站的脚本可以偷偷向mail.example.com发起请求因为你的浏览器会自动携带邮箱域的Cookie恶意脚本就能以你的身份读取邮件、发送邮件造成严重的安全问题。同源策略从根本上杜绝了这种“借刀杀人”式的攻击。3. CORS机制详解浏览器与服务器的“三次握手”理解了同源策略的“墙”我们再看CORS这扇“门”。CORS是一套W3C标准它允许服务器声明哪些“外源”可以访问自己的资源。整个过程不是浏览器单方面决定的而是浏览器和服务器之间的一次精密协作对于可能“写数据”的复杂请求甚至是一次“三次握手”。3.1 简单请求与预检请求关键分水岭浏览器将跨域请求分为两类简单请求和非简单请求需预检的请求。区分它们至关重要因为处理逻辑完全不同。简单请求必须同时满足以下所有条件请求方法为GET、HEAD、POST之一。请求头仅包含以下集合Accept、Accept-Language、Content-Language、Content-Type且值仅限于application/x-www-form-urlencoded、multipart/form-data、text/plain。请求中的任意XMLHttpRequestUpload对象均没有注册任何事件监听器。请求中没有使用ReadableStream对象。对于简单请求浏览器会直接发出请求但在请求头中自动添加一个Origin字段标明请求来自哪个源如Origin: http://localhost:8080。服务器收到后需要在响应头中包含Access-Control-Allow-Origin其值要么是请求头中Origin的值要么是*表示允许任何源。浏览器看到这个响应头才会把响应内容交给前端JavaScript否则就报CORS错误。非简单请求预检请求则复杂得多。当请求不满足简单请求的条件时例如使用了PUT、DELETE方法或Content-Type为application/json浏览器不会直接发出真正的请求而是先发起一个OPTIONS方法的预检请求。这个OPTIONS请求就像一次“事前询问”它携带三个关键头Origin请求来源。Access-Control-Request-Method真实请求将使用的方法如PUT。Access-Control-Request-Headers真实请求将携带的自定义头如X-Custom-Header。服务器必须响应这个预检请求通过响应头来回答浏览器的“询问”Access-Control-Allow-Origin允许的源。Access-Control-Allow-Methods允许的真实请求方法。Access-Control-Allow-Headers允许的真实请求头。Access-Control-Max-Age本次预检响应的有效期秒在此期间内同一请求无需再次预检。只有预检请求的响应通过了浏览器的检查浏览器才会发出真实的请求。整个流程如下图所示以PUT /api/data且Content-Type: application/json为例浏览器 (http://localhost:8080) 服务器 (http://localhost:8081) | | | --- OPTIONS /api/data ------------ | | Origin: http://localhost:8080 | | Access-Control-Request-Method: PUT | | Access-Control-Request-Headers: content-type | | | | --- 200 OK ----------------------- | | Access-Control-Allow-Origin: http://localhost:8080 | Access-Control-Allow-Methods: PUT, POST, GET | Access-Control-Allow-Headers: content-type | Access-Control-Max-Age: 86400 | | | --- PUT /api/data (真实请求) ------ | | Origin: http://localhost:8080 | | Content-Type: application/json | | { name: test } | | | | --- 200 OK ----------------------- | | Access-Control-Allow-Origin: http://localhost:8080 | { id: 1 } |注意很多开发者在本地用Postman、Curl等工具测试接口正常但一到浏览器就报错根本原因就是这些工具不会像浏览器一样执行同源策略和预检请求。服务器可能根本没处理OPTIONS请求导致预检失败。3.2 核心响应头字段深度解析服务器通过一系列以Access-Control-开头的响应头来控制CORS行为。理解每一个字段的含义和陷阱是正确配置的关键。Access-Control-Allow-Origin(必选)指定允许访问该资源的外源URI。值可以是具体的源如https://www.example.com也可以是通配符*。但使用*需极度谨慎它意味着任何网站都可以通过前端JavaScript读取此响应。如果响应中包含敏感信息如用户数据、凭证这将极其危险。此外当请求需要携带凭证withCredentials为true时Access-Control-Allow-Origin不能设为*必须指定明确的源。Access-Control-Allow-Credentials(可选)布尔值。当设置为true时表示允许浏览器在跨域请求中携带凭证信息如Cookie、HTTP认证和客户端SSL证书。前端需要在XMLHttpRequest或Fetch中设置withCredentials true。重要限制当此字段为true时Access-Control-Allow-Origin不能为*必须是一个明确的源。Access-Control-Allow-Methods(预检请求必选)用于响应预检请求列出真实请求允许使用的HTTP方法。如果服务器支持GET,POST,PUT则应返回Access-Control-Allow-Methods: GET, POST, PUT。常见错误是只写了真实请求的方法导致其他合法的跨域方法也被禁止。Access-Control-Allow-Headers(预检请求可选)用于响应预检请求列出真实请求允许携带的自定义请求头。例如前端请求头里有X-Auth-Token服务器就必须在响应中包含Access-Control-Allow-Headers: X-Auth-Token。一个巨坑像Content-Type、Authorization这些“简单请求头”之外的都需要在这里声明。很多人配置了CORS还是报错就是因为漏掉了这个头。Access-Control-Max-Age(可选)指定预检请求的结果可以被缓存多久秒。例如Access-Control-Max-Age: 86400表示缓存24小时。合理设置可以避免对同一接口频繁发送预检请求提升性能。Access-Control-Expose-Headers(可选)默认情况下前端JavaScript只能访问CORS安全响应头Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma。如果你在响应头中设置了自定义头如X-Total-Count用于分页并希望前端能通过getResponseHeader()读取就必须在此字段中暴露它Access-Control-Expose-Headers: X-Total-Count。4. 后端实战主流框架的CORS配置与避坑指南理论懂了关键在实操。不同后端技术栈的配置方式各异但核心都是设置上面那些响应头。下面以几个最常用的框架为例。4.1 Spring Boot (Java) 配置注解与过滤器的选择在Spring Boot中最优雅的方式是使用CrossOrigin注解或全局配置。方法一使用CrossOrigin注解控制器级别RestController RequestMapping(/api) public class UserController { CrossOrigin(origins http://localhost:8080) // 允许特定源 GetMapping(/users) public ListUser getUsers() { // ... 业务逻辑 } CrossOrigin(origins *) // 允许所有源不推荐用于生产 PostMapping(/users) public User createUser(RequestBody User user) { // ... 业务逻辑 } }这种方式灵活但需要在每个控制器或方法上添加维护起来麻烦。方法二全局配置推荐通过一个配置类实现WebMvcConfigurer接口这是生产环境最常用的方式。Configuration public class WebConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) // 匹配的路径 .allowedOrigins(https://www.yourfrontend.com, http://localhost:8080) // 允许的源多个用逗号隔开 .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) // 允许的方法 .allowedHeaders(*) // 允许所有头或指定如 Content-Type, Authorization .exposedHeaders(X-Total-Count) // 暴露自定义头 .allowCredentials(true) // 允许凭证 .maxAge(3600L); // 预检请求缓存1小时 } }踩坑提醒如果你同时使用了Spring Security上述配置可能会被Security的过滤器链覆盖而失效。此时需要在Spring Security的配置中显式启用CORSEnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Override protected void configure(HttpSecurity http) throws Exception { http.cors() // 启用CORS配置 .and() // ... 其他安全配置 } Bean CorsConfigurationSource corsConfigurationSource() { CorsConfiguration configuration new CorsConfiguration(); configuration.setAllowedOrigins(Arrays.asList(https://www.yourfrontend.com)); configuration.setAllowedMethods(Arrays.asList(GET,POST,PUT,DELETE,OPTIONS)); configuration.setAllowCredentials(true); configuration.addExposedHeader(X-Total-Count); UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration(/api/**, configuration); return source; } }4.2 Node.js (Express) 配置中间件的正确用法在Express中使用cors这个官方中间件是标准做法。npm install corsconst express require(express); const cors require(cors); const app express(); // 1. 最简单也是最危险的用法允许所有跨域请求 // app.use(cors()); // 2. 生产环境推荐配置具体的CORS选项 const corsOptions { origin: function (origin, callback) { // 允许的源列表 const allowedOrigins [https://www.yourfrontend.com, http://localhost:8080]; // 如果是允许的源或者请求没有Origin头如移动端、curl if (!origin || allowedOrigins.indexOf(origin) ! -1) { callback(null, true); } else { callback(new Error(Not allowed by CORS)); } }, methods: [GET, POST, PUT, DELETE, OPTIONS], allowedHeaders: [Content-Type, Authorization, X-Requested-With], exposedHeaders: [X-Total-Count], credentials: true, // 允许携带凭证 maxAge: 3600 // 预检请求缓存1小时 }; app.use(cors(corsOptions)); // 你的路由 app.get(/api/users, (req, res) { res.json([{id: 1, name: Alice}]); }); app.listen(8081);关键点origin配置项可以是一个函数这给了我们极大的灵活性。比如你可以根据环境变量动态设置允许的源或者在开发环境下允许所有本地源。4.3 Nginx反向代理配置从源头“消灭”跨域对于生产环境一个更常见且安全的做法是使用Nginx或Apache等反向代理让前端和后端在同一个“源”下。这样浏览器看到的是同源请求从根本上绕过了CORS问题。假设前端部署在https://www.example.com后端API在http://backend-server:3000。server { listen 443 ssl; server_name www.example.com; # 前端静态文件 location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } # 反向代理API请求到后端服务器 location /api/ { # 核心将请求代理到后端对浏览器而言请求源仍是 www.example.com proxy_pass http://backend-server:3000/; # 以下是一些重要的代理头设置确保后端能获取真实信息 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 如果后端仍需处理CORS例如被其他第三方前端调用则仍需设置CORS头 # add_header Access-Control-Allow-Origin https://www.example.com always; # add_header Access-Control-Allow-Credentials true always; # ... 其他CORS头 } }这种方案的优点是安全前端代码中无需暴露后端服务器的真实地址和端口。简化前端开发者无需关心CORS配置所有请求都发向同源。灵活可以在Nginx层统一做限流、缓存、SSL卸载、负载均衡等。5. 前端视角发起跨域请求的正确姿势与常见陷阱后端配置好了前端发起请求时也有不少注意事项。5.1 Fetch API 与 Axios 的配置差异使用原生Fetch API// 简单GET请求 fetch(https://api.other.com/data) .then(response response.json()) .then(data console.log(data)) .catch(error console.error(Error:, error)); // 需要携带凭证(Cookie)的复杂POST请求 fetch(https://api.other.com/data, { method: POST, headers: { Content-Type: application/json, X-Custom-Header: value }, body: JSON.stringify({ key: value }), credentials: include // 关键携带凭证 }) .then(response { // 读取暴露的自定义头 const totalCount response.headers.get(X-Total-Count); return response.json(); }) .then(data console.log(data));使用Axios更常用import axios from axios; // 创建一个配置了基地址和默认凭证的实例 const apiClient axios.create({ baseURL: https://api.other.com, withCredentials: true, // 关键允许携带凭证 headers: { Content-Type: application/json } }); // 发起请求 apiClient.post(/data, { key: value }) .then(response { console.log(response.data); // Axios会自动将暴露的响应头放在 response.headers 中 }) .catch(error { // 注意CORS错误通常在error.response为undefined时发生属于网络层错误 if (error.response) { // 请求已发出服务器返回了错误状态码 console.log(error.response.status); } else if (error.request) { // 请求已发出但无响应如网络错误、CORS拦截 console.log(No response received:, error.request); } else { // 请求配置出错 console.log(Error setting up request:, error.message); } });5.2 开发环境下的代理配置Vue/React的解决方案在本地开发时前端运行在localhost:3000后端在localhost:8080跨域问题不可避免。手动配置后端CORS固然可以但更便捷的方式是利用前端构建工具如Vue CLI、Create React App提供的开发服务器代理功能。Vue CLI (vue.config.js):module.exports { devServer: { proxy: { /api: { // 匹配所有以 /api 开头的请求 target: http://localhost:8080, // 后端服务器地址 changeOrigin: true, // 修改请求头中的Host为目标URL的origin pathRewrite: { ^/api: // 重写路径去掉 /api 前缀可选取决于后端路由 } } } } };配置后前端代码中请求/api/users开发服务器会将其代理到http://localhost:8080/users浏览器看到的是同源请求。Create React App (package.json 或 setupProxy.js):在package.json中直接添加proxy: http://localhost:8080或者创建src/setupProxy.js进行更精细的配置const { createProxyMiddleware } require(http-proxy-middleware); module.exports function(app) { app.use( /api, createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true, }) ); };实操心得开发环境用代理生产环境用Nginx反向代理这是最清晰、最安全的架构。尽量避免在开发和生产环境使用同一套“允许所有源(*)”的CORS配置这会在无形中降低你的安全意识。6. 高级话题与疑难杂症排查即使配置看起来正确CORS问题依然可能以各种诡异的形式出现。下面是一些高级场景和排查思路。6.1 携带Cookie凭证时的“双限制”问题这是CORS中最容易出错的地方之一。当你的请求需要携带Cookie比如Session认证时必须满足两个条件服务器响应头必须包含Access-Control-Allow-Credentials: true并且Access-Control-Allow-Origin必须是具体的源不能是*。前端请求必须设置withCredentials: trueFetch API或axios.defaults.withCredentials trueAxios。如果只满足一个浏览器依然会报错。错误信息通常是The value of the Access-Control-Allow-Origin header in the response must not be the wildcard * when the requests credentials mode is include.6.2 预检请求OPTIONS的缓存与性能对于频繁发起的复杂跨域请求如上传文件每次请求前都发一个OPTIONS预检请求会严重影响性能。解决方案是让服务器在响应预检请求时设置一个较长的Access-Control-Max-Age头例如8640024小时。这样同一浏览器在有效期内对同一资源的相同请求方法就不会再发送预检请求。6.3 非简单请求头导致的“隐形”预检你以为你的请求是GET应该是简单请求不一定。如果你在请求头里添加了一个自定义头比如X-Auth-Token那么这个请求就变成了非简单请求会触发预检。排查时一定要打开浏览器的“网络(Network)”面板查看是否有一个OPTIONS请求先于你的真实请求发出并检查其响应头是否正确。6.4 服务器错误响应如500时的CORS头缺失一个常见的陷阱是当服务器端代码发生错误返回500状态码时如果错误处理中间件没有正确添加CORS响应头浏览器会因为收不到Access-Control-Allow-Origin头而报CORS错误从而掩盖了真实的服务器错误。这会让前端开发者误以为是CORS配置问题而实际上可能是后端逻辑bug。务必确保你的全局错误处理器也添加了CORS头。6.5 使用Charles、Fiddler等代理工具调试CORS当问题难以定位时代理工具是利器。以Charles为例你可以开启Map Local功能将线上API映射到本地文件方便修改响应头进行测试。如果使用Map Local时遇到CORS错误如热词中提到的charles maplocal 报cors通常是因为你映射的本地文件没有包含必要的CORS响应头。你需要在Charles的Rewrite功能中为这些响应动态添加Access-Control-Allow-Origin等头信息。直接查看完整的请求和响应头对比与预期是否一致。7. 安全考量CORS配置不当的潜在风险CORS是一把双刃剑配置不当会引入严重的安全漏洞。风险一过度宽松的Access-Control-Allow-Origin: *这是最常见的错误。它意味着任何网站都可以通过前端JavaScript读取你接口的返回数据。如果接口返回的是用户敏感信息、内部数据或管理功能就等于向整个互联网敞开了大门。生产环境绝对不要使用*必须严格指定允许的源列表。风险二过度宽松的Access-Control-Allow-Methods和Access-Control-Allow-Headers如果你允许了不必要的HTTP方法如PUT,DELETE或自定义头可能会扩大攻击面。攻击者可能利用这些方法进行未授权的数据修改。应遵循“最小权限原则”只开放业务需要的方法和头。风险三凭证与通配符源共存如前所述当Access-Control-Allow-Credentials: true时Access-Control-Allow-Origin不能为*。如果错误配置浏览器会阻止请求这实际上是一种安全保护。但有些服务器端框架或配置错误可能允许这种矛盾的情况这需要仔细检查。风险四反射Origin头导致的漏洞一种错误的配置模式是服务器简单地回显请求中的Origin头作为Access-Control-Allow-Origin的值。这看起来灵活但如果缺乏对Origin值的验证攻击者可以构造一个恶意网站其Origin头指向受害者的域名从而诱导用户浏览器向受害者网站发起携带凭证的请求CSRF的一种变体。正确的做法是服务器端维护一个可信的源白名单并与传入的Origin进行严格比对。我个人在项目中的实践是将CORS配置作为应用启动时的重要检查项并写入部署清单。对于允许的源我们通常通过环境变量注入确保开发、测试、生产环境隔离。同时在API网关或负载均衡器层面也会设置一层CORS策略作为防御纵深。
)
