Vite 开发代理与后端集成：server.proxy、路径重写与 Mock

痛点 1：跨域 —— 前端 5173 端口请求 8000 端口后端，CORS 拦截
痛点 2：地址混乱 —— 每人本地后端端口不同，代码里硬编码
痛点 3：后端未就绪 —— 接口 404，前端被阻塞

浏览器 ──同源请求 /api/users──► Vite Dev Server ──转发──► http://localhost:8000/users
                                    ▲                            │
                                    └──── 同源，无 CORS 问题 ─────┘

// vite.config.ts
export default {
  server: {
    proxy: {
      "/api": {
        target: "http://localhost:8000",   // 后端地址
        changeOrigin: true,                // 改写 Host 头（后端视角=正常来源）
      },
      // 多个后端：不同前缀指不同 target
      "/auth": {
        target: "http://localhost:9000",
        changeOrigin: true,
      },
    },
  },
};

请求 /api/users
  → 转发到 http://localhost:8000/api/users
  → Host 头改为 localhost:8000（changeOrigin）
  → 响应原样返回前端

proxy: {
  "/api": {
    target: "http://localhost:8000",
    changeOrigin: true,
    rewrite: (path) => path.replace(/^\/api/, ""),  // 剥掉 /api
  },
}

请求 /api/users
  → rewrite 后 /users
  → 转发 http://localhost:8000/users

后端带前缀：/api/users → target 保留 /api（不 rewrite）
后端不带前缀：/api/users → rewrite 成 /users（前端约定统一前缀）

不 open：请求到后端的 Host 头是 localhost:5173
  → 后端按 Host 校验（如 CORS 白名单/站点鉴权）会拒绝
open：Host 头改写为 target（localhost:8000）
  → 后端视角 = 同站点请求，校验通过

proxy: {
  "/api": {
    target: "http://localhost:8000",
    changeOrigin: true,   // 生产/测试环境通常必开
  },
}

proxy: {
  "/api": {
    target: "https://api.example.com",   // HTTPS 目标
    changeOrigin: true,
    secure: false,   // 目标证书自签/内网时跳过校验（生产不要！）
  },
}

proxy: {
  "/ws": {
    target: "wss://localhost:8000",   // 或 ws://
    ws: true,                          // 启用 WebSocket 代理
    changeOrigin: true,
  },
}

浏览器 ──ws://localhost:5173/ws──► Vite ──► ws://localhost:8000/ws
                                   （HTTP 升级 + 双向转发）

proxy: {
  "/ws": {
    target: "ws://localhost:8000",
    ws: true,
    changeOrigin: true,
  },
}

Mock 方式对比：
□ vite-plugin-mock → 用配置文件模拟接口（dev 专用）
□ 自定义中间件 → configureServer 注入假数据（最灵活）
□ Mock Service Worker（MSW）→ 拦截浏览器请求（真实验证）

// 自定义中间件 Mock（配置无关、纯 JS）
export function mockPlugin(mocks: Record<string, unknown>): Plugin {
  return {
    name: "local-mock",
    configureServer(server) {
      server.middlewares.use((req, res, next) => {
        const mock = mocks[req.url ?? ""];
        if (mock) { res.setHeader("Content-Type", "application/json"); res.end(JSON.stringify(mock)); }
        else next();
      });
    },
  };
}

// 开发时用 Mock，联调时关掉
server: {
  proxy: isMockEnabled ? {} : { "/api": realBackend },
}

// .env.development / .env.staging / .env.production
// VITE_API_BASE=/api
// VITE_PROXY_TARGET=http://localhost:8000

export default ({ mode }) => {
  const isDev = mode === "development";
  return {
    server: {
      proxy: isDev ? {
        "/api": {
          target: loadEnv(mode, process.cwd()).VITE_PROXY_TARGET,
          changeOrigin: true,
        },
      } : {},
    },
    build: {
      // 生产直接用 VITE_API_BASE（同源/CDN 场景）
      rollupOptions: { /* ... */ },
    },
  };
};

环境矩阵：
dev：     proxy → 本地后端 / Mock
staging： proxy 或无 → 预发布后端
prod：    无 proxy，API 走同源/网关/CDN

工作流：
1. 契约先行：OpenAPI/接口文档先定（前后端同源）
2. 前端用 Mock 按契约开发
3. 后端就绪 → 切 target 到真实后端
4. 联调验证：真实数据 + 契约校验（response 与 schema 一致）
5. 故障 → 看 proxy 日志/Network 面板定位

# 自测代理
curl -v http://localhost:5173/api/users   # 看转发后的响应