故障排除

每个部分都提供快速修复方法，并链接到帮助中心的完整指南。

构建失败

您的仪表板显示构建状态为“Failed”。常见原因包括：

• MDX 页面中存在损坏的导入或组件。
• docs.json 无效（括号未闭合、最后一个数组项后有多余逗号）。
• docs.json 导航中列出的页面在 .mdx 文件中不存在。

推送前请运行 jamdesk dev。它可以在本地捕获前两类问题。

有关具体错误代码，请参阅 构建失败 和 错误参考。

自定义域名无法验证

如果添加 DNS 记录后域名仍显示“Pending”，请按以下顺序检查：

1. 确认已添加 _jamdesk.<hostname> TXT 记录。没有该记录，路由将无法激活。缺少 TXT 记录是域名处于 Pending 状态的最常见原因。hostname 指您要验证的完整域名（对于 docs.example.com，TXT 记录名称为 _jamdesk.docs.example.com）。
2. 确认子域名添加的是 CNAME 记录（而不是 A 记录）。
3. 如果您使用 Cloudflare，请将两条记录的代理设置为 仅 DNS（灰色云朵）。
4. 在 whatsmydns.net 上检查 DNS 传播情况。

# Verify the TXT verification record
dig TXT _jamdesk.docs.yourdomain.com

# Verify your CNAME is resolving
dig CNAME docs.yourdomain.com

即使 dig 已显示您的记录解析成功，仪表板仍可能在长达 30 分钟内报告“Pending”。验证程序依赖上游解析器，而这些解析器会缓存否定性 DNS 响应。请等待半小时后再排查更深层的问题。

DNS 故障排除 介绍了各服务商的特定注意事项。

有效的 OpenAPI 规范无法验证

jamdesk dev 会拒绝有效的规范，并报出类似 #/servers/0/variables/host must NOT have unevaluated properties 的错误。这通常出现在带有 description 的服务器变量，或仅包含 name 的 license 上。问题出在 CLI 自带的 OpenAPI 3.1 元模式副本上。npm 12 默认会阻止包安装脚本运行，因此修正该模式中两个已知缺陷的步骤被跳过了。

请升级 CLI。1.1.167 及更高版本会在验证时修复该模式：

npm install -g jamdesk@latest

如果您固定使用的是较旧版本，请运行 npm install -g --allow-scripts=jamdesk jamdesk，以允许安装脚本执行。

GitHub 仓库未显示

仓库未出现在列表中，通常意味着 Jamdesk GitHub App 未安装在该仓库所属的组织上。另外，仓库访问权限可能被设置为“Selected repositories”但未包含您的仓库。请在 github.com/settings/installations 重新授权，并授予“All repositories”或特定仓库的访问权限。

有关 Webhook 和权限问题，请参阅 GitHub 问题。

分析数据缺失

站点首次部署后，分析数据最长需要 24 小时才会显示。广告拦截器和“请勿跟踪”设置会导致部分访问未被计入。您的数据始终会略少于服务器日志。如果仪表板仍显示零访客，请确认站点已部署且可公开访问。

分析问题 深入介绍了数据延迟或缺失的情况。

登录问题

如果您无法登录或被重定向回登录界面，请清除 dashboard.jamdesk.com 的缓存和 Cookie，然后尝试使用无痕窗口。GitHub 登录要求您的 GitHub 邮箱与 Jamdesk 账户上的邮箱一致。

有关账户恢复步骤，请参阅 登录问题。

仍然无法解决？