构建故障排除
通过将错误信息与原因和解决方案对应起来，修复常见的构建失败。涵盖配置错误、缺失依赖、MDX 语法及图标问题。
构建日志会显示哪里出错了以及出错的位置。在下面找到你的错误信息。
查看错误详情
- 打开项目的 Deployments 标签页
- 点击失败的构建
- 阅读错误信息并滚动查看构建日志
日志会指出导致构建中断的具体文件和行号。
常见错误
配置错误
Invalid docs.json 表示你的配置文件无法解析。通常原因是多余的逗号、未闭合的括号或缺少引号。
查找缺失的逗号、括号或引号。
运行 jamdesk validate 查看具体错误。
修正错误并推送，以触发新的构建。
缺少页面
Page not found 表示你的导航指向了一个不存在的文件。请对照 docs.json 中的路径检查文件名。大小写必须完全一致。不要包含 .mdx 扩展名。
MDX 语法错误
MDX compilation failed 表示某个页面上的 MDX 或 JSX 格式有误。通常是未闭合的标签（有 <Card> 却没有对应的 </Card>）、未转义的字符（例如本应写作 \{ 的字面量 {），或无效的属性语法。
构建超时
Build exceeded time limit 表示构建运行时间超过了我们允许的上限。通常原因是体积大且未经优化的图片。请压缩图片、拆分非常大的页面，并删除不再发布的页面。
构建警告
警告不会导致构建失败，你的站点仍会正常发布。警告会出现在构建警告邮件中、Deployments 标签页中对应构建的条目里，以及你运行 jamdesk validate 或 jamdesk dev 时的终端中。
缺少图片
Image not found 警告某个页面引用了项目中不存在的图片。
Jamdesk 会将每个图片引用（Markdown 的 ，以及 <img loading="lazy"> 和 <Image> 标签上的 src）与你代码仓库中的文件进行核对。警告会注明页面、行号以及无法解析的路径。
请上传图片，或将路径指向一个存在的文件。路径区分大小写。以 / 开头的路径从项目根目录解析，其他路径则相对于当前页面解析。引用 photo.png 的写法在图片优化将其转换为 WebP 后仍然有效。
Jamdesk 会跳过外部 URL、data: URI 以及代码块中的图片语法。
调试步骤
日志会指出导致错误的具体文件和行号。从这里开始。
运行 jamdesk dev 在本地复现故障。
运行 jamdesk validate 检查 docs.json。运行 jamdesk broken-links 查找失效的内部链接。
查看你的最后一次提交。你是否添加了页面或修改了配置？
仍然无法解决？
如果以上方法都无法解决问题：
- 复制完整的构建日志
- 记下你的项目 ID（位于 URL 中）
- 联系支持