---
title: 如何校验元数据文件的合法性
description: 说明 AI 修改 SuccApp 元数据文件后，如何使用 SuccApp CLI 把本地内容发送到服务器编译校验，并根据错误信息定位问题。
navTitle: 元数据合法性校验
---
# 如何校验元数据文件的合法性

AI 修改 `.dash`、`.spg`、`.tbl`、`.rpt` 等元数据文件后，如果不想等到浏览器预览时才发现表达式、组件配置或模型结构错误，可以先用 SuccApp CLI 做一次服务器编译校验。校验会把本地文件内容发送到当前服务器编译，不保存文件，也不修改服务器上的元数据内容。

## 适用场景{#scenarios}

遇到以下情况时，先做元数据合法性校验：

1. AI 修改了仪表板、页面、报表、模型、表单或主题等 JSON 元数据文件。
2. 浏览器预览或设计器打开时报错，需要在终端里拿到结构化错误信息。
3. 推送测试服务器前，希望先拦截 JSON 语法、版本升级、表达式和编译阶段的错误。
4. 需要让 AI Agent 读取 `--json` 结果并继续修复文件。

图片、附件、普通脚本和非 JSON 文件不适合使用这个命令校验。它也不能证明业务口径、数据结果、权限和页面交互一定正确。

## 前置条件{#prerequisites}

执行校验前确认：

1. 当前目录在 SuccApp 工作区内。
2. 工作区已经配置活跃服务器，并已完成登录。
3. 要校验的文件在本地工作区中存在。
4. 文件路径属于当前服务器已知的元数据项目范围。

如果还没有准备工作区，先阅读[连接服务器与下载元数据](../workspace/connect-and-clone.md)。

## 执行校验{#run}

在工作区根目录或子目录执行：

```bash
succapp workspace file compile path/to/file.dash
```

也可以一次校验多个文件：

```bash
succapp workspace file compile path/to/page.spg path/to/model.tbl
```

需要给 AI Agent 或脚本读取时，使用 JSON 输出：

```bash
succapp workspace file compile path/to/file.dash --json
```

命令会读取本地文件内容，按文件路径确定服务器上的元数据类型和编译上下文，然后调用服务器编译逻辑。服务器会先按当前版本尝试升级传入内容，再执行对应的编译校验。

::: tip 提示
`workspace file compile` 不会把本地内容保存到服务器。校验通过后，仍然需要执行 `succapp workspace push <path>`，浏览器预览才能看到本地修改后的服务器版本。
:::

## 查看校验结果{#result}

校验通过时，结果会显示通过文件数和失败文件数。校验失败时，CLI 会返回非 0 退出码，并展示失败文件、编译器和错误信息。

JSON 输出中重点看这些字段：

| 字段 | 说明 |
| :--- | :--- |
| `summary.files` | 本次校验的文件数量。 |
| `summary.passed` | 通过校验的文件数量。 |
| `summary.failed` | 未通过校验的文件数量。 |
| `items[].remotePath` | 文件对应的服务器元数据路径。 |
| `items[].type` | 服务器识别到的元数据类型，例如 `dash`、`spg`、`tbl`。 |
| `items[].compiler` | 本次使用的编译器，常见为 `nodejs` 或 `java`。 |
| `items[].success` | 当前文件是否通过编译校验。 |
| `items[].errorInfo` | 服务器返回的结构化错误信息。 |

`success: false` 表示文件内容没有通过校验。此时命令退出码非 0 是预期行为，不要把它当作 CLI 连接失败或程序崩溃。

## 根据错误修复{#fix}

定位问题时按以下顺序看：

1. 先看 `items[].remotePath`，确认是哪一个文件失败。
2. 再看 `items[].errorInfo.message`、`errorCode` 或 `className`，确认错误类型。
3. 如果 `errorInfo.locationPath` 中包含文件路径、组件、字段或表达式位置，优先按该位置检查。
4. 修改本地文件后重新执行 `succapp workspace file compile <path>`。
5. 校验通过后，再执行 `succapp workspace push <path>` 并打开浏览器验证。

常见修复方向：

| 错误现象 | 处理方向 |
| :--- | :--- |
| JSON 解析失败 | 检查逗号、引号、括号、注释和文件编码。 |
| 版本升级失败 | 对照同类文件或先执行 `succapp workspace file upgrade --dry-run <path>`。 |
| 表达式报错 | 检查参数、字段名、函数名、运算符和字符串引号。 |
| 组件或布局配置报错 | 对照同类型页面、仪表板或报表中的组件结构。 |
| 模型结构报错 | 检查 `.tbl` 的模型类型、字段、维键、度量、数据源和物理表配置。 |

## 校验通过后还要做什么{#after}

元数据合法性校验只说明文件能通过服务器编译。继续交付前还需要：

1. 用 [Diff 审查](../quality/diff-review.md) 确认修改范围。
2. 用 [引用检查](../quality/reference-check.md) 确认资源、字段、数据集和脚本引用没有被破坏。
3. 执行 `succapp workspace push <path>` 推送到测试服务器。
4. 按[预览文件](../quality/preview-file.md)在浏览器或设计器中验证运行效果。
5. 关键业务流程继续做[产品验证](../quality/product-verification.md)。