# AI 组件在预发布正常，上了客户生产环境却一片空白

> 问题多半出在 iframe 两侧的两份 CSP 白名单，先认清是哪一侧拒绝，能省下一周邮件往来。

原文: https://fdetimes.net/zh/guides/embed-ai-widget-iframe-web-component-csp/

预发布环境上的演示一切顺利，客户点头认可，上线日期也定了下来。到了部署到真实客户门户的那天早上，原本留给 AI 助手的位置只剩一个空白框，控制台里只有一行红字：“Refused to frame”。

你的代码一行都没改，变的是它周围的页面：客户的生产站点启用了严格的内容安全策略（CSP），而预发布环境没有。

能看懂两个页面之间这道边界的工程师，一个上午就能解决问题；看不懂的，要和客户的安全团队来回发一周邮件。

本文讲解如何看懂这道边界：该选 iframe 还是 Web Component，每种方案需要客户开放什么，以及如何让两个页面互相通信而不留下新的漏洞。

## iframe 有两道关卡

Chrome for Developers 关于 CSP 的文档从一个朴素的事实讲起：默认情况下，页面要求运行什么代码，浏览器就运行什么代码。因此页面需要声明一份可信来源的白名单。到了 iframe 这里，白名单有两份，两侧各一份。

在客户页面上，`frame-src` 规定该页面可以从哪里加载 iframe。在你的组件页面上，`frame-ancestors` 规定哪些父页面可以嵌入它。MDN 明确指出，这两条指令的方向正好相反。面对空白框，第一个问题是：哪一侧在拒绝？

有两个陷阱常常导致误判。第一个：如果客户的 CSP 里没有 `frame-src`，浏览器会先回退到 `child-src`，再回退到 `default-src`。一句看似无害的 `default-src 'self'` 就足以拦下你的 iframe，哪怕客户坚称自己“没有拦截任何 frame”。

第二个陷阱在你这一侧：`frame-ancestors` 写在 `` 标签里不起作用，必须通过 HTTP 头发送。如果组件部署在静态托管上、策略写在 HTML 里，实际上等于什么都没声明。应当在 CDN 或服务器上配置。

## iframe 还是 Web Component：先选边界，再选技术

Web Components 由三部分组成：自定义元素、Shadow DOM 和 HTML 模板。按 MDN 的说法，它的目的是封装，以减少与宿主页面在命名和样式上的冲突。Shadow DOM 把组件的样式和 ID 与页面其余部分隔开，客户的 CSS 不会弄坏你的按钮，反之亦然。

容易误读的一点是：这种隔离是视觉上的，不是安全边界。自定义元素直接运行在客户的文档中。

结论随之而来。组件既然位于客户页面中，它的脚本和 API 调用就必须和页面上其他脚本一样，通过页面的 CSP。而放在独立源上的 iframe 会把组件作为独立文档加载，双方通过 `postMessage` 交换数据，这条通道的两端都由你掌控。

**要点:** 嵌入的组件遵循客户页面的规则，而不是你的规则。

由此可以得出一条实用的选择原则。如果组件需要融入界面、读取页面状态，而客户也接受在自己页面里运行你的代码，Web Component 是合理的选择。如果组件持有令牌、对话历史或终端用户数据，而你不希望页面上任何其他脚本碰到它们，就选 iframe。

## 示例：客户门户里的语音助手

假设你要在 `https://app.client.example` 上加一个支持语音输入的 AI 助手。组件位于 `https://widget.vendor.example`，API 位于 `https://api.vendor.example`。由于组件持有对话会话，你选择了 iframe。第一步是在响应头里声明你这一侧：

```http
Content-Security-Policy: frame-ancestors https://app.client.example
```

在客户一侧，假设当前响应头只有 `default-src 'self'`。按照回退规则，iframe 会被拦截。请客户只加一条指令，而不是放宽 `default-src`：

```http
Content-Security-Policy: default-src 'self';
  script-src 'self' 'nonce-{fresh-value-per-request}' 'strict-dynamic';
  frame-src https://widget.vendor.example
```

加载组件的代码片段是内联脚本，因此需要 nonce。Infobip 在 Live Chat 组件文档中推荐使用 nonce，并且不建议使用 `unsafe-inline`，除非客户的指令里本来就有它。Chrome for Developers 补充说，nonce 必须每次请求重新生成，而且不可被猜到。写死在模板里的 nonce 起不到任何保护作用。

为什么要用 `strict-dynamic`？Atlassian 在其组件文档中解释，加载组件的脚本更新频繁，基于哈希的 CSP 不太合适，因此推荐使用 `strict-dynamic`。

Atlassian 还要求客户对组件所在的主机开放 `frame-src`，与上面的示例一致。

接下来是语音部分。iframe 标签需要 `allow` 属性：

```html
<iframe src="https://widget.vendor.example/chat?tenant=client"
        allow="microphone"
        sandbox="allow-scripts allow-same-origin allow-forms"></iframe>
```

MDN 指出，`allow` 只能在页面 `Permissions-Policy` 响应头已设定的策略基础上进一步收紧，不能替代这个响应头。如果客户发送了 `Permissions-Policy: microphone=()`，无论 iframe 标签怎么写，你的麦克风按钮都不会有声音。这个问题要在需求调研阶段问清楚，而不是等到上线当天。

`sandbox` 属性要仔细看。MDN 强烈警告：当嵌入内容与父页面同源时，不要同时使用 `allow-scripts` 和 `allow-same-origin`，因为嵌入页面这时可以移除自己的沙箱。

上面的配置之所以可以接受，只是因为组件位于独立的源上。如果有一天客户提议把组件代理到 `app.client.example/assistant` 下“整理一下”，那就是去掉其中一个标志的时候。

## 忘了校验 origin，postMessage 就是一道后门

客户页面常常需要把上下文传给组件，比如用户正在查看哪一笔订单。组件也需要向外报告，比如对话已转交人工客服。这种通信的标准通道是 `postMessage`，MDN 为它定了两条规则。

发送时，始终指定具体的 `targetOrigin`，绝不用 `"*"`，因为目标窗口可能已经跳转到别处，数据会落到陌生人手里。接收时，校验 `origin`，最好同时校验 `source`。MDN 明确表示，跳过这一步会为跨站脚本攻击打开大门。

```js
const WIDGET = 'https://widget.vendor.example';
const frame = document.querySelector('iframe');

frame.contentWindow.postMessage({ type: 'context', orderId: 'A123' }, WIDGET);

window.addEventListener('message', (e) => {
  if (e.origin !== WIDGET) return;
  if (e.source !== frame.contentWindow) return;
  if (e.data?.type === 'handoff') openAgentPanel(e.data.ticketId);
});
```

组件一侧反过来做同样的事，合法 origin 列表应当来自每个租户的配置，而不是写死在代码里。

## 让上线推迟一周的错误

最常见的是改错了一侧：其实是你自己的 `frame-ancestors` 在拦截，却请客户放宽 CSP，或者反过来。第二种是要求过多。客户会拒绝 `default-src *` 或 `unsafe-inline`，而且理由充分。

第三种是以为选了 iframe 就只需要申请 `frame-src`。Infobip 明确说明，它的 Live Chat 组件虽然通过 iframe 加载，客户仍需同时开放 `script-src`、`connect-src`、`frame-src` 和 `style-src`。

即使组件位于 iframe 中，客户页面上加载它的那段代码仍然要通过客户的 CSP。所以从一开始就交出完整清单，而不是每失败一次就让客户再开一条指令。

## 去见安全团队时带什么

这份清单应当整理成一份事先准备好的文档——“嵌入组件的 CSP 要求”，逐条列出每条指令、每个域名以及需要它的理由。有了它，会议可以逐行推进，而不是在问题之间兜圈子。

这份文档也是写进简历的最好证据。与其写“前端集成”，不如写：设计了嵌入配置和 CSP 要求，使组件在安全策略严格的系统上顺利进入生产环境。

比起只会要求开放权限的人，安全团队更信任理解他们策略的人。

**本周动手试试:**

- 在一个 CSP 严格的页面（银行或大型 SaaS 产品）上打开 DevTools，读一读 Content-Security-Policy 响应头，自己回答：来自陌生域名的 iframe 能否加载？如果能，是哪条指令允许的？
- 搭一个 HTML 页面，在 localhost 上嵌入来自第二个源的 iframe，实现带 origin 校验的双向 postMessage，再从第三个源发送消息，确认它会被拒绝。
- 为你负责的产品起草一页“嵌入组件的 CSP 要求”，列出每条指令、每个域名及其理由。

## 信源

- [Content-Security-Policy: frame-ancestors directive - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors)

- [Content-Security-Policy: frame-src directive - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-src)

- [<iframe> HTML inline frame element - HTML | MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe)

- [Web Components - Web APIs | MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)

- [Window: postMessage() method - Web APIs | MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)

- [Content Security Policy (CSP)](https://www.infobip.com/docs/live-chat/content-security-policy-csp-in-live-chat)

- [About the widget security policy | Customer Service Management | Atlassian Support](https://support.atlassian.com/customer-service-management/docs/about-the-widget-security-policy/)

- [Content Security Policy | Privacy & Security | Chrome for Developers](https://developer.chrome.com/docs/privacy-security/csp)
