Giscus comments blocked by giscus.app CSP: frame-ancestors 'self' prevents iframe loading

[baoyu0]

问题描述

Giscus 评论区无法正常加载。在 All 文档页（如 /zh/tutorials/flux/flux-2-dev）底部点击 "💬 点击或滚动到此处加载评论" 后无响应，浏览器控制台报：

Framing 'https://giscus.app/' violates the following Content Security Policy directive: "frame-ancestors 'self'". The request has been blocked.

根因分析

giscus.app 在响应中返回了两道锁，阻止自己被 iframe 嵌入到任何外部站点：

1. Content-Security-Policy: frame-ancestors 'self'
2. X-Frame-Options: SAMEORIGIN

这两条是 giscus.app 服务器自己返回的，不是 docs.comfy.org 的问题。错误中的 frame-ancestors 'self' 指的不是本页面的 CSP（本页面的 frame-ancestors 允许 Mintlify 相关域名），而是 giscus.app 拒绝了被嵌入。

验证步骤

# giscus.app 在带有完整请求参数时仍返回 frame-ancestors 'self'
curl -s -D- "https://giscus.app/zh?origin=https://docs.comfy.org&session=&data-origin=https%3A%2F%2Fdocs.comfy.org&data-repo=comfy%2Fdocs&data-repo-id=R_kgDOJ7l03w&data-category=General&data-category-id=DIC_kwDOJ7l0384CiLkK&data-mapping=og%3Atitle&data-strict=0&data-reactions-enabled=1&data-emit-metadata=0&data-input-position=bottom&data-theme=preferred_color_scheme&data-lang=zh" | grep -iE "content-security-policy|frame-ancestors|x-frame-options"

# 输出:
# Content-Security-Policy: frame-ancestors 'self';

当前集成方式

目前的 giscus-comments.js 实现采用了标准的 Giscus 集成方式：

const script = document.createElement('script');
script.src = 'https://giscus.app/client.js';
script.setAttribute('data-repo', 'Comfy-Org/docs');
script.setAttribute('data-repo-id', 'R_kgDOLlassQ');
script.setAttribute('data-category', 'Announcements');
script.setAttribute('data-category-id', 'DIC_kwDOLlassc4CtQoz');
script.setAttribute('data-mapping', 'pathname');
// ...

Giscus 的标准 client.js 会在内部创建 <giscus-widget> Web Component，再由组件创建 iframe 到 giscus.app。这个 iframe 的 URL 会携带 origin 和 session 参数，giscus.app 的服务器应当据此动态生成 frame-ancestors 来放行。

但实际请求中 giscus.app 返回了锁定的 frame-ancestors 'self'，表明握手环节出了问题。

可能原因

1. giscus.app 侧 bug/回归 — 标准 client.js 创建的 iframe 在 origin 验证上出了问题
2. Mintlify 打包路径问题 — 由于 Mintlify 是 SPA (Next.js)，Giscus client.js 的加载时机可能与标准用法有差异，影响 session 生成
3. Cloudflare 缓存 — docs.comfy.org 经过 Cloudflare（CF-Ray: a1235c1fb846d2b7-FRA），如果 giscus.app 的响应被 CDN 缓存了 CSP 头，可能覆盖动态生成的 frame-ancestors

建议排查方向

• 直接在浏览器中触发 Giscus 加载后，查看 iframe 的实际 URL 和 giscus.app 的完整响应头
• 检查是否有 Cloudflare/中间层修改了 giscus.app 的 CSP 响应
• 尝试在 giscus-comments.js 中打印 iframe 的 src URL，确认 session 和 origin 参数是否正确传递

环境

• 页面: https://docs.comfy.org/zh/tutorials/flux/flux-2-dev
• 浏览器: Chrome (ERR_BLOCKED_BY_CLIENT)
• 平台: Mintlify (Next.js SPA)
• Giscus 集成: giscus-comments.js (自托管，非标准 CDN 引用)

[lin-bot23]

感谢详细排查，不过结论需要修正一下。

** 是 giscus.app 的正常行为**

Giscus 的标准集成不是通过传统 <iframe> 嵌入的——它用 <giscus-widget> Web Component + client.js，iframe 由 Web Component 内部动态创建，并通过 postMessage 跨域通信。giscus.app 的 server 会根据合法的 origin + session 参数动态放行，不会真的封锁所有外部站点。否则成千上万使用 Giscus 的站点都会挂。

curl 测试拿到的 frame-ancestors 'self' 是因为缺少 Web Component 生成的合法 session token，不属于正常的加载路径。

可能的真正原因

如果部分用户（或特定浏览器）无法加载，更可能是：

1. 浏览器扩展拦截（广告拦截器、隐私扩展经常拦截 Giscus）
2. Mintlify SPA 的脚本加载时机问题（giscus-comments.js 可能在 DOM 未就绪时执行）
3. giscus.app 偶发的 server-side 故障

建议排查

在复现环境下打开浏览器 DevTools → Network 面板，过滤 giscus，查看 client.js 是否成功加载、Web Component 是否注册、iframe 的完整 URL 和响应头，比 curl 测试更可靠。

---

补充：这个问题在 Mintlify 上可能不如在传统 SSG 站点上稳定，因为 Mintlify 是 SPA，DOM 替换和客户端路由切换可能影响 Web Component 的初始化时机。如果确认是加载时机问题，可以考虑加 MutationObserver 监听评论区容器出现后再注入 Giscus。