浏览器和移动端直连 API：CORS、Key 暴露与网关转发清单

做 H5 或网页应用时，很多人第一反应是前端直接 fetch 模型接口。本地跑得通，一上线就撞 CORS，或者为了绕开跨域把 Key 写进前端代码——这一步做完，Key 事实上已经公开了。这篇按工程落地讲：为什么不能直连、三种替代方案怎么选、各自的代价是什么、上线前该检查哪几项。

做 H5 或网页应用时，很多人第一反应是前端直接 fetch 模型接口。本地跑得通，一上线就撞 CORS，或者为了绕开跨域把 Key 写进前端代码。这一步做完，Key 事实上已经公开了，剩下的只是别人愿不愿意去拿的问题。

这篇不讲原理科普，按工程落地讲清楚三件事：为什么前端直连约等于交出 Key、网关转发加短期令牌加来源白名单三种替代方案各自代价是什么、上线前该按什么顺序排查。涉及具体额度、价格、限速数字，一律到站内对应页面核对当时的数字，别拿这篇文章里的描述当报价单用。

为什么前端直连约等于交出 Key

浏览器里的任何凭据都运行在用户设备上。打开开发者工具看网络面板、翻打包产物里的字符串、抓一次请求头，三步就能拿到。代码混淆、把 Key 拆成几段拼接、放进环境变量再打包，这些只是把门槛抬高一点，改变不了它最终会被下发到客户端这一事实。

• 危险不在泄露本身，而在没有边界：能调哪些模型、能烧多少额度、能读写哪些接口，全都跟着这把 Key 走
• 按量计费的场景下，泄露常常先表现为账单异常，而不是报错，等你发现时已经跑了一段时间
• 可以稍微放松的情况：Key 只绑定了很低额度、只允许特定来源、并且随时能吊销，这种情况下风险敞口有限
• 反过来，一把全权限、长期有效、无法单独吊销的 Key 放在前端，任何理由都站不住，包括「先上线再说」

先分清你在做哪种东西：内部小工具、给人看的演示 Demo、还是真实用户会付费的产品。前两种的做法不能直接搬到第三种，很多事故就是把 Demo 阶段的写法带进了正式产品。

三种替代方案与各自的代价

网关转发的好处是 Key 不出服务器，顺带能加限流、日志、内容过滤。短期令牌的好处是减少后端转发压力，但前提是上游确实支持这种临时凭据机制，不支持就别硬凑，硬凑出来的「伪令牌」只是在接口外面套了层壳。

来源白名单常被当成万能药，它拦得住浏览器从别的域名发起的请求，拦不住有人直接用脚本带同样的头去调。所以它只能当叠加的一层，不能当唯一手段。三者可以同时上，但别指望任何一层单独兜住全部风险。

网关转发的落地清单：超时、并发、降级、日志

1. 定超时前端到网关、网关到模型两段分别设超时，别让用户对着转圈等。流式响应要单独处理，长连接超时和普通请求不是一回事，混用一套配置通常会在流式场景下出问题。
2. 加限流按用户、按 IP、按 Key 三个维度各设一道闸，防止一个人把额度跑干。限流命中时返回可读的错误信息，别把上游返回的原始报文直接透给前端，那里面可能带内部标识。
3. 定降级上游报错或超时时，是排队重试、切备用通道，还是返回一条明确提示，提前定好写进代码。重试要设次数上限并做退避，否则会把一次上游抖动放大成一轮雪崩。
4. 记日志至少记下请求时间、用户标识、模型、耗时、状态、消耗量。日志里别把完整 Key 和敏感正文原样落盘，脱敏规则要在写日志的同一个函数里做，别指望后面补。
5. 压一轮本地能跑不等于线上能跑，先用真实域名、真实并发量走一轮，再到 /tools/speed-test 量一次链路延迟，把它当作后续对比的基线。

这套清单里的具体阈值，比如限流放多少、超时设几秒，取决于你的用户分布和上游表现，没有通用答案。站内的价格与限速资料页可以帮你判断上游大概的响应特征，但最终数字要按自己压测结果定。

上线前的排查顺序

按顺序排查比东改一处西改一处更快。下面这个顺序是从「先定性再动手」的角度排的，前两步没搞清楚就改代码，多半是在浪费时间。

• 第一步看报错来源：CORS 报错是浏览器拦住了响应，请求其实已经发出去了；先把这条区分清楚，别一上来就怀疑后端
• 第二步看 Key 的权限和时效：是不是全权限、是不是长期有效、能不能按需吊销，三项都占就该换方案
• 第三步看有没有账户级兜底：额度上限、消费告警、异常调用自动停用，缺哪项先去后台补上
• 第四步留切换预案：网关挂了或上游不稳时前端提示什么、后端切哪条路，写清楚放在团队能看到的地方

如果你的场景没有用户体系、也没有后端，那最务实的做法不是硬找技术绕路，而是接受这类应用只能停留在演示阶段，别接真实付费用户。

跨域是浏览器替你挡的一刀，它挡的是浏览器，不是你。