Vite前端API调用与本地开发代理配置策略详解

本文档详细描述了本项目在前端代码中定义后端 API URL 的风格，以及如何配置 Vite 开发服务器的代理（Proxy），并解释这套组合方案解决了哪些关键问题。

一、 核心问题

现代 Web 开发中，前端应用（运行在浏览器）和后端 API（运行在服务器）通常是分离的。这会带来两个主要问题：

• 跨域资源共享 (CORS)：在本地开发时，前端运行在 http://localhost:5173，而后端 API 运行在云端的 https://gateway.jpgcp.cloud。由于源（协议、域名、端口）不同，浏览器会出于安全策略，默认阻止前端直接调用后端 API。
• 环境差异：前端代码需要一种方法，既能在本地开发时正确调用云端 API，又能在部署到生产环境后，正确地调用生产环境的 API，而不需要每次都手动修改代码。

二、 解决方案：“相对路径” + “Vite 代理”

我们采用了一套标准的、优雅的组合方案来解决以上所有问题。

1. API URL 风格：使用相对路径

我们修改了 src/services/api.ts 文件，将 API 的 URL 定义为一个相对路径。

代码 (src/services/api.ts):

// The URL of your backend API. Using a relative path works for both
// local development (with proxy) and production deployment.
const API_URL = '/chat-api-svc/api/v1/chat';

// ...
const response = await fetch(API_URL, { ... });

原理与优势：

• 当 URL 以 / 开头时，浏览器会自动将当前页面的协议和域名加在它的前面。
• 在生产环境: 页面在 https://gateway.jpgcp.cloud/chat/，请求就会发往 https://gateway.jpgcp.cloud/chat-api-svc/api/v1/chat。这正好能匹配上我们 GKE Gateway 中的路由规则，实现了同源调用，没有 CORS 问题。
• 在本地开发环境: 页面在 http://localhost:5173/chat/，请求就会发往 http://localhost:5173/chat-api-svc/api/v1/chat。这个地址本身是无效的，但它为我们的第二步——Vite 代理——创造了条件。

2. Vite 代理配置

为了让本地开发时的 API 请求能成功，我们配置了 Vite 的开发服务器，让它充当一个代理。

配置 (vite.config.ts):

// ...
export default defineConfig({
  // ...
  server: {
    host: true,
    // This proxy configuration is for the local development server ONLY.
    proxy: {
      // 当开发服务器收到一个以 '/chat-api-svc' 开头的请求时...
      '/chat-api-svc': {
        // ...就将它转发给这个目标地址。
        target: 'https://gateway.jpgcp.cloud',
        // 改变请求的 Origin 头，对于 HTTPS 和虚拟主机托管是必需的。
        changeOrigin: true,
      },
    },
  },
  // ...
})

原理与优势：

• 这个 server.proxy 配置仅在 npm run dev 时生效，对生产构建没有影响。
• 它告诉 Vite：“你就是中间人。所有发给你的、路径以 /chat-api-svc 开头的请求，都不要自己处理，而是原封不动地转发给 https://gateway.jpgcp.cloud，然后再把那边的响应拿回来，交给浏览器。”
• 对于浏览器来说，它始终认为自己是在和 localhost:5173 通信，因此完全规避了 CORS 问题。

三、 总结

通过**“前端使用相对路径”和“本地开发环境使用代理”**这套组合拳，我们实现了：

• 一套代码，两种环境无缝运行：同一份前端代码，无需任何修改，既可以在本地开发时调用云端 API，也可以在部署后调用生产环境的网关。
• 彻底解决 CORS 问题：无论是本地还是生产，从浏览器的视角来看，API 调用都是同源的。
• 配置清晰，易于维护：API 的真实地址只存在于一处（Vite 的代理配置中），便于未来修改。生产环境的路由则完全由 GKE Gateway 的配置来管理。

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。