前端工程化 / 系统课时
定制 CORS 与响应头
定制 CORS 与响应头
本课解决开发环境中“到底该由谁处理跨域”的混乱:你将为 Vite 开发服务器配置精确的 CORS 白名单与通用响应头,并能区分直接访问 Vite、经代理访问后端和浏览器直连后端三种责任边界。
学习目标
- 使用
server.cors限制允许访问 Vite 开发服务器的来源 - 使用
server.headers添加统一的开发环境响应头 - 判断跨域问题应由 Vite、开发代理还是后端服务处理
先划清三种跨域责任
server.cors 只控制 Vite 开发服务器返回的资源,例如 HTML、模块脚本、源码映射和静态文件。它通过响应头告诉浏览器,哪些来源可以读取这些响应;它不是登录鉴权,也不会阻止 curl 或其他服务器发起请求。
当页面请求 /api,且该路径被 server.proxy 转发到后端时,浏览器看到的请求目标仍是当前 Vite 地址,因此开发阶段通常没有浏览器跨域。代理只负责转发,不代表后端已经正确配置生产环境 CORS。
如果浏览器直接请求 https://api.example.test,响应来自后端,必须由后端返回正确的 Access-Control-Allow-* 头。修改 Vite 的 server.cors 或 server.headers 无法修复这条直连链路。

配置白名单与通用响应头
下面的配置只允许本机开发页面和指定测试域读取 Vite 响应。启用凭据时不能使用通配来源 *,应明确列出可信来源。headers 适合添加安全提示、禁用开发缓存或调试标识,不要用固定的 Access-Control-Allow-Origin 代替 cors 的来源匹配。
import { defineConfig } from 'vite'
export default defineConfig({
server: {
cors: {
// 同时支持本机任意开发端口和固定测试域
origin: [
/^http:\/\/localhost:\d+$/,
'https://dev.example.test',
],
methods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'],
allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
exposedHeaders: ['X-Request-ID'],
credentials: true,
maxAge: 600,
},
headers: {
// 这些头会附加到 Vite 开发服务器的响应
'X-Content-Type-Options': 'nosniff',
'Cache-Control': 'no-store',
'X-Dev-Server': 'vite',
},
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
},
},
},
})这份配置生效后,允许来源会获得匹配自身的 Access-Control-Allow-Origin,预检请求还能看到允许的方法、请求头和凭据设置。/api 的目标地址只在 Vite 开发服务器内部可见,正式部署仍要由网关或后端建立真实转发与 CORS 策略。
验证预检响应
启动开发服务器后,用带 Origin 的 OPTIONS 请求模拟浏览器预检。动态端口以实际启动日志为准;若项目不是 5173,请替换命令中的端口。
curl -i -X OPTIONS "http://localhost:5173/src/main.ts" \
-H "Origin: https://dev.example.test" \
-H "Access-Control-Request-Method: GET" \
-H "Access-Control-Request-Headers: authorization,x-request-id"预期输出关键行如下,响应头顺序和大小写可能不同。
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://dev.example.test
Vary: Origin
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET,HEAD,PUT,PATCH,POST,DELETE
Access-Control-Allow-Headers: Content-Type,Authorization,X-Request-ID
Access-Control-Max-Age: 600
X-Content-Type-Options: nosniff
Cache-Control: no-store
X-Dev-Server: vite再把 Origin 改成未授权域名。请求可能仍返回状态码,但响应中不应出现允许该来源的 Access-Control-Allow-Origin;真正执行拦截的是浏览器,而不是 curl。
避免把响应头配置成安全幻觉
不要把 cors: true 当作默认修复方案,它允许任意网站读取开发服务器内容。开发服务器可能暴露源码、环境注入结果和调试资源,应采用明确白名单,并避免把服务直接开放到不可信网络。
server.headers 是静态键值集合,适合所有响应都相同的头。需要按路径、用户或请求来源动态计算响应头时,应通过 Vite 插件的 configureServer 添加中间件,或把逻辑放到真正负责该接口的后端。
排查顺序
遇到浏览器跨域报错时,先在网络面板确认失败请求的完整 URL和响应方。请求落到 Vite 资源就检查 server.cors;请求命中 /api 代理就检查代理是否成功连接后端;请求直接落到后端域名就检查后端或网关的 CORS。
如果预检失败,还要核对请求方法、自定义请求头和凭据模式。前端使用 credentials: 'include' 时,服务端必须返回明确来源和 Access-Control-Allow-Credentials: true,不能返回通配来源。