★ FEATURED ARTICLE 后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载导读在前后端分离的现代 Web 开发中浏览器同源策略导致的跨域CORS问题几乎是每个全栈开发者都要面对的第一道坎。本文聚焦 Midway Hooks 项目Node.js 全栈/前后端一体化框架的 Hooks 体系中如何通过koa/cors中间件配置跨域覆盖从依赖安装、全局中间件挂载到全部核心配置项逐一拆解的完整流程。读完本文你将能够在 Midway Hooks 项目中独立完成跨域配置并理解origin、credentials、allowMethods等关键参数对浏览器预检请求与响应头的影响。背景为什么 Midway Hooks 需要 CORS 配置Midway Hooks 是基于函数式编程风格Functional API构建 API 的开发模式开发者不再编写传统 Controller而是通过Api()、Get()等函数式装饰器定义接口配合useContext()访问请求上下文。由于这种模式天然面向前后端一体化场景前端页面与后端接口经常运行在不同的端口甚至不同域名上浏览器便会基于同源策略拦截跨源请求。从仓库中的示例项目 samples/functional-api-service 可以看出Hooks 应用的入口是 src/configuration.ts其中通过imports注册midwayjs/koa等框架组件。这正是 CORS 中间件需要挂载的位置——在 Hooks 体系中中间件统一通过hooks()配置对象的middleware数组注入koa/cors作为标准 Koa 中间件可以无缝接入。使用方法第一步安装依赖在项目根目录执行以下命令安装koa/corsnpm install koa/corskoa/cors是 Koa 生态中最常用的 CORS 中间件基于koa的洋葱模型实现专门用于向响应报文写入Access-Control-*系列跨域响应头。第二步在 configuration.ts 中启用Hooks 应用通过createConfiguration定义应用配置imports中注册 Koa 框架与hooks()配置。将cors()中间件放入hooks()的middleware数组即可对全部接口启用跨域import { createConfiguration, hooks, } from midwayjs/hooks; import * as Koa from midwayjs/koa; import cors from koa/cors; export default createConfiguration({ imports: [ Koa, hooks({ // 全局启用 CORS允许任意来源访问 middleware: [ cors({ origin: * }), ], }), ], });cors()返回的是一个标准 Koa 中间件函数因此它同样可以出现在 Midway Hooks 支持的任意中间件层级中。仓库文档 site/docs/hooks/middleware.md 展示了中间件的三种挂载位置CORS 均可按需选择全局中间件放在configuration.ts的hooks({ middleware: [...] })中对所有接口生效即上述示例文件级中间件在 API 文件中导出config: ApiConfig { middleware: [logger, cors] }对该文件内所有 API 函数生效单函数中间件通过Middleware(logger, cors)包裹单个Api(Get(), ...)函数仅对该函数生效。其中「文件级」与「单函数级」两种方式无需带参数调用cors直接传入函数本身即可例如middleware: [logger, cors]而全局方式通常显式调用cors({ origin: * })以明确配置项。核心配置项详解koa/cors支持的配置项如下这也是 Midway Hooks 中 CORS 能力的完整参数面/** * CORS middleware * * param {Object} [options] * - {String|Function(ctx)} origin Access-Control-Allow-Origin, default is request Origin header * - {String|Array} allowMethods Access-Control-Allow-Methods, default is GET,HEAD,PUT,POST,DELETE,PATCH * - {String|Array} exposeHeaders Access-Control-Expose-Headers * - {String|Array} allowHeaders Access-Control-Allow-Headers * - {String|Number} maxAge Access-Control-Max-Age in seconds * - {Boolean|Function(ctx)} credentials Access-Control-Allow-Credentials, default is false. * - {Boolean} keepHeadersOnError Add set headers to err.header if an error is thrown * return {Function} cors middleware * api public */逐项说明如下配置项对应响应头默认值说明originAccess-Control-Allow-Origin请求头中的Origin允许的跨域来源可传字符串如*或http://127.0.0.1:7001也可传函数(ctx) string动态返回。启用credentials时不能使用*allowMethodsAccess-Control-Allow-MethodsGET,HEAD,PUT,POST,DELETE,PATCH允许的 HTTP 方法可传字符串或字符串数组exposeHeadersAccess-Control-Expose-Headers无允许前端 JS 读取的响应头列表默认情况下浏览器只能读取少量安全响应头allowHeadersAccess-Control-Allow-Headers请求头中的Access-Control-Request-Headers允许的请求头列表可传字符串或字符串数组maxAgeAccess-Control-Max-Age无预检请求Preflight结果可缓存的秒数减少浏览器重复发送 OPTIONS 请求credentialsAccess-Control-Allow-Credentialsfalse是否允许携带 Cookie 等凭证可传布尔值或函数(ctx) booleankeepHeadersOnError无false中间件执行报错时是否将已设置的跨域响应头写入err.headers便于上层错误处理时透传origin控制允许的来源origin是 CORS 配置中最核心的选项。默认行为是回显请求头中的Origin值即允许任意来源。生产环境若要收紧应显式指定为具体域名例如cors({ origin: http://127.0.0.1:7001 })需要根据请求动态判断来源时可以传入函数cors({ origin: (ctx) { // 依据 ctx.request.header.origin 或业务逻辑返回允许的来源 return https://example.com; }, })注意根据 CORS 规范Access-Control-Allow-Origin一旦设置为*浏览器要求Access-Control-Allow-Credentials必须为false反之只要启用credentials: trueorigin就不能是通配符*必须给出明确的来源或函数动态返回值否则浏览器会拒绝响应。credentials允许携带 Cookie 与凭证跨域请求若需要携带 Cookie例如fetch(url, { credentials: include })或 XMLHttpRequest 的withCredentials true服务端必须开启credentials: truecors({ origin: http://127.0.0.1:7001, credentials: true, })如前所述该配置与origin: *互斥。仓库文档 site/docs/extensions/cross_domain.md 中关于通用跨域组件的配置示例同样强调了这一点可互为印证。allowMethods 与 allowHeaders预检请求的通行证当浏览器发起带自定义头如Content-Type: application/json、Authorization的跨域请求时会先发送 OPTIONS 预检请求Preflight。服务端通过Access-Control-Allow-Methods与Access-Control-Allow-Headers告知浏览器允许的方法与请求头匹配时浏览器才会放行真实请求。allowMethods默认覆盖GET,HEAD,PUT,POST,DELETE,PATCH基本满足 RESTful API 场景若接口使用了自定义方法如OPTIONS之外的扩展可按需追加cors({ allowMethods: [GET, POST, PUT, DELETE, PATCH, OPTIONS], allowHeaders: [Content-Type, Authorization, X-Requested-With], })maxAge缓存预检结果maxAge单位为秒用于指示浏览器缓存本次预检响应避免每个跨域请求都触发一次额外的 OPTIONS 往返。高频调用的接口建议设置较大值例如cors({ maxAge: 86400 })缓存一天。exposeHeaders 与 keepHeadersOnErrorexposeHeaders默认情况下浏览器只向 JS 暴露Cache-Control、Content-Language、Content-Type、Expires、Last-Modified、Pragma等安全响应头自定义响应头如分页信息X-Total-Count需要通过该选项显式声明后才能被前端读取keepHeadersOnError当后续中间件或业务代码抛出异常时是否保留已写入的跨域头。若你的应用有统一的全局错误处理中间件且希望错误响应仍携带 CORS 头应将其设为true否则错误响应可能因缺少 CORS 头而被浏览器拦截前端只能看到晦涩的网络错误而非真实错误信息。与通用跨域组件的差异仓库还提供了面向传统框架midwayjs/faas、midwayjs/web、midwayjs/koa、midwayjs/express的通用跨域组件midwayjs/cross-domain它通过Configuration({ imports: [crossDomain] })引入并支持在 config.default.ts 中以配置项形式声明cors与jsonp模式详见 site/docs/extensions/cross_domain.md。而本文所述的 Hooks 方式与它的本质区别在于Midway Hooks 的函数式配置体系中CORS 被当作一个普通 Koa 中间件注入hooks({ middleware: [...] })配置即代码无需额外的组件装载与配置中心适合以函数式 API 为主的新项目若你的项目同时存在传统 Controller 与 Hooks 两种编码风格也可以按需混用这两种跨域方案。常见问题排查当发现 CORS 配置不生效时可以对照仓库文档 site/docs/extensions/cross_domain.md 中总结的排查顺序逐项确认确认请求确实跨域同源策略只约束浏览器环境服务端调用Node.js 内部请求、curl 等不受 CORS 限制不设置任何配置也能成功确认请求发自浏览器只有浏览器XMLHttpRequest、Fetch API才会执行同源策略检查确认请求带有Origin头同源请求或部分浏览器场景如地址栏直达不带Origin头CORS 中间件据此无法触发响应头写入检查预检请求OPTIONS是否被中间件正确处理确认allowMethods/allowHeaders与实际请求匹配检查credentials与origin的搭配credentials: true时origin不能为*否则浏览器会因响应头非法而拦截。典型的 CORS 报错形如Access to fetch at http://127.0.0.1:7002/ from origin http://127.0.0.1:7001 has been blocked by CORS policy: No Access-Control-Allow-Origin header is present on the requested resource.该报错意味着服务端响应中缺少Access-Control-Allow-Origin头优先检查中间件是否已挂载、请求是否真的带了Origin头、以及错误响应是否因keepHeadersOnError为false而丢失了跨域头。小结在 Midway Hooks 中配置 CORS 只需三步安装koa/cors、在configuration.ts的hooks({ middleware })中挂载cors()、按需设置origin、credentials、allowMethods等参数。这套方案完全复用 Koa 生态的中间件能力代码量小、作用域可控全局/文件级/单函数级均可并天然适配 Hooks 函数式 API 的开发范式。合理设置maxAge与keepHeadersOnError还能显著优化跨域请求的性能与错误排查体验。如需进一步了解中间件的三种挂载层级与更多中间件用法可继续阅读仓库文档 site/docs/hooks/middleware.md通用框架下的跨域组件含 JSONP则见 site/docs/extensions/cross_domain.md。赞分享后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载相关推荐Midway 跨域组件cross-domain完全指南CORS 与 JSONP 配置实战Midway 跨域组件cross domain完全指南CORS 与 JSONP 配置实战 导读 Midway 提供了开箱即用的通用跨域组件 midway后端微服务云原生Wasp 多域名 CORS 配置实战基于全局中间件管理跨域访问Wasp 多域名 CORS 配置实战基于全局中间件管理跨域访问 本篇指南讲解如何在 Wasp 应用中通过自定义全局中间件global middlewareWeb框架后端前端CLI开发工具OpenCloud 中的 CORS 中间件rs/cors 配置、实现原理与实战指南OpenCloud 中的 CORS 中间件rs/cors 配置、实现原理与实战指南 导读 OpenCloud 作为一款提供文件管理、共享与协同能力的开源平台后端微服务存储认证鉴权上一篇告别冗长命令行Chronicle-Core系统属性文件加载机制详解与最佳实践下一篇LeetCode-Go 如何运行 gotest.sh 生成 Codecov 可识别的单一覆盖率文件 coverage.txt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
