技术文章

外部链接将在新标签页打开。

微信小程序 / H5 调用第三方 API 的正确姿势:密钥留在服务端

一句话回答

微信小程序与 H5 的代码都运行在用户设备上,任何下发到前端的第三方 API 密钥都应视为已经公开。可行的做法是前端只调用自己的服务端接口,由服务端持有密钥、附加鉴权并调用第三方;H5 还需考虑浏览器同源策略,小程序则需按微信官方规则配置服务器域名。具体配置项与最新限制本次材料未提供,待核实。

微信小程序和 H5 有一个共同点:代码最终运行在用户的设备上。因此“正确姿势”的第一条不是选哪个请求库,而是判断密钥落在哪一侧。凡是打包进前端包、写进页面脚本、存进 localStorage 或小程序 storage 的第三方 API 密钥,都应视为已经公开。可落地的做法是:前端只调用你自己的服务端接口,第三方密钥由服务端持有并附加。

一、先判断密钥是否下发到了客户端#

  • H5:浏览器可以查看源码与 Network 面板,前端出现的 key 能被直接复制。
  • 小程序:代码包可被解包,本地存储可被读取;变量混淆只是提高阅读成本,不构成保护。
  • 服务端:密钥只出现在部署环境变量或密钥管理服务中,可以轮换、可以撤销、可以按调用方限流。

所以判断标准不是“前端做了没有加密”,而是“密钥是否曾经下发到客户端”。把明文换成另一段可被还原的字符串,并不改变它已经离开服务端这一事实。

二、三条调用路径的差别#

路径密钥位置浏览器同源策略微信侧约束适用场景
前端直连第三方客户端受 CORS 约束需符合服务器域名要求公开、无需密钥的接口
前端 → 自建代理 → 第三方服务端不涉及只约束到代理域名需要密钥或计费的接口
前端 → 云函数/边缘函数 → 第三方函数运行环境不涉及按平台规则配置无自建服务时的过渡方案

H5 直连会受浏览器同源策略约束,第三方需要返回允许来源的 CORS 响应头,否则请求在浏览器侧就会被拦下。小程序不走浏览器的 CORS 机制,但需要按微信官方要求配置服务器域名并使用 HTTPS。具体配置入口、域名类型与数量限制属于会变化的平台规则,本次材料未提供,待核实。

三、代理层需要定下来的几件事#

  1. 只暴露业务语义路径,例如 /api/weather,不要做成“传什么 URL 就转发什么”的通用通道,否则代理会变成开放转发器。
  2. 鉴权放在代理层:用户登录态校验在这里做,第三方密钥只用于出站,两者不要混用。
  3. 定好超时与重试预算:重试只对幂等请求开启,并设置次数上限。
  4. 统一错误包络:不把第三方原始错误体、请求头和密钥回传给前端。
  5. 日志脱敏:记录请求 ID 与状态码,不记录完整请求体与鉴权头。

示意代码(未执行)

下面的片段用于说明“密钥只出现在服务端”这一结构,属于伪代码,混合了 Express 风格的路由与响应方法,未实际运行,也不能直接用于生产。运行环境假设为支持全局 fetch 与 AbortController 的 Node.js 版本。

// 未执行的示意代码:前端只请求 /api/weather,由服务端附加密钥
app.get('/api/weather', async (req, res) => {
  // 1. 先校验调用方身份,未通过直接返回 401
  // 2. 只接受白名单内的参数,避免把任意输入拼进上游请求
  const upstream = new URL('https://api.example.com/v1/weather'); // example.com 为占位域名
  upstream.searchParams.set('city', String(req.query.city ?? ''));

  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 5000); // 超时预算
  try {
    const r = await fetch(upstream, {
      headers: { Authorization: `Bearer ${process.env.THIRD_PARTY_KEY}` }, // 密钥来自环境变量
      signal: controller.signal
    });
    if (!r.ok) {
      return res.status(502).json({ error: 'upstream_failed' }); // 不回传上游原始错误
    }
    return res.status(200).json(await r.json());
  } catch (e) {
    return res.status(504).json({ error: 'upstream_timeout' });
  } finally {
    clearTimeout(timer);
  }
});

THIRD_PARTY_KEY 是占位名称,示例中的域名与路径均为演示用途,不构成对任何真实接口的调用说明。

四、上线前的核对项#

  • 前端包、源码、构建产物中是否还残留密钥字符串;
  • 密钥能否在不重新发版的情况下轮换,撤销流程是否演练过;
  • 代理层是否限制可转发的目标,是否对单用户设了频率上限;
  • 小程序后台配置的服务器域名是否与实际请求域名一致;
  • 超时、重试、错误包络是否已经写进接口约定;
  • 日志与埋点中是否排除了鉴权头与敏感参数。

五、本文没有覆盖的部分#

不同第三方 API 的鉴权方式差异很大,例如签名计算、OAuth 授权码流程、用 AppID 与 AppSecret 换取临时凭证等,这些都必须以对应服务的官方文档为准。本次没有可用的正文素材,因此不给出具体的参数名、有效期与版本结论,相关细节待核实。同样,微信小程序服务器域名的最新规则、H5 预检请求的具体行为,也应以官方文档和实际环境验证为准,本文只讨论“密钥不下发到前端”这一条稳定边界。

作者:沐小悠

本文约 7 分钟读完 · 关键词:微信小程序调用第三方API、H5 跨域请求、API 密钥安全、BFF 代理层、服务器域名配置

更多文章 GET 示例接口

「」标签下的其他文章