内容安全策略（CSP）配置

面向实施严格安全策略的反向代理、防火墙和网络的 domain 白名单与响应头配置

内容安全策略（CSP）是一项安全标准，通过控制网页可加载的资源来帮助防止跨站脚本（XSS）攻击。Mintlify 默认提供 CSP，能保护大多数站点。如果你的文档托管在会覆盖默认 CSP 的反向代理或防火墙之后，你可能需要配置 CSP 响应头，确保相关功能正常运行。

​

CSP 指令

以下 CSP 指令用于控制可加载的资源：

• script-src: 控制可执行的脚本
• style-src: 控制可加载的样式表
• font-src: 控制可加载的字体
• img-src: 控制可加载的图像、icon 和徽标
• connect-src: 控制可连接的 URL，用于 API 调用和 WebSocket 连接
• frame-src: 控制可在 frame 或 iframe 中嵌入的 URL
• default-src: 其他指令未显式设置时的回退项

​

域名白名单

域名	用途	CSP 指令	必需
d4tuoctqmanu0.cloudfront.net	KaTeX CSS、字体	style-src、font-src	必需
*.mintlify.dev	文档内容	connect-src、frame-src	必需
*.mintlify.com	控制台、API、Analytics 代理	connect-src	必需
leaves.mintlify.com	AI 助手 API	connect-src	必需
d3gk2c5xim1je2.cloudfront.net	图标、图像、标志	img-src	必需
d1ctpt7j8wusba.cloudfront.net	Mint 版本与发布文件	connect-src	必需
mintcdn.com	图像、网站图标（favicon）	img-src、connect-src	必需
*.mintcdn.com	图像、网站图标（favicon）	img-src、connect-src	必需
api.mintlifytrieve.com	搜索 API	connect-src	必需
cdn.jsdelivr.net	用于 OG 图片的表情符号资源	script-src、img-src	必需
fonts.googleapis.com	Google Fonts	style-src、font-src	可选
www.googletagmanager.com	Google Analytics/GTM	script-src、connect-src	可选
cdn.segment.com	Segment 分析	script-src、connect-src	可选
plausible.io	Plausible 分析	script-src、connect-src	可选
us.posthog.com	PostHog 分析	connect-src	可选
cdn.getkoala.com	Koala 分析	script-src	可选
tag.clearbitscripts.com	Clearbit 追踪	script-src	可选
cdn.heapanalytics.com	Heap 分析	script-src	可选
chat.cdn-plain.com	Plain 聊天小部件	script-src	可选
chat-assets.frontapp.com	Front 聊天小部件	script-src	可选
browser.sentry-cdn.com	Sentry 错误追踪	script-src、connect-src	可选
js.sentry-cdn.com	Sentry JavaScript SDK	script-src	可选

​

示例 CSP 配置

只包含你实际使用的服务的 domain。删除你尚未为文档配置的任何 Analytics 域名。

Content-Security-Policy:
default-src 'self';
script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net www.googletagmanager.com cdn.segment.com plausible.io
us.posthog.com cdn.getkoala.com tag.clearbitscripts.com cdn.heapanalytics.com chat.cdn-plain.com chat-assets.frontapp.com
browser.sentry-cdn.com js.sentry-cdn.com;
style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com;
font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com;
img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net;
connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com
api.mintlifytrieve.com www.googletagmanager.com cdn.segment.com plausible.io us.posthog.com browser.sentry-cdn.com;
frame-src 'self' *.mintlify.dev;

​

按代理类型分类的常见配置

大多数反向代理都支持添加自定义请求头。

​

Cloudflare 配置

创建一个 Response Header Transform 规则：

1. 在你的 Cloudflare 控制台中，进入 Rules > Overview。
2. 选择 Create rule > Response Header Transform Rule。
3. 配置该规则：

• Modify response header：设置为 Static
  • Header name：Content-Security-Policy
  • Header value：
    default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net; connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src 'self' *.mintlify.dev;
    

4. 部署该规则。

​

配置 AWS CloudFront

在 CloudFront 中添加一个响应标头策略：

{
"ResponseHeadersPolicy": {
    "Name": "MintlifyCSP",
    "Config": {
    "SecurityHeadersConfig": {
        "ContentSecurityPolicy": {
        "ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net; connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src 'self' *.mintlify.dev;",
        "Override": true
        }
      }
    }
  }
}

​

Vercel 配置

将以下内容添加到你的 vercel.json：

{
"headers": [
    {
    "source": "/(.*)",
    "headers": [
        {
        "key": "Content-Security-Policy",
        "value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net; connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src 'self' *.mintlify.dev;"
        }
      ]
    }
  ]
}

​

疑难排解

在浏览器控制台中定位 CSP 违规：

1. 打开浏览器的开发者工具。
2. 切换到 Console 标签页。
3. 查找以下前缀的错误：
   • Content Security Policy: The page's settings blocked the loading of a resource
   • Refused to load the script/stylesheet because it violates the following Content Security Policy directive
   • Refused to connect to because it violates the following Content Security Policy directive