FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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。
示意图由两个区块组成。左边是客户页面(app.client.example),第一道关卡是 frame-src:规定页面可以从哪里加载 iframe,缺省时浏览器回退到 default-src。右边是你的组件(widget.vendor.example),第二道关卡是 frame-ancestors:规定哪些父页面可以嵌入它,只有通过 HTTP 头发送才生效。一条虚线箭头从组件指向客户页面,标注“嵌入到”。
只有双方都允许,iframe 才会显示:客户页面的 frame-src 和组件的 frame-ancestors。遇到空白框时,先弄清是哪一侧在拒绝。

预发布环境上的演示一切顺利,客户点头认可,上线日期也定了下来。到了部署到真实客户门户的那天早上,原本留给 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 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力Python FDE 接手 TypeScript 仓库,真正的新概念只有三个结构类型、Promise 和 npm 是新内容,其余都能对应到 Python,另有一项合并前必跑的类型检查。