---
title: 构建失败
description: "将构建错误与解决方案匹配：配置错误、MDX 语法错误、文件缺失、OpenAPI 问题和超时。"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

在 **Deployments** 标签页中打开失败的构建，并将错误消息与下面的相应部分进行匹配。

## 查找错误

1. 转到项目的 **Deployments** 标签页
2. 点击失败的构建
3. 查看错误消息和日志

日志会准确显示发生了什么问题，以及问题所在的位置。

## 常见失败原因

### 配置无效

**错误：** "Invalid docs.json"

你的 `docs.json` 存在语法或架构错误。

**解决方法：**
1. 检查是否缺少逗号、括号或引号
2. 在本地运行 `jamdesk validate`
3. 对照[架构参考](/cn/config/docs-json-reference)

### 页面缺失

**错误：** "Page 'path/to/page' not found"

导航中引用的页面不存在。

**解决方法：**
- 确认文件存在
- 检查路径是否完全匹配（区分大小写）
- 不要在 `docs.json` 中包含 `.mdx` 扩展名

### MDX 语法错误

**错误：** "MDX compilation failed"

MDX 或 JSX 语法无效。

**常见原因：**
- 未闭合的标签：没有 `</Card>` 的 `<Card>`
- 未转义的大括号：使用 `{` 而不是 `\{`
- 无效的属性：使用 `title=value` 而不是 `title="value"`

### 图片缺失

**错误：** "Asset not found"

MDX 中引用的图片不存在。

**解决方法：**
- 检查图片路径是否正确
- 路径相对于文档目录
- 确认文件已提交到 Git

## 调试步骤

<Steps>
  <Step title="阅读错误信息">
    日志会准确告诉你失败的内容和位置。
  </Step>
  <Step title="在本地测试">
    运行 `jamdesk dev` 以重现错误。
  </Step>
  <Step title="验证配置">
    运行 `jamdesk validate` 以检查配置。
  </Step>
  <Step title="检查最近的更改">
    查看最近一次提交，找出问题所在。
  </Step>
</Steps>

## 仍无法解决？

如果你无法解决问题：

1. 复制完整的构建日志
2. 记下项目 ID
3. [联系支持](/cn/help/support/contact)

## 相关文章

<Columns cols={2}>
  <Card title="错误参考" icon="book" href="/cn/help/troubleshooting/error-reference">
    解释所有错误代码
  </Card>
  <Card title="CLI 概览" icon="terminal" href="/cn/cli/overview">
    在本地测试构建
  </Card>
</Columns>