跨域问题是每个前后端分离开发者都会遇到的“拦路虎”。本文将从浏览器同源策略讲起结合Python后端Django/Flask/FastAPI的实战配置帮你彻底搞懂CORS的原理与解决方案。彻底掌握前后端跨域问题Python后端实战指南文章目录彻底掌握前后端跨域问题Python后端实战指南前言第一章跨域问题本质剖析1.1 什么是同源策略1.2 为什么要有同源策略1.3 什么是跨域资源共享CORS1.4 两种跨域请求类型第二章Python后端CORS配置全攻略2.1 Django框架的CORS配置2.1.1 安装与基础配置2.1.2 允许所有来源开发环境专用2.1.3 指定允许的来源生产环境推荐2.1.4 高级配置选项2.1.5 Django Vue部署时的CSRF问题2.2 Flask框架的CORS配置2.2.1 安装与初始化2.2.2 全局CORS配置2.2.3 精细化配置2.2.4 使用装饰器进行单接口配置2.3 FastAPI框架的CORS配置2.3.1 安装FastAPI和Uvicorn2.3.2 配置CORS中间件2.3.3 动态来源配置2.4 三种Python框架CORS配置对比第三章前端开发环境代理解决方案3.1 Vite项目的代理配置3.2 Axios请求封装3.3 在Vue组件中使用3.4 开发代理vs生产CORS第四章生产环境部署与Nginx配置4.1 同源部署策略4.2 Nginx反向代理配置4.3 Docker Compose多服务部署第五章跨域疑难问题排查指南5.1 常见跨域错误信息及解读5.2 排查清单5.3 调试工具推荐第六章安全最佳实践6.1 切勿在生产环境使用通配符6.2 谨慎处理Cookie凭证6.3 合理设置预检请求缓存6.4 遵循最小权限原则6.5 与CSRF防护协同工作结语前言在前后端分离的开发模式日益普及的今天跨域资源访问CORSCross-Origin Resource Sharing问题几乎是每个开发者都会遇到的挑战。当你欢快地在Vue或React项目中调用后端API却看到浏览器控制台报出鲜红的跨域错误时那种挫败感想必很多人都经历过。本文将从跨域问题的本质出发深入浅出地讲解其原理并重点围绕Python后端框架Django、Flask、FastAPI给出详尽的解决方案。无论你是刚入门的新手还是经验丰富的开发者都能从中找到适合自己的跨域处理方案。第一章跨域问题本质剖析1.1 什么是同源策略在理解跨域之前我们首先要了解浏览器的同源策略Same-Origin Policy。这是浏览器施加的一种安全限制它规定只有在协议、域名、端口完全一致的情况下页面才能访问另一个页面的资源。举个简单的例子页面地址http://localhost:5173Vue项目默认端口API地址http://localhost:8080后端接口地址虽然域名都是localhost但端口不同5173 vs 8080这就构成了跨域。浏览器会拒绝前端页面访问这个API 。1.2 为什么要有同源策略同源策略的存在是为了保护用户的数据安全。如果没有这个限制恶意网站就可以通过脚本任意访问其他网站的敏感数据如Cookie、LocalStorage等 。比如你在浏览银行网站的同时打开了另一个恶意网站如果没有同源策略这个恶意网站就可能通过脚本获取你在银行网站的登录凭证。1.3 什么是跨域资源共享CORS为了解决合法的跨域需求W3C制定了跨域资源共享CORSCross-Origin Resource Sharing标准。CORS允许服务器声明哪些外部源可以访问其资源通过一套HTTP头信息来实现浏览器与服务器之间的跨域数据交互 。简单来说CORS就是服务器在HTTP响应头中告诉浏览器“我信任这个来源的请求放行吧。”1.4 两种跨域请求类型浏览器将CORS请求分为两类处理方式有所不同请求类型满足条件处理特点简单请求方法为GET、HEAD、POSTContent-Type仅限于application/x-www-form-urlencoded、multipart/form-data、text/plain浏览器直接发出请求在请求头中附加Origin字段服务器返回的响应头必须包含Access-Control-Allow-Origin预检请求不满足简单请求条件的请求如PUT、DELETE方法或Content-Type为application/json浏览器先发送OPTIONS请求询问服务器是否允许实际请求得到肯定答复后才发送真实请求理解这两种请求类型的区别非常重要因为在实际开发中我们最常用的Content-Type就是application/json这恰恰属于需要预检请求的情况。第二章Python后端CORS配置全攻略2.1 Django框架的CORS配置Django作为Python最流行的Web框架处理跨域问题通常借助于第三方库django-cors-headers。2.1.1 安装与基础配置pipinstalldjango-cors-headers安装完成后需要在Django项目的settings.py中进行配置 # settings.py# 注册应用INSTALLED_APPS[django.contrib.admin,django.contrib.auth,# ... 其他应用corsheaders,# 添加corsheaders]# 添加中间件注意位置要尽量靠前MIDDLEWARE[corsheaders.middleware.CorsMiddleware,# 应该放在最前面django.middleware.common.CommonMiddleware,# ... 其他中间件]2.1.2 允许所有来源开发环境专用在开发环境中为了快速调试可以暂时允许所有来源访问 # settings.py# 允许所有来源生产环境切勿使用CORS_ALLOW_ALL_ORIGINSTrue# Django 3.x及以上版本# 对于旧版本Django使用 CORS_ORIGIN_ALLOW_ALL True2.1.3 指定允许的来源生产环境推荐生产环境中应当严格指定允许访问的域名 # settings.py# 只允许特定域名访问CORS_ALLOWED_ORIGINS[https://example.com,https://sub.example.com,http://localhost:5173,# Vue开发服务器http://127.0.0.1:5173,http://localhost:8080,# 备用端口]# 如果需要支持正则表达式匹配如动态子域名CORS_ALLOWED_ORIGIN_REGEXES[r^https://\w\.example\.com$,]2.1.4 高级配置选项# settings.py# 允许携带Cookie跨域请求中携带身份凭证CORS_ALLOW_CREDENTIALSTrue# 默认为False# 允许的HTTP请求方法CORS_ALLOW_METHODS(DELETE,GET,OPTIONS,PATCH,POST,PUT,)# 允许的非标准HTTP请求头CORS_ALLOW_HEADERS(accept,authorization,content-type,user-agent,x-csrftoken,x-requested-with,# 可以添加自定义头my-custom-header,)# 预检请求的有效期秒减少预检请求次数CORS_PREFLIGHT_MAX_AGE86400# 24小时# 限制CORS头生效的URLCORS_URLS_REGEXr^/api/.*$# 只对/api/路径应用CORS2.1.5 Django Vue部署时的CSRF问题在DjangoVue的前后端分离项目中启用CORS后还需要注意CSRF保护的配置 # settings.py# 允许跨域携带CookieCORS_ALLOW_CREDENTIALSTrue# 信任的来源用于CSRF保护CSRF_TRUSTED_ORIGINS[http://localhost:5173,https://yourdomain.com,]2.2 Flask框架的CORS配置Flask作为轻量级Web框架可以通过flask-cors扩展轻松实现CORS支持。2.2.1 安装与初始化pipinstallflask-cors2.2.2 全局CORS配置最简单的配置方式是全局启用CORS fromflaskimportFlaskfromflask_corsimportCORS appFlask(__name__)CORS(app)# 允许所有来源访问所有路由app.route(/api/data)defget_data():return{message:Hello CORS!}2.2.3 精细化配置如果需要更精细的控制可以传入配置参数 fromflaskimportFlaskfromflask_corsimportCORS appFlask(__name__)# 配置CORS选项corsCORS(app,resources{r/api/*:{# 只对/api路径生效origins:[http://localhost:5173,https://example.com],methods:[GET,POST,PUT,DELETE],allow_headers:[Content-Type,Authorization],supports_credentials:True,# 允许携带Cookiemax_age:3600# 预检请求缓存时间},r/public/*:{origins:*,# 公开接口允许所有来源methods:[GET]}})app.route(/api/data)defget_data():return{message:Hello CORS!}app.route(/public/info)defpublic_info():return{message:This is public}2.2.4 使用装饰器进行单接口配置如果只需要个别接口支持跨域可以使用cross_origin装饰器 fromflaskimportFlask,jsonifyfromflask_corsimportcross_origin appFlask(__name__)app.route(/api/hello)cross_origin(originshttp://localhost:5173)defhello():returnjsonify({message:Hello World})app.route(/api/goodbye)# 不添加装饰器不支持跨域defgoodbye():returnjsonify({message:Goodbye World})2.3 FastAPI框架的CORS配置FastAPI作为新兴的异步框架内置了CORS中间件配置起来也非常简单。2.3.1 安装FastAPI和Uvicornpipinstallfastapi uvicorn2.3.2 配置CORS中间件FastAPI通过CORSMiddleware来处理跨域 fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddleware appFastAPI()# 配置CORSapp.add_middleware(CORSMiddleware,allow_origins[http://localhost:5173,https://example.com],# 允许的来源allow_credentialsTrue,# 允许携带Cookieallow_methods[*],# 允许所有方法allow_headers[*],# 允许所有请求头max_age3600,# 预检请求缓存时间)app.get(/api/data)asyncdefread_data():return{message:Hello from FastAPI}2.3.3 动态来源配置如果来源列表需要动态生成可以使用回调函数fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddlewarefromtypingimportList appFastAPI()# 从环境变量或数据库加载允许的来源defget_allowed_origins()-List[str]:# 这里可以从数据库读取配置return[http://localhost:5173,https://yourdomain.com]originsget_allowed_origins()app.add_middleware(CORSMiddleware,allow_originsorigins,allow_credentialsTrue,allow_methods[GET,POST,PUT,DELETE],allow_headers[Content-Type,Authorization],)2.4 三种Python框架CORS配置对比特性DjangoFlaskFastAPI主要库django-cors-headersflask-corsCORSMiddleware内置全局配置settings.py中配置CORS(app)app.add_middleware细粒度控制CORS_URLS_REGEXresources参数路径依赖配置携带CookieCORS_ALLOW_CREDENTIALSsupports_credentialsallow_credentials预检缓存CORS_PREFLIGHT_MAX_AGEmax_agemax_age第三章前端开发环境代理解决方案在开发环境中除了后端配置CORS外前端也可以通过代理服务器来规避跨域问题。这种方法的好处是不需要修改后端代码特别适合在联调阶段使用。3.1 Vite项目的代理配置Vue 3项目通常使用Vite作为构建工具可以通过配置vite.config.js实现代理 // vite.config.jsimport{defineConfig}fromviteimportvuefromvitejs/plugin-vueexportdefaultdefineConfig({plugins:[vue()],server:{proxy:{// 将以/api开头的请求代理到后端服务器/api:{target:http://localhost:8000,// 后端服务器地址changeOrigin:true,// 改变请求头中的Origin为目标地址rewrite:(path)path.replace(/^\/api/,),// 可选重写路径configure:(proxy,options){// 代理配置的回调可以添加日志等proxy.on(error,(err,req,res){console.log(proxy error,err);});}},// 多个代理规则/uploads:{target:http://localhost:8000,changeOrigin:true,}}}})理解rewrite的作用如果后端接口实际路径是http://localhost:8000/hello而前端希望用/api/hello调用就需要rewrite去掉/api前缀如果后端接口本身就带有/api前缀如http://localhost:8000/api/hello则不需要rewrite 。3.2 Axios请求封装结合代理配置Axios的请求可以这样封装 // src/utils/request.jsimportaxiosfromaxiosconstrequestaxios.create({baseURL:,// 由于代理配置可以留空或写/timeout:10000,withCredentials:true,// 允许携带Cookie如果需要})// 请求拦截器request.interceptors.request.use(config{// 添加token等认证信息consttokenlocalStorage.getItem(token)if(token){config.headers.AuthorizationBearer${token}}returnconfig},error{returnPromise.reject(error)})// 响应拦截器request.interceptors.response.use(response{returnresponse.data},error{// 统一错误处理console.error(请求错误:,error)returnPromise.reject(error)})exportdefaultrequest3.3 在Vue组件中使用// views/Example.vueimportrequestfrom/utils/requestexportdefault{methods:{asyncfetchData(){try{// 实际请求会被代理到 http://localhost:8000/helloconstdataawaitrequest.get(/api/hello)console.log(data)}catch(error){console.error(数据获取失败,error)}}}}3.4 开发代理vs生产CORS需要明确的是前端代理方案仅适用于开发环境。当项目构建并部署到生产环境时代理配置不会生效。生产环境仍然需要后端正确配置CORS或者通过Nginx等反向代理解决跨域 。方案适用环境优点缺点Vite代理开发环境配置简单无需修改后端仅开发环境有效后端CORS生产环境标准化解决方案安全可控需要后端配合Nginx代理生产环境无需修改应用代码统一入口需要运维知识第四章生产环境部署与Nginx配置在生产环境中除了后端配置CORS外还可以使用Nginx作为反向代理来解决跨域问题。这种方式可以实现前后端同源访问彻底规避跨域。4.1 同源部署策略最简单的方式是将前端静态文件和后端API部署在同一个域名的不同路径下 https://example.com/ # 前端页面 https://example.com/api/ # 后端API这种部署方式不存在跨域问题但要求前端路由不能与API路径冲突。4.2 Nginx反向代理配置如果前端和后端部署在不同服务器上可以通过Nginx反向代理将API请求转发到后端服务器 # /etc/nginx/sites-available/example.com server { listen 80; server_name example.com; # 前端静态文件 location / { root /var/www/frontend/dist; try_files $uri $uri/ /index.html; } # API代理 location /api/ { proxy_pass http://backend-server:8000/; # 后端服务器地址 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头 add_header Access-Control-Allow-Origin $http_origin always; add_header Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS always; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization always; add_header Access-Control-Allow-Credentials true always; # 处理预检请求 if ($request_method OPTIONS) { add_header Access-Control-Allow-Origin $http_origin always; add_header Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS always; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization always; add_header Access-Control-Allow-Credentials true always; add_header Content-Length 0; add_header Content-Type text/plain; return 204; } } }4.3 Docker Compose多服务部署对于使用Docker部署的项目可以通过docker-compose配置多个服务 # docker-compose.ymlversion:3.8services:backend:build:./backendcontainer_name:django_backendexpose:-8000environment:-DEBUGFalse-CORS_ALLOWED_ORIGINShttp://localhost,https://example.comnetworks:-app_networkfrontend:build:./frontendcontainer_name:vue_frontendports:-80:80depends_on:-backendnetworks:-app_networknginx:image:nginx:latestcontainer_name:nginx_proxyvolumes:-./nginx/conf.d:/etc/nginx/conf.dports:-80:80-443:443depends_on:-backend-frontendnetworks:-app_networknetworks:app_network:driver:bridge第五章跨域疑难问题排查指南5.1 常见跨域错误信息及解读错误信息可能原因解决方案No Access-Control-Allow-Origin header is present后端未配置CORS或配置不正确检查后端CORS配置确保返回了正确的响应头Response to preflight request doesnt pass access control check预检请求未通过确保OPTIONS请求正确处理返回了204状态码和允许头Credentials flag is true, but the Access-Control-Allow-Origin header is *携带凭证时不能使用通配符*将Access-Control-Allow-Origin设置为具体域名Multiple CORS header Access-Control-Allow-Origin not allowed响应头重复设置检查是否有多个地方同时设置CORS头5.2 排查清单当遇到跨域问题时可以按照以下清单逐一排查 确认请求URL正确性协议、域名、端口是否匹配预期路径是否正确检查CORS响应头Access-Control-Allow-Origin是否存在且正确Access-Control-Allow-Credentials是否设置为true如果需要携带CookieAccess-Control-Allow-Methods是否包含实际请求方法验证预检请求OPTIONS请求是否返回200或204状态码响应头是否完整检查凭证配置前端是否设置withCredentials: true或credentials: include后端是否设置Access-Control-Allow-Credentials: true是否同时使用通配符*和true不允许验证代理配置开发环境代理规则是否正确路径重写是否生效请求头是否正确传递5.3 调试工具推荐浏览器开发者工具查看Network面板中的请求和响应头Postman/Insomnia绕过浏览器限制测试APIcurl命令快速测试CORS头# 测试OPTIONS预检请求curl-XOPTIONS http://localhost:8000/api/data\-HOrigin: http://localhost:5173\-HAccess-Control-Request-Method: GET\-v# 测试实际请求curl-XGET http://localhost:8000/api/data\-HOrigin: http://localhost:5173\-v第六章安全最佳实践6.1 切勿在生产环境使用通配符将Access-Control-Allow-Origin设置为*虽然方便但会允许任何网站访问你的API存在严重安全风险。生产环境必须明确指定允许的来源列表 。6.2 谨慎处理Cookie凭证当设置allowCredentials(true)时必须注意 Access-Control-Allow-Origin不能为*Access-Control-Allow-Headers不能为*Cookie的SameSite属性可能需要设置为NoneHTTPS环境下6.3 合理设置预检请求缓存通过maxAge设置适当的预检请求缓存时间可以减少不必要的OPTIONS请求提升性能。一般建议设置为600到86400秒之间 。6.4 遵循最小权限原则只开放必要的HTTP方法和请求头不要盲目使用*。例如如果API只支持GET请求就应该限制Access-Control-Allow-Methods为GET。6.5 与CSRF防护协同工作启用CORS允许跨域携带Cookie时需要特别注意CSRF攻击防护。Django等框架提供了CSRF_TOKEN机制需要将前端域名添加到CSRF信任列表中 。结语跨域问题是前后端分离架构中的一道必经关卡理解其原理并掌握解决方案是每个Web开发者的基本功。通过本文的学习你应该已经掌握了跨域问题的本质浏览器的同源安全策略CORS的核心机制简单请求与预检请求Python三大框架的CORS配置方法开发环境的代理解决方案生产环境的Nginx部署策略安全最佳实践和问题排查技巧记住跨域不是Bug而是浏览器保护用户的安全机制。选择合适的方案、遵循安全规范就能在保证安全的前提下实现跨域资源共享。希望本文能帮助你在实际项目中游刃有余地应对跨域挑战转载声明本文原创转载请注明出处。
彻底掌握前后端跨域问题：Python后端实战指南
发布时间：2026/5/19 2:24:50
跨域问题是每个前后端分离开发者都会遇到的“拦路虎”。本文将从浏览器同源策略讲起结合Python后端Django/Flask/FastAPI的实战配置帮你彻底搞懂CORS的原理与解决方案。彻底掌握前后端跨域问题Python后端实战指南文章目录彻底掌握前后端跨域问题Python后端实战指南前言第一章跨域问题本质剖析1.1 什么是同源策略1.2 为什么要有同源策略1.3 什么是跨域资源共享CORS1.4 两种跨域请求类型第二章Python后端CORS配置全攻略2.1 Django框架的CORS配置2.1.1 安装与基础配置2.1.2 允许所有来源开发环境专用2.1.3 指定允许的来源生产环境推荐2.1.4 高级配置选项2.1.5 Django Vue部署时的CSRF问题2.2 Flask框架的CORS配置2.2.1 安装与初始化2.2.2 全局CORS配置2.2.3 精细化配置2.2.4 使用装饰器进行单接口配置2.3 FastAPI框架的CORS配置2.3.1 安装FastAPI和Uvicorn2.3.2 配置CORS中间件2.3.3 动态来源配置2.4 三种Python框架CORS配置对比第三章前端开发环境代理解决方案3.1 Vite项目的代理配置3.2 Axios请求封装3.3 在Vue组件中使用3.4 开发代理vs生产CORS第四章生产环境部署与Nginx配置4.1 同源部署策略4.2 Nginx反向代理配置4.3 Docker Compose多服务部署第五章跨域疑难问题排查指南5.1 常见跨域错误信息及解读5.2 排查清单5.3 调试工具推荐第六章安全最佳实践6.1 切勿在生产环境使用通配符6.2 谨慎处理Cookie凭证6.3 合理设置预检请求缓存6.4 遵循最小权限原则6.5 与CSRF防护协同工作结语前言在前后端分离的开发模式日益普及的今天跨域资源访问CORSCross-Origin Resource Sharing问题几乎是每个开发者都会遇到的挑战。当你欢快地在Vue或React项目中调用后端API却看到浏览器控制台报出鲜红的跨域错误时那种挫败感想必很多人都经历过。本文将从跨域问题的本质出发深入浅出地讲解其原理并重点围绕Python后端框架Django、Flask、FastAPI给出详尽的解决方案。无论你是刚入门的新手还是经验丰富的开发者都能从中找到适合自己的跨域处理方案。第一章跨域问题本质剖析1.1 什么是同源策略在理解跨域之前我们首先要了解浏览器的同源策略Same-Origin Policy。这是浏览器施加的一种安全限制它规定只有在协议、域名、端口完全一致的情况下页面才能访问另一个页面的资源。举个简单的例子页面地址http://localhost:5173Vue项目默认端口API地址http://localhost:8080后端接口地址虽然域名都是localhost但端口不同5173 vs 8080这就构成了跨域。浏览器会拒绝前端页面访问这个API 。1.2 为什么要有同源策略同源策略的存在是为了保护用户的数据安全。如果没有这个限制恶意网站就可以通过脚本任意访问其他网站的敏感数据如Cookie、LocalStorage等 。比如你在浏览银行网站的同时打开了另一个恶意网站如果没有同源策略这个恶意网站就可能通过脚本获取你在银行网站的登录凭证。1.3 什么是跨域资源共享CORS为了解决合法的跨域需求W3C制定了跨域资源共享CORSCross-Origin Resource Sharing标准。CORS允许服务器声明哪些外部源可以访问其资源通过一套HTTP头信息来实现浏览器与服务器之间的跨域数据交互 。简单来说CORS就是服务器在HTTP响应头中告诉浏览器“我信任这个来源的请求放行吧。”1.4 两种跨域请求类型浏览器将CORS请求分为两类处理方式有所不同请求类型满足条件处理特点简单请求方法为GET、HEAD、POSTContent-Type仅限于application/x-www-form-urlencoded、multipart/form-data、text/plain浏览器直接发出请求在请求头中附加Origin字段服务器返回的响应头必须包含Access-Control-Allow-Origin预检请求不满足简单请求条件的请求如PUT、DELETE方法或Content-Type为application/json浏览器先发送OPTIONS请求询问服务器是否允许实际请求得到肯定答复后才发送真实请求理解这两种请求类型的区别非常重要因为在实际开发中我们最常用的Content-Type就是application/json这恰恰属于需要预检请求的情况。第二章Python后端CORS配置全攻略2.1 Django框架的CORS配置Django作为Python最流行的Web框架处理跨域问题通常借助于第三方库django-cors-headers。2.1.1 安装与基础配置pipinstalldjango-cors-headers安装完成后需要在Django项目的settings.py中进行配置 # settings.py# 注册应用INSTALLED_APPS[django.contrib.admin,django.contrib.auth,# ... 其他应用corsheaders,# 添加corsheaders]# 添加中间件注意位置要尽量靠前MIDDLEWARE[corsheaders.middleware.CorsMiddleware,# 应该放在最前面django.middleware.common.CommonMiddleware,# ... 其他中间件]2.1.2 允许所有来源开发环境专用在开发环境中为了快速调试可以暂时允许所有来源访问 # settings.py# 允许所有来源生产环境切勿使用CORS_ALLOW_ALL_ORIGINSTrue# Django 3.x及以上版本# 对于旧版本Django使用 CORS_ORIGIN_ALLOW_ALL True2.1.3 指定允许的来源生产环境推荐生产环境中应当严格指定允许访问的域名 # settings.py# 只允许特定域名访问CORS_ALLOWED_ORIGINS[https://example.com,https://sub.example.com,http://localhost:5173,# Vue开发服务器http://127.0.0.1:5173,http://localhost:8080,# 备用端口]# 如果需要支持正则表达式匹配如动态子域名CORS_ALLOWED_ORIGIN_REGEXES[r^https://\w\.example\.com$,]2.1.4 高级配置选项# settings.py# 允许携带Cookie跨域请求中携带身份凭证CORS_ALLOW_CREDENTIALSTrue# 默认为False# 允许的HTTP请求方法CORS_ALLOW_METHODS(DELETE,GET,OPTIONS,PATCH,POST,PUT,)# 允许的非标准HTTP请求头CORS_ALLOW_HEADERS(accept,authorization,content-type,user-agent,x-csrftoken,x-requested-with,# 可以添加自定义头my-custom-header,)# 预检请求的有效期秒减少预检请求次数CORS_PREFLIGHT_MAX_AGE86400# 24小时# 限制CORS头生效的URLCORS_URLS_REGEXr^/api/.*$# 只对/api/路径应用CORS2.1.5 Django Vue部署时的CSRF问题在DjangoVue的前后端分离项目中启用CORS后还需要注意CSRF保护的配置 # settings.py# 允许跨域携带CookieCORS_ALLOW_CREDENTIALSTrue# 信任的来源用于CSRF保护CSRF_TRUSTED_ORIGINS[http://localhost:5173,https://yourdomain.com,]2.2 Flask框架的CORS配置Flask作为轻量级Web框架可以通过flask-cors扩展轻松实现CORS支持。2.2.1 安装与初始化pipinstallflask-cors2.2.2 全局CORS配置最简单的配置方式是全局启用CORS fromflaskimportFlaskfromflask_corsimportCORS appFlask(__name__)CORS(app)# 允许所有来源访问所有路由app.route(/api/data)defget_data():return{message:Hello CORS!}2.2.3 精细化配置如果需要更精细的控制可以传入配置参数 fromflaskimportFlaskfromflask_corsimportCORS appFlask(__name__)# 配置CORS选项corsCORS(app,resources{r/api/*:{# 只对/api路径生效origins:[http://localhost:5173,https://example.com],methods:[GET,POST,PUT,DELETE],allow_headers:[Content-Type,Authorization],supports_credentials:True,# 允许携带Cookiemax_age:3600# 预检请求缓存时间},r/public/*:{origins:*,# 公开接口允许所有来源methods:[GET]}})app.route(/api/data)defget_data():return{message:Hello CORS!}app.route(/public/info)defpublic_info():return{message:This is public}2.2.4 使用装饰器进行单接口配置如果只需要个别接口支持跨域可以使用cross_origin装饰器 fromflaskimportFlask,jsonifyfromflask_corsimportcross_origin appFlask(__name__)app.route(/api/hello)cross_origin(originshttp://localhost:5173)defhello():returnjsonify({message:Hello World})app.route(/api/goodbye)# 不添加装饰器不支持跨域defgoodbye():returnjsonify({message:Goodbye World})2.3 FastAPI框架的CORS配置FastAPI作为新兴的异步框架内置了CORS中间件配置起来也非常简单。2.3.1 安装FastAPI和Uvicornpipinstallfastapi uvicorn2.3.2 配置CORS中间件FastAPI通过CORSMiddleware来处理跨域 fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddleware appFastAPI()# 配置CORSapp.add_middleware(CORSMiddleware,allow_origins[http://localhost:5173,https://example.com],# 允许的来源allow_credentialsTrue,# 允许携带Cookieallow_methods[*],# 允许所有方法allow_headers[*],# 允许所有请求头max_age3600,# 预检请求缓存时间)app.get(/api/data)asyncdefread_data():return{message:Hello from FastAPI}2.3.3 动态来源配置如果来源列表需要动态生成可以使用回调函数fromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddlewarefromtypingimportList appFastAPI()# 从环境变量或数据库加载允许的来源defget_allowed_origins()-List[str]:# 这里可以从数据库读取配置return[http://localhost:5173,https://yourdomain.com]originsget_allowed_origins()app.add_middleware(CORSMiddleware,allow_originsorigins,allow_credentialsTrue,allow_methods[GET,POST,PUT,DELETE],allow_headers[Content-Type,Authorization],)2.4 三种Python框架CORS配置对比特性DjangoFlaskFastAPI主要库django-cors-headersflask-corsCORSMiddleware内置全局配置settings.py中配置CORS(app)app.add_middleware细粒度控制CORS_URLS_REGEXresources参数路径依赖配置携带CookieCORS_ALLOW_CREDENTIALSsupports_credentialsallow_credentials预检缓存CORS_PREFLIGHT_MAX_AGEmax_agemax_age第三章前端开发环境代理解决方案在开发环境中除了后端配置CORS外前端也可以通过代理服务器来规避跨域问题。这种方法的好处是不需要修改后端代码特别适合在联调阶段使用。3.1 Vite项目的代理配置Vue 3项目通常使用Vite作为构建工具可以通过配置vite.config.js实现代理 // vite.config.jsimport{defineConfig}fromviteimportvuefromvitejs/plugin-vueexportdefaultdefineConfig({plugins:[vue()],server:{proxy:{// 将以/api开头的请求代理到后端服务器/api:{target:http://localhost:8000,// 后端服务器地址changeOrigin:true,// 改变请求头中的Origin为目标地址rewrite:(path)path.replace(/^\/api/,),// 可选重写路径configure:(proxy,options){// 代理配置的回调可以添加日志等proxy.on(error,(err,req,res){console.log(proxy error,err);});}},// 多个代理规则/uploads:{target:http://localhost:8000,changeOrigin:true,}}}})理解rewrite的作用如果后端接口实际路径是http://localhost:8000/hello而前端希望用/api/hello调用就需要rewrite去掉/api前缀如果后端接口本身就带有/api前缀如http://localhost:8000/api/hello则不需要rewrite 。3.2 Axios请求封装结合代理配置Axios的请求可以这样封装 // src/utils/request.jsimportaxiosfromaxiosconstrequestaxios.create({baseURL:,// 由于代理配置可以留空或写/timeout:10000,withCredentials:true,// 允许携带Cookie如果需要})// 请求拦截器request.interceptors.request.use(config{// 添加token等认证信息consttokenlocalStorage.getItem(token)if(token){config.headers.AuthorizationBearer${token}}returnconfig},error{returnPromise.reject(error)})// 响应拦截器request.interceptors.response.use(response{returnresponse.data},error{// 统一错误处理console.error(请求错误:,error)returnPromise.reject(error)})exportdefaultrequest3.3 在Vue组件中使用// views/Example.vueimportrequestfrom/utils/requestexportdefault{methods:{asyncfetchData(){try{// 实际请求会被代理到 http://localhost:8000/helloconstdataawaitrequest.get(/api/hello)console.log(data)}catch(error){console.error(数据获取失败,error)}}}}3.4 开发代理vs生产CORS需要明确的是前端代理方案仅适用于开发环境。当项目构建并部署到生产环境时代理配置不会生效。生产环境仍然需要后端正确配置CORS或者通过Nginx等反向代理解决跨域 。方案适用环境优点缺点Vite代理开发环境配置简单无需修改后端仅开发环境有效后端CORS生产环境标准化解决方案安全可控需要后端配合Nginx代理生产环境无需修改应用代码统一入口需要运维知识第四章生产环境部署与Nginx配置在生产环境中除了后端配置CORS外还可以使用Nginx作为反向代理来解决跨域问题。这种方式可以实现前后端同源访问彻底规避跨域。4.1 同源部署策略最简单的方式是将前端静态文件和后端API部署在同一个域名的不同路径下 https://example.com/ # 前端页面 https://example.com/api/ # 后端API这种部署方式不存在跨域问题但要求前端路由不能与API路径冲突。4.2 Nginx反向代理配置如果前端和后端部署在不同服务器上可以通过Nginx反向代理将API请求转发到后端服务器 # /etc/nginx/sites-available/example.com server { listen 80; server_name example.com; # 前端静态文件 location / { root /var/www/frontend/dist; try_files $uri $uri/ /index.html; } # API代理 location /api/ { proxy_pass http://backend-server:8000/; # 后端服务器地址 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头 add_header Access-Control-Allow-Origin $http_origin always; add_header Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS always; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization always; add_header Access-Control-Allow-Credentials true always; # 处理预检请求 if ($request_method OPTIONS) { add_header Access-Control-Allow-Origin $http_origin always; add_header Access-Control-Allow-Methods GET, POST, PUT, DELETE, OPTIONS always; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization always; add_header Access-Control-Allow-Credentials true always; add_header Content-Length 0; add_header Content-Type text/plain; return 204; } } }4.3 Docker Compose多服务部署对于使用Docker部署的项目可以通过docker-compose配置多个服务 # docker-compose.ymlversion:3.8services:backend:build:./backendcontainer_name:django_backendexpose:-8000environment:-DEBUGFalse-CORS_ALLOWED_ORIGINShttp://localhost,https://example.comnetworks:-app_networkfrontend:build:./frontendcontainer_name:vue_frontendports:-80:80depends_on:-backendnetworks:-app_networknginx:image:nginx:latestcontainer_name:nginx_proxyvolumes:-./nginx/conf.d:/etc/nginx/conf.dports:-80:80-443:443depends_on:-backend-frontendnetworks:-app_networknetworks:app_network:driver:bridge第五章跨域疑难问题排查指南5.1 常见跨域错误信息及解读错误信息可能原因解决方案No Access-Control-Allow-Origin header is present后端未配置CORS或配置不正确检查后端CORS配置确保返回了正确的响应头Response to preflight request doesnt pass access control check预检请求未通过确保OPTIONS请求正确处理返回了204状态码和允许头Credentials flag is true, but the Access-Control-Allow-Origin header is *携带凭证时不能使用通配符*将Access-Control-Allow-Origin设置为具体域名Multiple CORS header Access-Control-Allow-Origin not allowed响应头重复设置检查是否有多个地方同时设置CORS头5.2 排查清单当遇到跨域问题时可以按照以下清单逐一排查 确认请求URL正确性协议、域名、端口是否匹配预期路径是否正确检查CORS响应头Access-Control-Allow-Origin是否存在且正确Access-Control-Allow-Credentials是否设置为true如果需要携带CookieAccess-Control-Allow-Methods是否包含实际请求方法验证预检请求OPTIONS请求是否返回200或204状态码响应头是否完整检查凭证配置前端是否设置withCredentials: true或credentials: include后端是否设置Access-Control-Allow-Credentials: true是否同时使用通配符*和true不允许验证代理配置开发环境代理规则是否正确路径重写是否生效请求头是否正确传递5.3 调试工具推荐浏览器开发者工具查看Network面板中的请求和响应头Postman/Insomnia绕过浏览器限制测试APIcurl命令快速测试CORS头# 测试OPTIONS预检请求curl-XOPTIONS http://localhost:8000/api/data\-HOrigin: http://localhost:5173\-HAccess-Control-Request-Method: GET\-v# 测试实际请求curl-XGET http://localhost:8000/api/data\-HOrigin: http://localhost:5173\-v第六章安全最佳实践6.1 切勿在生产环境使用通配符将Access-Control-Allow-Origin设置为*虽然方便但会允许任何网站访问你的API存在严重安全风险。生产环境必须明确指定允许的来源列表 。6.2 谨慎处理Cookie凭证当设置allowCredentials(true)时必须注意 Access-Control-Allow-Origin不能为*Access-Control-Allow-Headers不能为*Cookie的SameSite属性可能需要设置为NoneHTTPS环境下6.3 合理设置预检请求缓存通过maxAge设置适当的预检请求缓存时间可以减少不必要的OPTIONS请求提升性能。一般建议设置为600到86400秒之间 。6.4 遵循最小权限原则只开放必要的HTTP方法和请求头不要盲目使用*。例如如果API只支持GET请求就应该限制Access-Control-Allow-Methods为GET。6.5 与CSRF防护协同工作启用CORS允许跨域携带Cookie时需要特别注意CSRF攻击防护。Django等框架提供了CSRF_TOKEN机制需要将前端域名添加到CSRF信任列表中 。结语跨域问题是前后端分离架构中的一道必经关卡理解其原理并掌握解决方案是每个Web开发者的基本功。通过本文的学习你应该已经掌握了跨域问题的本质浏览器的同源安全策略CORS的核心机制简单请求与预检请求Python三大框架的CORS配置方法开发环境的代理解决方案生产环境的Nginx部署策略安全最佳实践和问题排查技巧记住跨域不是Bug而是浏览器保护用户的安全机制。选择合适的方案、遵循安全规范就能在保证安全的前提下实现跨域资源共享。希望本文能帮助你在实际项目中游刃有余地应对跨域挑战转载声明本文原创转载请注明出处。
