Skip to main content
如果你的文档站点在运行几秒后出现 500 错误，或导航变慢，可能是 Cloudflare 防火墙拦截了对 Mintlify 资源的请求。

​
症状

  • 文档页面起初能加载，但 30–60 秒后崩溃并返回 500 错误
  • 页面间的客户端导航缓慢或异常
  • 对 /mintlify-assets/* 路径的请求在浏览器控制台中显示 403 错误
  • 来自 Cloudflare 的安全挑战提示“数据格式错误”或“可疑的 URL 模式”

​
根本原因

由于以下原因，Cloudflare 的 Web Application Firewall（WAF）和 Bot Fight Mode 可能会将 Mintlify 的资源请求判定为可疑：
  • 编码的 URL 参数中包含多个“%”符号
  • 含有特殊字符的较长 query 字符串
  • 来自空闲标签页的自动化请求

​
解决方案

创建一条 Cloudflare 防火墙规则，将 Mintlify 资产排除在安全检查之外。

​
创建防火墙例外

  1. 登录你的 Cloudflare 控制台
  2. 选择你的 domain
  3. 前往 Security > WAF
  4. 选择 Create rule
  5. 按以下设置配置规则：
Rule name: 允许 Mintlify 资源 When incoming requests match:
  • Field: Hostname
  • Operator: equals
  • Value: docs.yourdomain.com（替换为你的实际文档 domain）
And:
  • Field: URI Path
  • Operator: starts with
  • Value: /mintlify-assets/
Then:
  • Action: Skip
  • Select: All remaining custom rules、Managed rules 和 Super Bot Fight Mode
  1. 启用 Log 以跟踪匹配的请求
  2. 选择 Deploy

​
验证规则

部署后：
  1. 在浏览器中打开文档站点
  2. 将页面闲置 2–3 分钟
  3. 在各页面之间切换
  4. 在浏览器控制台中检查是否出现 403 错误
如果问题仍然存在，请核对规则配置：
  • 确保主机名与文档的 domain 完全一致
  • 确认 URI 路径使用 starts with（而非 contains）
  • 不要在路径的值中包含通配符（*）
  • 确认该规则已启用并完成部署

​
常见错误

  • 将 contains 运算符用于 /mintlify-assets/* - * 会被视为普通字符，而非通配符
  • 对 URI Path 使用 equals - 这只会匹配精确路径 /mintlify-assets/，不匹配子路径
  • 忘记跳过 Bot Fight Mode - 必须在 skip 操作中显式包含
  • 主机名错误 - 必须与实际的文档 domain 完全匹配

​
其他故障排除

如果防火墙例外未能解决问题：
  1. 在 Cloudflare 的 Security > Events 日志中检查被拦截的请求
  2. 验证你的 Cloudflare Worker（若使用自定义子路径）是否正确转发了 Host 头
  3. 暂时将 Security Level 设置为 “Essentially Off”，以确认问题是否由 Cloudflare 引起
  4. 检查是否有自定义 Page Rules 会覆盖该防火墙例外

​
可用配置示例

规则:允许 Mintlify 资源
状态:已启用

当传入请求匹配时:
  (http.host eq "docs.flashnet.xyz" and starts_with(http.request.uri.path, "/mintlify-assets/"))

然后:
  跳过:所有剩余的自定义规则、托管规则、超级机器人对抗模式
  日志:已启用

Related topics

Cloudflare自定义域名Custom domain