构建错误参考

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

配置错误

INVALID_DOCS_JSON

消息： "Invalid docs.json configuration"

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

修复：

1. 在本地运行 jamdesk validate 查看详细错误
2. 检查是否缺少逗号、括号或引号
3. 确认所有值都符合预期架构

MISSING_PAGE

消息： "Page 'path/to/page' referenced in navigation but file not found"

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

修复：

1. 检查文件是否存在于指定路径
2. 确认 docs.json 中的路径与实际文件名一致（不含 .mdx）
3. 检查大小写。路径区分大小写

INVALID_FRONTMATTER

消息： "Invalid frontmatter in 'path/to/page'"

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

修复：

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

MDX 错误

MDX_SYNTAX_ERROR

消息： "MDX compilation failed"

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

修复：

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

COMPONENT_NOT_FOUND

消息： "Unknown component 'ComponentName'"

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

修复：

1. 查看组件参考以确认正确的名称
2. 组件名称区分大小写：使用 <Card> 而非 <card>
3. 确认你没有导入自定义组件（不受支持）

INVALID_PROPS

消息： "Invalid props for component 'ComponentName'"

原因： 组件接收了它不接受的属性。

修复：

1. 查看组件文档以确认有效属性
2. 删除任何不受支持的属性
3. 在组件文档中检查属性的预期类型（例如，cols 期望数字而非字符串）

OpenAPI 错误

OPENAPI_PARSE_ERROR

消息： "Failed to parse OpenAPI specification"

原因： 你的 OpenAPI 规范文件语法或结构无效。

修复：

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

OPENAPI_REFERENCE_ERROR

消息： "Unresolved reference in OpenAPI spec"

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

修复：

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

构建超时

BUILD_TIMEOUT

消息： "Build exceeded maximum time limit"

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

修复：

1. 优化大图片（压缩或调整尺寸）
2. 将非常大的页面拆分为较小的页面
3. 如果页面数量极多，请减少页面数量
4. 如果问题仍然存在，请联系支持团队

资源错误

ASSET_NOT_FOUND

消息： "Asset 'path/to/asset' not found"

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

修复：

1. 验证文件是否存在于指定路径
2. 检查路径是否相对于你的文档目录
3. 文件名大小写必须完全匹配。路径区分大小写

ASSET_TOO_LARGE

消息： "Asset exceeds maximum file size"

原因： 图片或文件超过了 10MB 的限制。

修复：

1. 使用 TinyPNG 或 ImageOptim 等工具压缩图片
2. 使用合适的格式（照片用 WebP，图标用 SVG）
3. 将非常大的文件托管在外部

获取帮助

如果你无法解决错误：

1. 在仪表板中查看完整的构建日志以获取更多信息
2. 在常见问题中搜索常见问题
3. 携带你的项目 ID 和错误详情联系支持团队

相关文章