构建错误参考

使用 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. 查看组件参考，确认组件名称是否正确
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 中搜索常见问题
3. 联系支持团队，并提供项目 ID 和错误详情

相关文章