故障排查

遇到问题时请从这里开始。每个小节都提供快速修复方法，并链接到帮助中心的完整指南。

构建失败

现象： dashboard 中构建状态显示为「Failed」。

快速检查：

1. 在本地运行 jamdesk dev，以便发现 MDX 语法错误
2. 确认 docs.json 是有效的 JSON（检查缺失的逗号和多余的尾随逗号）
3. 检查导航中列出的所有页面都存在对应的 .mdx 文件

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

自定义域名无法验证

现象： 添加 DNS 记录后，域名一直停留在「Pending」状态。

快速检查：

1. 对于子域名，请确认添加的是 CNAME 记录（而不是 A 记录）
2. 如果使用 Cloudflare，请将代理模式设置为 DNS only（灰色云朵图标）
3. 可在 whatsmydns.net 查看 DNS 传播情况

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

针对不同服务商的指引，请参阅 DNS 故障排查。

GitHub 仓库未出现

现象： 创建项目时找不到你的仓库。

快速检查：

1. 确认 Jamdesk GitHub App 已安装到该仓库所属的组织
2. 检查仓库访问权限是否设置为「All repositories」，或者已选中对应的仓库
3. 前往 github.com/settings/installations 重新授权

关于 webhook 和权限相关问题，请参阅 GitHub 问题。

分析数据缺失

现象： dashboard 显示访客数为零或数据陈旧。

快速检查：

1. 首次部署后，分析数据最长需要 24 小时才能显示
2. 广告拦截器和 Do Not Track 会导致部分访问无法被统计
3. 确认站点已部署并可公开访问

关于数据延迟或缺失的详细说明，请参阅 分析问题。

登录问题

现象： 无法登录，或反复被重定向到登录页面。

快速检查：

1. 清除浏览器对 dashboard.jamdesk.com 的缓存和 cookie
2. 尝试使用无痕或隐私窗口
3. 如果使用 GitHub SSO，请确认你的 GitHub 邮箱与 Jamdesk 账户一致

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

仍未解决？