浏览器拒绝显示框架 — X-Frame-Options DENY

症状

遇到“浏览器拒绝显示框架 — X-Frame-Options DENY”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

• Console: 因设置了 X-Frame-Options 为 DENY，拒绝在框架中显示
• 嵌入的仪表盘或登录页显示空白框架
• 同源可用，跨源失败

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

curl -sI https://embedded.example.com | grep -i "x-frame-options\|content-security-policy"

头的值表明是直接拒绝嵌入，还是仅限特定祖先。

步骤 2

DevTools → Network → select the framed document → Response Headers

确认是哪个头阻止了框架，可区分 CSP 规则与 X-Frame-Options。

常见诱因（按出现频率排序）：

• 被嵌页面发送 X-Frame-Options: DENY
• CSP 的 frame-ancestors 未包含嵌入源
• 两个头都被设置且相互冲突

根因

当 X-Frame-Options 为 DENY/SAMEORIGIN 且嵌入方不同，或 CSP 的 frame-ancestors 未包含嵌入方时，浏览器拒绝在框架中渲染该文档。这些头是站点的点击劫持防护。

修复

用列出具体允许嵌入方的 CSP frame-ancestors 取代 X-Frame-Options；ALLOW-FROM 已废弃，应使用 frame-ancestors。若确需被嵌入，切勿用 DENY。

注意：允许嵌入会重新引入点击劫持风险；应把 frame-ancestors 限定到具体可信源。

# allow embedding only by a specific origin
add_header Content-Security-Policy "frame-ancestors 'self' https://app.example.com" always;

# do NOT set a conflicting X-Frame-Options: DENY alongside it
# (frame-ancestors supersedes X-Frame-Options in modern browsers)

验证

从预期源嵌入并确认框架渲染；验证未列出的源仍被阻止。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。