Chrome 扩展调用私有 API 的实战与禁忌：以豆包 AI 为例，为何前端无法直调？

AI 小团子

215人浏览 · 2026-06-24 12:16:01

AI 小团子 · 2026-06-24 12:16:01 发布

开篇：一个让无数开发者踩坑的“常识”问题

在浏览器插件开发中，有一个问题几乎每天都会在技术社区被反复提起——“为什么我的 Chrome 扩展直接调用 API 总是报 CORS 错误？”“为什么我把 API Key 写在前端代码里，上线没多久就被盗刷了？”

这些问题背后，藏着一个大多数前端开发者容易忽视的底层逻辑：Chrome 扩展的前端环境（content script、popup）和普通网页一样，受浏览器同源策略的严格约束。而当你试图在扩展中调用像豆包 AI 这样的大模型私有 API 时，这个“常识”就成了第一道坎。

2026 年 6 月，Google Chrome 被曝出多个与扩展相关的安全漏洞——CVE-2026-11168 涉及扩展组件信息泄露，CVE-2026-8004 涉及恶意扩展导致跨域数据泄露。这些漏洞的披露再次将 Chrome 扩展的 API 调用安全问题推到了聚光灯下。与此同时，豆包 AI 作为字节跳动火山引擎旗下的明星大模型产品，其 API 调用量正在指数级增长。

那么问题来了：Chrome 扩展到底能不能调用豆包 AI 的私有 API？如果能，正确的姿势是什么？如果不能，又是什么在阻止你？

本文将带你从原理到实战，彻底搞清楚这个问题。

一、问题拆解：为什么前端“不能”直接调用私有 API？

1.1 同源策略（CORS）：第一道天然屏障

先看一个最直接的场景。假设你在 Chrome 扩展的 content script 或 popup 页面中写了这样一段代码：

// ❌ 错误示范：在 content script 或 popup 中直接调用
fetch('https://ark.cn-beijing.volces.com/api/v3/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ek-xxxxxxxxxxxxx'
  },
  body: JSON.stringify({
    model: 'ep-xxxxxxxxxxxxxxx',
    messages: [{ role: 'user', content: '你好' }]
  })
})

运行结果是什么？浏览器会毫不犹豫地抛出 CORS 错误。

原因很简单：豆包 AI 的 API 服务器（ark.cn-beijing.volces.com）并没有在响应头中返回 Access-Control-Allow-Origin: * 或允许你的扩展源（chrome-extension://<extension-id>）。根据同源策略，前端页面（包括扩展的 content script 和 popup）只能请求与自身同源的资源。

但这里有个关键转折：Chrome 扩展的 background service worker（MV3）或 background page（MV2）发起的请求，完全不受 CORS 限制。浏览器信任扩展的 background 上下文，如同信任本地系统服务。这恰恰是解决问题的突破口——我们后面会详细展开。

1.2 API Key 泄露：比 CORS 更致命的第二道坎

假设你“绕过”了 CORS（比如在服务端配置了允许跨域），直接把 API Key 写在了前端代码里。恭喜你，你刚刚给自己埋了一颗定时炸弹。

2026 年 3 月，安全研究员发现超过 3,000 组活跃的 Google Cloud API 密钥暴露于公开网络，攻击者可通过网页抓取获取密钥，存取用户敏感文件或窃取 AI 调用配额。更令人震惊的是，这些密钥中有大量是以“AIza”前缀标识、被嵌入到客户端代码中的。

豆包 AI 的 API Key 同样面临这个风险。根据火山引擎官方文档，豆包 API 支持 token 和 signature 两种鉴权方式。无论哪种方式，一旦 API Key 或 Access Token 暴露在客户端，攻击者就可以：

盗刷你的调用额度：用你的 Key 随意调用模型，产生巨额费用
访问你的私有数据：如果 API 涉及文件上传或历史记录，敏感信息可能泄露
伪造请求：绕过你的业务逻辑，直接与模型交互

根据火山引擎官方文档，API Key 的格式示例为 ek-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx，这个 key 只在创建时显示一次。官方明确建议：禁止在客户端硬编码 App Secret。

1.3 私有 API 的“私有”二字意味着什么？

豆包 AI 的 API 属于私有 API——它需要鉴权、需要付费、需要开发者实名认证。这与那些完全公开、无需认证的公共 API 有着本质区别。

根据火山引擎官方文档，调用豆包 API 需要完成以下步骤：

注册火山引擎账号并完成实名认证
在火山方舟平台创建 API Key
开通豆包 AI 模型（如 Doubao-lite-128k 或 Doubao-pro-256k）
创建「推理接入点」获取 Endpoint ID

Endpoint ID 是你调用的模型地址，格式为 ep-xxxxxxxxxxxxxxx。API Key 是身份凭证，Endpoint ID 是目标地址——两者缺一不可。

这意味着，豆包 API 从设计之初就不是给前端直接调用的。它需要服务端参与鉴权、需要保护密钥、需要控制访问频率。前端直调，从根本上违背了这套安全模型的设计初衷。

二、核心原理：Chrome 扩展调用 API 的架构模型

2.1 Chrome 扩展的三种脚本上下文

在深入解决方案之前，先厘清 Chrome 扩展的三种脚本上下文及其 API 调用能力：

脚本类型	CORS 限制	可访问 Chrome API	典型用途
Content Script	✅ 受限制	部分	操作页面 DOM
Popup / Options	✅ 受限制	完整	用户界面交互
Background Service Worker (MV3)	❌ 不受限制	完整	后台逻辑、网络请求

Background Service Worker 是 Chrome 扩展 MV3 的核心变革。从 Chrome 121 开始，所有异步扩展 API 都支持 Promise。它运行在独立的后台进程中，不依赖任何页面上下文，因此不受 CORS 限制。

2.2 正确的调用链路

正确的架构应该是这样的：

┌─────────────────────────────────────────────────────────────┐
│                     Chrome 扩展                             │
│  ┌─────────────┐    ┌──────────────────────────────────┐   │
│  │  Popup/     │    │  Background Service Worker       │   │
│  │  Content    │───▶│  (MV3)                           │   │
│  │  Script     │    │  • 无 CORS 限制                  │   │
│  └─────────────┘    │  • 存储 API Key (chrome.storage) │   │
│                     │  • 发起 HTTP 请求                 │   │
│                     └──────────────┬───────────────────┘   │
└────────────────────────────────────┼───────────────────────┘
                                     │
                                     ▼
                          ┌─────────────────────┐
                          │   豆包 AI API 服务器  │
                          │  (火山引擎)          │
                          └─────────────────────┘

关键原则：所有需要鉴权的 API 调用，都必须由 Background Service Worker 发起。前端脚本（popup、content script）只负责 UI 交互和结果展示，通过 chrome.runtime.sendMessage 与 background 通信。

2.3 代码实战：正确的调用方式

Step 1：在 Background Service Worker 中封装 API 调用

// background.js (MV3 Service Worker)

// 从 chrome.storage 读取 API Key（用户配置时写入）
async function getApiKey() {
  const result = await chrome.storage.local.get(['doubaoApiKey']);
  return result.doubaoApiKey;
}

// 调用豆包 API 的核心函数
async function callDoubaoAPI(userMessage) {
  const apiKey = await getApiKey();
  if (!apiKey) {
    throw new Error('请先配置豆包 API Key');
  }

  const endpointId = await getEndpointId(); // 从 storage 读取

  const response = await fetch(
    'https://ark.cn-beijing.volces.com/api/v3/chat/completions',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        model: endpointId,
        messages: [
          { role: 'system', content: '你是一个智能助手' },
          { role: 'user', content: userMessage }
        ],
        stream: false  // 如需流式输出可设为 true
      })
    }
  );

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`API 调用失败: ${response.status} - ${errorText}`);
  }

  return await response.json();
}

// 监听来自 popup/content script 的消息
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'CALL_DOUBAO') {
    callDoubaoAPI(message.payload)
      .then(result => sendResponse({ success: true, data: result }))
      .catch(error => sendResponse({ success: false, error: error.message }));
    return true;  // 保持消息通道开放，用于异步响应
  }
});

Step 2：在 Popup 中发送消息

// popup.js

document.getElementById('sendBtn').addEventListener('click', async () => {
  const userInput = document.getElementById('input').value;

  // 发送消息到 background
  chrome.runtime.sendMessage(
    {
      type: 'CALL_DOUBAO',
      payload: userInput
    },
    (response) => {
      if (response.success) {
        const reply = response.data.choices[0].message.content;
        displayResult(reply);
      } else {
        showError(response.error);
      }
    }
  );
});

Step 3：配置 manifest.json

{
  "manifest_version": 3,
  "name": "豆包 AI 助手",
  "version": "1.0.0",
  "permissions": [
    "storage"
  ],
  "host_permissions": [
    "https://ark.cn-beijing.volces.com/*"
  ],
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_popup": "popup.html"
  }
}

注意：host_permissions 是 MV3 的关键配置，用于声明扩展需要访问哪些外部域名。

三、方案对比：四种调用路径的优劣分析

3.1 方案一：Background 直调（推荐 ✅）

架构：Popup/Content → Background → 豆包 API

维度	评价
安全性	⭐⭐⭐⭐⭐ API Key 不暴露给前端
CORS	✅ 完全绕过
复杂度	⭐⭐ 中等
实时性	⭐⭐⭐⭐⭐ 直接调用，延迟最低
可维护性	⭐⭐⭐⭐ 逻辑集中在 background

这是最推荐的方式。API Key 存储在 chrome.storage 中，仅 background 可访问，前端脚本完全接触不到敏感凭证。

3.2 方案二：自建后端代理

架构：Popup/Content → 自建后端 → 豆包 API

维度	评价
安全性	⭐⭐⭐⭐ Key 在后端，但增加了攻击面
CORS	✅ 后端可配置 CORS
复杂度	⭐⭐⭐⭐ 需要额外部署和维护
实时性	⭐⭐⭐ 多一跳，延迟增加
可维护性	⭐⭐⭐ 需维护后端服务

根据豆包 AI 官方集成指南，反向代理是规避 CORS 的推荐方式之一。通过 Nginx 或 Node.js 中间层统一转发请求，隐藏真实 API 地址并复用服务端凭证。在已有 Nginx 作为入口网关的企业环境中，可不改动任何应用代码，仅通过 Nginx 配置实现 API 路由转发。

但这种方式的问题在于：你多了一个需要维护的后端服务。对于个人开发者或轻量级插件来说，这增加了不必要的复杂度。

3.3 方案三：前端直调（❌ 不推荐）

架构：Popup/Content → 豆包 API

维度	评价
安全性	⭐ API Key 暴露在前端代码中
CORS	❌ 除非服务端配置 CORS
复杂度	⭐ 最简单
实时性	⭐⭐⭐⭐⭐
可维护性	⭐⭐

这是绝大多数新手踩的坑。虽然写起来简单，但安全隐患巨大。2026 年 3 月曝光的 Google API 密钥泄露事件已经用 3,000+ 个真实案例证明了这一点。

有人可能会说：“我用的是短期有效的 Access Token，不是永久 API Key。”但根据豆包 API 的鉴权机制，Token 仍然需要由 App ID 和 App Secret 生成——App Secret 同样不能暴露在前端。

3.4 方案四：Web SDK（官方方案）

架构：网站 → 豆包 Web SDK → 豆包 API

维度	评价
安全性	⭐⭐⭐⭐ SDK 内部处理鉴权
CORS	✅ SDK 自动处理
复杂度	⭐⭐ 简单
实时性	⭐⭐⭐⭐
可维护性	⭐⭐⭐⭐⭐ 官方维护

豆包 AI 官方提供了 Web SDK，适用于希望快速部署轻量级 AI 交互界面的场景。SDK 自动处理身份鉴权与消息路由，支持自定义样式与初始提示语。

但Web SDK 主要面向网站集成，而非 Chrome 扩展。在扩展中使用 SDK 需要额外处理跨上下文通信，反而增加了复杂度。

3.5 方案对比总结

方案	安全性	开发成本	维护成本	推荐度
Background 直调	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
自建后端代理	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
前端直调	⭐	⭐	⭐⭐	❌
Web SDK	⭐⭐⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐ (网站场景)

四、豆包 AI 调用实战：从 API Key 到第一个响应

4.1 获取 API Key 和 Endpoint ID

根据火山引擎官方文档，获取凭证的完整流程如下：

Step 1：进入火山方舟平台
访问 https://console.volcengine.com/ark

Step 2：创建 API Key

左侧菜单找到「API 密钥管理」
点击「创建 API Key」
命名后复制保存（只会显示一次！）

Step 3：开通豆包 AI 模型

进入「模型管理中心」
推荐开通：Doubao-lite-128k（轻量、免费额度足）或 Doubao-pro-256k（效果更好）

Step 4：创建推理接入点

左侧进入「在线推理」
点击「创建推理接入点」
选择模型、地区（如 cn-beijing）
创建完成后复制 Endpoint ID（格式：ep-xxxxxxxxxxxxxxx）

4.2 流式 vs 非流式：如何选择？

豆包 API 支持流式（stream: true）和非流式（stream: false）两种响应模式。

非流式：一次性返回完整结果，适合短文本场景。
流式：分块返回，用户体验更好（逐字输出），适合长文本生成。

根据实测数据，在相同测试环境（4核CPU/8GB内存/100Mbps带宽）下：

指标	REST/1.1	gRPC/HTTP2
平均延迟(100次)	320ms	210ms
最大QPS	82	153
带宽利用率	65%	92%

gRPC 在长连接场景优势明显。但对于 Chrome 扩展这种轻量级场景，REST API 已经足够。

流式响应的处理代码示例：

// background.js - 流式调用
async function callDoubaoAPIStream(userMessage) {
  const apiKey = await getApiKey();
  const endpointId = await getEndpointId();

  const response = await fetch(
    'https://ark.cn-beijing.volces.com/api/v3/chat/completions',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        model: endpointId,
        messages: [{ role: 'user', content: userMessage }],
        stream: true
      })
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const chunk = decoder.decode(value);
    // 解析 SSE 格式数据并逐块返回
    // ...
  }
}

4.3 错误处理与重试机制

根据豆包 API 实战经验，开发者常面临几个典型问题：

超时控制：模型推理时间不可预测，短文本可能毫秒级响应，长文本可能超过 30 秒
Token 消耗计算：输入输出 token 总和直接影响计费，中文与 token 的映射关系非 1:1
并发瓶颈：单个连接无法充分利用带宽，突发流量易触发限流

建议使用指数退避重试策略：

// 使用 tenacity 库实现指数退避重试
@retry(wait=wait_exponential(multiplier=1, max=10))
async function callDoubaoAPIWithRetry(text) {
  // API 调用逻辑
}

五、安全风险深度剖析：不仅仅是 API Key 泄露

5.1 2026 年 Chrome 扩展安全漏洞警示

2026 年 5 月至 6 月，Google Chrome 密集披露了多个与扩展相关的安全漏洞：

CVE-2026-11168：扩展组件存在信息泄露漏洞
CVE-2026-8004：恶意扩展可泄露跨域数据
CVE-2026-9964：Mac 版 Chrome 扩展的 Use-After-Free 漏洞，可执行任意代码
GHSA-X732-WXXW-QF5C：Chrome 149.0.7827.53 之前版本，扩展实现不当允许攻击者在沙箱内执行任意代码

这些漏洞揭示了一个残酷的现实：Chrome 扩展本身就是一个潜在的攻击面。即使你的代码写得再安全，如果用户安装了恶意扩展或浏览器版本存在漏洞，敏感数据仍可能泄露。

5.2 豆包 API 调用的特定安全风险

当 Chrome 扩展调用豆包 API 时，面临以下特有风险：

风险一：API Key 存储安全
即使 API Key 存储在 chrome.storage 中，如果扩展被恶意代码注入（如通过 XSS 或恶意 content script），攻击者仍可能通过 chrome.storage.local.get 读取到 Key。

风险二：请求伪造
攻击者可能通过伪造 chrome.runtime.sendMessage 消息，诱使 background 发起非预期的 API 调用。

风险三：响应数据泄露
如果 API 响应包含敏感信息（如用户对话历史、个人数据），而这些数据在前端被不当处理，可能造成泄露。

5.3 安全加固最佳实践

1. 最小权限原则
在 manifest.json 中只申请必要的权限。不要滥用 host_permissions，只添加实际需要调用的 API 域名。

2. 内容安全策略（CSP）
配置严格的 CSP，防止 XSS 攻击。豆包 AI 官方集成指南也将 CSP 配置列为五种官方集成方式之一。

3. 输入验证与输出过滤
对所有用户输入进行验证，对 API 响应进行脱敏处理。

4. 定期更新
保持 Chrome 浏览器和扩展自身更新到最新版本。前述 CVE 漏洞大多已在 Chrome 149.0.7827.53 及更高版本中修复。

5. 使用短期 Token
如果业务允许，优先使用短期有效的 Access Token 而非永久 API Key。

六、生态工具与竞品对比

6.1 豆包 vs 其他大模型 API 的调用差异

特性	豆包 AI	OpenAI	文心一言	通义千问
API 兼容性	火山引擎专属	OpenAI 格式	百度专属	阿里专属
鉴权方式	Bearer Token	Bearer Token	API Key + Secret	API Key
CORS 支持	❌ 不支持	❌ 不支持	❌ 不支持	❌ 不支持
Web SDK	✅ 有	✅ 有	✅ 有	✅ 有
免费额度	✅ 新用户有	❌ 付费	✅ 有	✅ 有

所有主流大模型的 API 都不支持前端直接调用。这不是豆包特有的限制，而是行业通行的安全规范。

6.2 开源工具与框架

OpenClaw：一个开源项目，支持将豆包、DeepSeek、Kimi 等网页版服务转化为 API 调用。但需要注意，这种方式本质上是模拟浏览器行为，存在稳定性和合规风险。

Midscene.js：AI 驱动的 UI 自动化测试工具，支持通过 Chrome 插件调用豆包等大模型。在配置中需要设置 MIDSCENE_MODEL_FAMILY: 'doubao-vision' 来指定豆包视觉模型。

快马平台：可一键生成集成豆包 AI 的浏览器插件，自动生成 manifest.json、背景脚本、内容脚本等完整框架。

6.3 部署方案对比

部署方案	适用场景	优势	劣势
Chrome Web Store 发布	公开插件	用户安装方便	需审核、有合规要求
本地加载未打包扩展	开发测试	快速迭代	仅开发者可用
企业私有部署	企业内部工具	安全可控	需维护更新机制

七、结论与实践建议

7.1 核心结论

Chrome 扩展不能直接调用豆包 AI 等私有 API，原因有三：

CORS 限制：content script 和 popup 受同源策略约束，无法跨域请求
API Key 泄露风险：前端代码中的密钥可被轻易提取，导致盗刷和攻击
私有 API 的设计初衷：豆包等大模型 API 从架构上就要求服务端参与鉴权

正确的解决方案是：在 Background Service Worker 中发起所有 API 调用，利用其无 CORS 限制的特性，同时将 API Key 安全存储在 chrome.storage 中，前端仅通过消息通信与 background 交互。

7.2 决策流程图

开始
  │
  ▼
需要调用豆包 API？
  │
  ├── 否 ──▶ 无需处理
  │
  ▼ 是
使用 Background Service Worker？
  │
  ├── 否（使用 MV2）──▶ 考虑升级到 MV3
  │
  ▼ 是
API Key 存储在哪？
  │
  ├── 前端代码中 ──▶ ❌ 立即迁移到 chrome.storage
  │
  ▼ 已安全存储
通过 chrome.runtime.sendMessage 通信？
  │
  ├── 否 ──▶ 重构为消息驱动架构
  │
  ▼ 是
  │
  ▼
  ✅ 安全调用

7.3 趋势判断

趋势一：Manifest V3 全面普及
Google 正在强制推动扩展从 MV2 迁移到 MV3。MV3 中 Background Service Worker 取代了 Background Page，对异步编程和生命周期管理提出了更高要求。开发者需要尽快适应这一变化。

趋势二：大模型 API 安全要求持续升级
2026 年接连曝光的 API Key 泄露事件，将推动各大模型平台收紧安全策略。未来可能会出现更严格的 IP 白名单、请求签名等机制，进一步增加前端直调的难度。

趋势三：浏览器端 AI 能力增强
Chrome 正在推出 Prompt API 等内置 AI 能力。未来部分 AI 推理可能直接在浏览器端完成，减少对云端 API 的依赖——但这不会取代云端大模型的需求，而是形成互补。

趋势四：开发工具链成熟
像快马、Midscene.js 等工具正在降低 Chrome 扩展的开发门槛。未来“一键生成集成大模型的浏览器插件”将成为常态，但安全架构的核心原则不会改变。

7.4 给开发者的最后建议

永远不要在客户端代码中硬编码 API Key——无论它看起来多么“安全”
优先使用 Background Service Worker 发起 API 请求——这是 MV3 的标准做法
保持 Chrome 和扩展更新——安全漏洞的修复往往在新版本中
申请最小权限——不要贪图方便而滥用 host_permissions
关注官方文档更新——火山引擎和豆包 API 的文档在持续迭代

最后，记住一句话：安全不是一蹴而就的功能，而是贯穿开发全过程的思维方式。在 Chrome 扩展调用私有 API 这个场景中，正确的架构设计比任何“奇技淫巧”都更重要。

天工造物局

北京人形旗下天工造物具身智能开源社区，聚焦具身天工与慧思开物两大平台

更多推荐

deck.gl TripsLayer 出租车轨迹动画示例实战：从示例运行到着色器原理

TripsLayer 是 deck.gl 中用于渲染**随时间流动的轨迹动画**（如出租车行程、物流路径、迁徙路线）的核心图层。本文以仓库中的最小独立示例 [examples/website/trips](https://link.gitcode.com/i/1442af8f442f4cff39ff546e050fceb5) 为骨架，带你完成从安装依赖、启动应用、理解曼哈顿出租车数据格式，到深入

天工造物局

LMCache CLI 实战：用 `lmcache kvcache clear` 管理运行中服务的 KV Cache 状态

本文是一份针对 LMCache 官方 CLI 命令 `lmcache kvcache` 的完整技术指南。该命令用于在**运行中的 LMCache 服务（MP HTTP server）**上管理 KV cache 状态，当前提供 `clear` 子命令，用于清空 L1（CPU 内存）层中缓存的全部 KV 数据。读完本文，你将掌握该命令的完整参数体系、退出码语义、终端/JSON/静默三种输出模式，并能

天工造物局

Bokeh 3.2.0 版本全解析：新 glyph 体系、WebGL 增强与交互工具升级

Bokeh 是 Python 生态中面向浏览器的交互式数据可视化库。本篇文章围绕 Bokeh ``3.2.0``（2023 年 6 月发布的 minor milestone）展开，系统梳理该版本引入的七项核心变更：Python 3.8 支持终止、``Axis.axis_label_orientation`` 轴标签方向控制、服务器资源自定义 host/port、``HSpan``/``VSpan`