前端工程化 / 系统课时
排查代理与跨域失败
排查代理与跨域失败
本课建立一套从浏览器到后端的分层排查顺序,帮助你快速区分代理未命中、TLS 证书、Cookie、CORS 与业务接口错误,并用网络面板和服务端日志完成闭环验证。
学习目标
- 能从浏览器网络面板判断请求是否真正经过 Vite 开发服务器。
- 能根据状态码、请求头、响应头和日志定位五类常见根因。
- 能修改代理配置并用可重复的请求验证修复结果。
先确认请求走了哪条链路
开发环境中的代理只处理发往 Vite 开发服务器、且路径命中 server.proxy 规则的请求。浏览器若直接访问后端绝对地址,请求不会经过 Vite,此时浏览器会执行真实的跨域检查。
在浏览器开发者工具的 Network 面板中选中失败请求,重点查看 Request URL、请求方法、状态码、Origin、Cookie、Set-Cookie 和响应体。若前端请求的是 /api/users,浏览器看到的地址仍应是 Vite 地址;转发后的目标地址需要结合 Vite 终端日志或后端访问日志确认。
下面的配置把 /api 转发到本地后端,并打印代理错误。路径重写后,/api/health 会被发送为后端的 /health。
import { defineConfig } from 'vite'
export default defineConfig({
server: {
proxy: {
'/api': {
target: 'http://127.0.0.1:8080',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, ''),
configure(proxy) {
proxy.on('error', (error, request) => {
console.error('[proxy error]', request.url, error.message)
})
},
},
},
},
})配置生效后重启开发服务器,再执行:
curl -i http://127.0.0.1:5173/api/health预期输出
HTTP/1.1 200 OK
content-type: application/json
...
{"status":"ok"}该结果假设后端 /health 接口按示例返回。端口、响应头和正文以实际项目为准;若返回 Vite 的 404,且后端没有访问日志,优先检查代理路径是否命中。
按现象区分五类根因
| 现象 | 更可能的根因 | 首要验证 |
|---|---|---|
| Vite 返回 404,后端无日志 | 代理未命中或重写错误 | 对照请求路径与 server.proxy 键 |
| Vite 返回 502,终端出现证书校验错误 | HTTPS 证书链不受信任 | 查看错误码并验证后端证书 |
| 登录成功但后续请求没有会话 | Cookie 未写入或未发送 | 检查 Set-Cookie、Domain、Path、SameSite、Secure |
| 浏览器出现预检或 CORS 报错 | 请求绕过代理,或生产端跨域策略不完整 | 检查 OPTIONS 与 CORS 响应头 |
| 请求到达后端并返回 4xx/5xx | 鉴权、参数或业务异常 | 对照请求 ID 与后端错误日志 |
代理使用 HTTPS 后端时,不要把 secure: false 当作长期修复。它只适合本地临时验证;正确做法是让运行 Vite 的系统信任开发证书,或为后端配置完整可信的证书链。
检查 Cookie 与 CORS 边界
Cookie 问题要分成“服务端是否下发”和“浏览器是否回传”两步。响应里没有 Set-Cookie,应查后端会话逻辑;有 Set-Cookie 但浏览器未保存,通常是 Domain、Path、SameSite 或 Secure 不匹配;浏览器已保存却未发送,则继续检查请求域、路径以及跨域请求是否启用了凭据。
CORS 只由浏览器对跨源请求实施。通过 Vite 代理后,浏览器看到的是同源请求,因此开发环境正常并不能证明生产环境的 CORS 配置正确。生产环境必须由网关或后端返回与实际前端源匹配的 Access-Control-Allow-Origin,使用凭据时不能把允许源写成 *。

用双端日志完成闭环
一次有效排查至少要关联三份证据:浏览器请求详情、Vite 终端日志、后端访问或错误日志。先记录请求时间、路径和状态码,再确认 Vite 是否转发,最后在后端按同一时间窗口查找请求。
若后端支持请求 ID,应让网关或应用返回该 ID,并在日志中同时记录。修复后不要只看页面“似乎正常”,还要重新检查状态码、响应体、Cookie 回传以及后端日志,确认请求走的是预期链路。