前端工程化 / 系统课时

排查代理与跨域失败

排查代理与跨域失败

本课建立一套从浏览器到后端的分层排查顺序,帮助你快速区分代理未命中、TLS 证书、Cookie、CORS 与业务接口错误,并用网络面板和服务端日志完成闭环验证。

学习目标

  • 能从浏览器网络面板判断请求是否真正经过 Vite 开发服务器。
  • 能根据状态码、请求头、响应头和日志定位五类常见根因。
  • 能修改代理配置并用可重复的请求验证修复结果。

先确认请求走了哪条链路

开发环境中的代理只处理发往 Vite 开发服务器、且路径命中 server.proxy 规则的请求。浏览器若直接访问后端绝对地址,请求不会经过 Vite,此时浏览器会执行真实的跨域检查。

在浏览器开发者工具的 Network 面板中选中失败请求,重点查看 Request URL、请求方法、状态码、Origin、Cookie、Set-Cookie 和响应体。若前端请求的是 /api/users,浏览器看到的地址仍应是 Vite 地址;转发后的目标地址需要结合 Vite 终端日志或后端访问日志确认。

下面的配置把 /api 转发到本地后端,并打印代理错误。路径重写后,/api/health 会被发送为后端的 /health。

ts
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)
          })
        },
      },
    },
  },
})

配置生效后重启开发服务器,再执行:

bash
curl -i http://127.0.0.1:5173/api/health

预期输出

text
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,使用凭据时不能把允许源写成 *。

代理、证书、Cookie、CORS 与后端错误的分层定位流程

用双端日志完成闭环

一次有效排查至少要关联三份证据:浏览器请求详情、Vite 终端日志、后端访问或错误日志。先记录请求时间、路径和状态码,再确认 Vite 是否转发,最后在后端按同一时间窗口查找请求。

若后端支持请求 ID,应让网关或应用返回该 ID,并在日志中同时记录。修复后不要只看页面“似乎正常”,还要重新检查状态码、响应体、Cookie 回传以及后端日志,确认请求走的是预期链路。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查代理与跨域失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通