浏览器跨域（CORS）错误排查与服务端代理模式解决方案

当你在浏览器前端代码（React、Vue、纯 HTML 页面等）中直接调用 HHAPI 时，浏览器的同源策略会检查响应头中的 CORS 字段，若条件不满足则会拦截请求，在控制台显示跨域错误。本文说明 CORS 问题的根本原因，以及推荐的解决方案。

强烈不建议在浏览器前端直接调用 HHAPI。在前端代码中直接调用意味着你的 API Key 会暴露在客户端——任何打开浏览器开发者工具的用户都能看到你的密钥。一旦密钥泄露，可能导致费用被滥用或账户安全风险。这是安全问题，而非仅仅是技术问题。

CORS 产生原因

浏览器的**同源策略（Same-Origin Policy）**规定：网页只能向与自身相同源（协议 + 域名 + 端口均一致）的地址发送请求。当你的前端页面（如 https://yourapp.com）尝试请求不同源的 HHAPI 地址时，浏览器会先发送一个 OPTIONS 预检请求，检查服务端是否在响应头中声明允许该来源访问：

Access-Control-Allow-Origin: https://yourapp.com

若服务端未返回对应的 CORS 响应头，浏览器会阻止该请求并在控制台报错：

Access to fetch at '<API_BASE_URL>/v1/chat/completions' from origin
'https://yourapp.com' has been blocked by CORS policy.

推荐解决方案：服务端代理

正确的做法是在你自己的服务端创建一个代理接口，由服务端持有 API Key 并转发请求到 HHAPI。前端只与你自己的服务端通信，API Key 始终不暴露给客户端。

在服务端创建代理接口

在你的 Node.js、Python 或其他后端服务中创建一个代理路由，接收前端请求。参考下方的 Node.js Express 示例。

前端调用自己的服务端接口

前端代码中，将请求目标从 HHAPI 地址改为你自己的服务端地址，无需携带 API Key：

// ✅ 前端只调用自己的服务端，不直接碰 HHAPI
const response = await fetch("/api/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    messages: [{ role: "user", content: "你好" }],
  }),
});
const data = await response.json();

服务端持有 API Key 并转发到 HHAPI

服务端从环境变量读取 API Key，附加到转发给 HHAPI 的请求中。前端用户无法看到该密钥。

Node.js Express 代理示例

import express from "express";
import OpenAI from "openai";

const app = express();
app.use(express.json());

// ✅ API Key 仅在服务端环境变量中，永远不会发送到浏览器
const client = new OpenAI({
  apiKey: process.env.HHAPI_API_KEY,
  baseURL: "<API_BASE_URL>/v1",
});

app.post("/api/chat", async (req, res) => {
  try {
    const { messages } = req.body;

    const completion = await client.chat.completions.create({
      model: "<MODEL_ID>",
      messages: messages,
    });

    res.json(completion);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => console.log("代理服务已启动：http://localhost:3000"));

如果必须从前端调用（不推荐）

若确有在浏览器直接调用的需求，HHAPI 是否支持配置特定域名的 CORS 白名单（待确认）。请联系技术支持了解详情。即使 CORS 问题得以解决，仍请注意 API Key 在前端暴露的安全风险。

使用服务端代理不仅能解决 CORS 问题，还带来更多好处：

用户鉴权：在代理层验证用户身份，防止未授权访问
请求审计：记录请求日志，便于排查问题和分析用量
用量控制：在代理层实现用户级别的请求限流，防止单个用户超额消耗
密钥隔离：API Key 集中管理在服务端，轮换密钥时无需修改前端代码

相关资源

​CORS 产生原因

​推荐解决方案：服务端代理

​Node.js Express 代理示例

​如果必须从前端调用（不推荐）

CORS 产生原因

推荐解决方案：服务端代理

Node.js Express 代理示例

如果必须从前端调用（不推荐）