---
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.

使用 Ctrl/Cmd+F 查找错误代码，或按类别浏览：配置、MDX、OpenAPI、超时和资源。

## 配置错误

### INVALID_DOCS_JSON

**消息：**“无效的 docs.json 配置”

**原因：**您的 `docs.json` 文件存在语法错误或无效值。

**修复：**
1. 在本地运行 `jamdesk validate` 查看详细错误
2. 检查是否缺少逗号、括号或引号
3. 验证所有值是否符合预期架构

### MISSING_PAGE

**消息：**“导航中引用的页面 'path/to/page' 不存在”

**原因：**`docs.json` 导航中列出的页面不存在。

**修复：**
1. 检查指定路径下是否存在该文件
2. 验证 `docs.json` 中的路径是否与实际文件名匹配（不含 `.mdx`）
3. 路径区分大小写，请检查大小写是否正确

### INVALID_FRONTMATTER

**消息：**“'path/to/page' 中的 frontmatter 无效”

**原因：**MDX 文件顶部的 YAML frontmatter 格式错误。

**修复：**
1. 确保 frontmatter 以 `---` 开始和结束
2. 检查 YAML 语法是否无效（缺少冒号、缩进错误）
3. 为包含特殊字符的字符串加引号

## MDX 错误

### MDX_SYNTAX_ERROR

**消息：**“MDX 编译失败”

**原因：**内容中的 MDX 或 JSX 语法无效。

**修复：**
1. 确保所有 JSX 标签都正确闭合（`<Card>...</Card>`）
2. 检查 props 是否使用正确的语法（`title="value"`，而不是 `title=value`）
3. 在普通文本中转义花括号：使用 `\{` 代替 `{`

### COMPONENT_NOT_FOUND

**消息：**“未知组件 'ComponentName'”

**原因：**使用了 Jamdesk 中不存在的组件。

**修复：**
1. 查看[组件参考](/cn/components/overview)，确认组件名称是否正确
2. 组件区分大小写：使用 `<Card>`，而不是 `<card>`
3. 确认没有导入自定义组件（不支持）

### INVALID_PROPS

**消息：**“组件 'ComponentName' 的 props 无效”

**原因：**组件收到其不接受的 props。

**修复：**
1. 查看组件文档，确认有效的 props
2. 移除不受支持的 props
3. 在组件文档中检查 prop 的预期类型（例如，`cols` 需要数字，而不是字符串）

## OpenAPI 错误

### OPENAPI_PARSE_ERROR

**消息：**“无法解析 OpenAPI 规范”

**原因：**您的 OpenAPI 规范文件存在无效语法或结构。

**修复：**
1. 在本地运行 `jamdesk openapi-check` 进行验证
2. 使用 Swagger Editor 等 OpenAPI 验证工具
3. 检查 JSON 或 YAML 语法是否有效

### OPENAPI_REFERENCE_ERROR

**消息：**“OpenAPI 规范中的引用无法解析”

**原因：**OpenAPI 规范中的 `$ref` 指向不存在的定义。

**修复：**
1. 验证所有 `$ref` 路径是否正确
2. 检查被引用的架构是否存在于 `components/schemas`
3. 如果 `$ref` 指向外部文件或 URL，请确认文件已包含在项目中，且 URL 可访问

## 构建超时

### BUILD_TIMEOUT

**消息：**“构建超出最大时间限制”

**原因：**构建耗时超过允许的时间（通常为 5 分钟）。

**修复：**
1. 优化大型图像（压缩或调整尺寸）
2. 将超大页面拆分为较小页面
3. 如果页面数量过多，请减少页面数量
4. 如果问题仍然存在，请联系支持团队

## 资源错误

### ASSET_NOT_FOUND

**消息：**“找不到资源 'path/to/asset'”

**原因：**文档中引用的图像或文件不存在。

**修复：**
1. 验证指定路径下是否存在该文件
2. 检查路径是否相对于文档目录
3. 路径区分大小写，请准确检查文件名

### ASSET_TOO_LARGE

**消息：**“资源超出最大文件大小”

**原因：**图像或文件大于 10MB 限制。

**修复：**
1. 使用 TinyPNG 或 ImageOptim 等工具压缩图像
2. 使用适合的格式（照片使用 WebP，图标使用 SVG）
3. 考虑将超大文件托管在外部

## 获取帮助

如果无法解决错误：

1. 在仪表板中查看完整构建日志，获取更多上下文
2. 在 [FAQ](/cn/help/faq) 中搜索常见问题
3. [联系支持团队](/cn/help/support/contact)，并提供项目 ID 和错误详情

## 相关文章

<Columns cols={2}>
  <Card title="构建失败" icon="triangle-exclamation" href="/cn/help/troubleshooting/build-failures">
    常见构建失败及其解决方案
  </Card>
  <Card title="联系支持团队" icon="headset" href="/cn/help/support/contact">
    获取团队帮助
  </Card>
</Columns>