AI 组件在预发布正常,上了客户生产环境却一片空白
问题多半出在 iframe 两侧的两份 CSP 白名单,先认清是哪一侧拒绝,能省下一周邮件往来。
要点速览
- iframe 被拦截时检查两处:客户页面的 frame-src(或 default-src),以及组件页面的 frame-ancestors。frame-ancestors 只有通过 HTTP 头发送才生效。
- iframe 把组件与客户页面隔离开。带 Shadow DOM 的 Web Component 只隔离样式和 ID,其代码仍受客户页面 CSP 约束。
- 用每次请求新生成的 nonce 代替 unsafe-inline;postMessage 要发往明确的 targetOrigin,并始终校验收到消息的 origin。
预发布环境上的演示一切顺利,客户点头认可,上线日期也定了下来。到了部署到真实客户门户的那天早上,原本留给 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 写在 <meta> 标签里不起作用,必须通过 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。第一步是在响应头里声明你这一侧:
Content-Security-Policy: frame-ancestors https://app.client.example
在客户一侧,假设当前响应头只有 default-src 'self'。按照回退规则,iframe 会被拦截。请客户只加一条指令,而不是放宽 default-src:
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 属性:
<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 明确表示,跳过这一步会为跨站脚本攻击打开大门。
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 要求,使组件在安全策略严格的系统上顺利进入生产环境。
比起只会要求开放权限的人,安全团队更信任理解他们策略的人。
这篇文章对你有帮助吗?
感谢你的反馈!
8 个信源
- Content-Security-Policy: frame-ancestors directive - HTTP | MDN · 2026-08-27
- Content-Security-Policy: frame-src directive - HTTP | MDN
- <iframe> HTML inline frame element - HTML | MDN
- Web Components - Web APIs | MDN
- Window: postMessage() method - Web APIs | MDN
- Content Security Policy (CSP)
- About the widget security policy | Customer Service Management | Atlassian Support
- Content Security Policy | Privacy & Security | Chrome for Developers