---
title: 修改、对比、拉取与推送
navTitle: 修改与同步
---
# 修改、对比、拉取与推送

本地修改和服务器同步是 SuccApp 的核心能力。AI 修改元数据后，项目成员应通过 SuccApp CLI 或 SuccApp for VS Code 查看差异，再选择拉取服务器变化或推送本地变化。

不要把 AI 修改完成视为交付完成。真正的交付闭环包括：检查本地变化、对比服务器基线、推送测试环境、产品界面验证、提交 Git 和必要的团队评审。

## 同步模型{#model}

SuccApp 使用三类内容判断同步状态：

| 内容 | 位置 | 说明 |
| :--- | :--- | :--- |
| 工作区文件 | 项目目录 | 用户实际编辑的本地元数据文件 |
| 本地 mirror | `.succapp/remote/` | 上次同步时记录的服务器基线 |
| 服务器当前内容 | SuccApp 服务器 | 服务器上正在生效的元数据 |

本地文件和 mirror 不一致时，会产生本地变化。本地 mirror 和服务器当前内容不一致时，会产生远端变化。如果本地和服务器都改了同一个资源，就可能产生冲突。

## 开始修改前{#before-edit}

开始修改前建议先完成以下检查：

1. 确认当前连接的是测试服务器。
2. 从 Git 拉取团队最新内容。
3. 在 SuccApp 中拉取服务器变化。
4. 确认 Changes 视图没有未处理的冲突。
5. 确认本次任务涉及的文件范围。

这样可以减少多人协作时互相覆盖的风险。

## 本地修改元数据{#edit-local}

克隆项目后，可以直接在 VS Code 中编辑项目目录下的元数据文件。

常见修改包括：

1. 修改页面、报表、仪表板等 JSON 元数据。
2. 修改前端脚本或后端脚本。
3. 新增或调整资源文件。
4. 使用 AI 辅助批量修改元数据字段。
5. 使用 CLI 或脚本生成小范围可审查的修改。

修改时应注意：

1. 不要随意删除目录级 `.meta` 文件或其中的资源条目。
2. 不要直接编辑 `.succapp/remote/` 下的文件。
3. 大范围格式化前，应确认团队是否接受格式化造成的差异。
4. 删除文件前，应确认服务器上也需要删除该资源。

## 刷新变化{#refresh-status}

修改后打开 SuccApp **变化** 视图，点击刷新按钮，或执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**）。

刷新后，Changes 视图会显示本地变化和远端变化；发生冲突时，相关资源会带有冲突标记。视图 badge 会显示当前需要处理的变化数量。

如果修改了 `.gitignore` 或同步忽略规则，建议刷新变化，让 SuccApp 重新计算变化列表。

## 处理服务器变化{#refresh-baseline}

SuccApp 会通过本地 mirror 和服务器当前内容判断远端变化。需要查看服务器是否有变化时，先执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**），再在 Changes 视图中检查远端变化和冲突。

如果确认要接受服务器上的最新内容，执行 **SuccApp: 拉取变化**（英文界面为 **SuccApp: Pull Changes**）。拉取会更新本地 mirror，并把可安全应用的服务器变化写入工作区；遇到同一路径本地也修改的情况，会返回冲突，等待用户确认。

如果远端变化分组中出现带 `?` 标记的项目，表示当前连接服务器或当前登录用户的项目列表没有返回该本地已跟踪项目。SuccApp 无法直接判断这是连错服务器、登录错用户、权限不足，还是服务器项目确实已删除；同名但项目身份不一致（例如连到了另一台服务器，或项目被删除后重建）也会归到这一类。这类项目不会被普通拉取或自动拉取直接删除本地内容；处理前应先核对服务器地址、登录用户、项目权限和项目名称。

如果服务器把整个项目重命名（项目身份不变、只是改名），远端变化中会显示为项目级的重命名。当前版本只展示该变化，不会在拉取或推送时自动把本地项目目录改名；直接对项目重命名执行拉取或推送会返回提示，请改用重新 clone 该项目或在本地改名以保持一致。

::: warning 注意
当前版本不提供单独只刷新 mirror、但不修改工作区文件的用户命令。拉取前如果本地已有重要修改，应先检查 Changes 视图中的本地变化，必要时先提交 Git。
:::

## 理解变化类型{#change-types}

常见变化类型如下：

| 类型 | 含义 | 常见处理 |
| :--- | :--- | :--- |
| 新增 | 本地或服务器新增文件 | 确认是否需要同步 |
| 修改 | 文件内容或目录级 `.meta` 信息变化 | 打开 diff 检查 |
| 删除 | 本地或服务器删除文件 | 确认是否真的删除 |
| 移动/重命名 | 文件路径发生变化 | 检查旧路径和新路径 |
| 冲突 | 本地和服务器都修改了同一资源 | 阅读[冲突处理](../troubleshoot/conflict-handling.md) |

对于 `.meta` 变化，需要结合资源操作理解。如果只是修改文件内容，通常不应出现大量无关 `.meta` 变化。

## 查看差异{#diff}

可以通过以下入口查看差异：

1. 在 Changes 视图中点击变化文件。
2. 在变化文件上选择 **与服务器版本对比**。
3. 在本地文件菜单中选择 **与服务器版本对比**。
4. 使用快捷键 `Ctrl+Alt+D`，macOS 使用 `Command+Alt+D`。

差异对比可能展示以下内容：

1. 本地文件和同步基线的差异。
2. 服务器当前内容和同步基线的差异。
3. 删除文件和空内容的差异。
4. 目录级 `.meta` 变化中的资源元信息差异。

检查差异时，应重点确认修改范围是否与任务一致，是否存在误删、误改、格式化噪声和无关文件。

## 拉取服务器变化{#pull}

拉取会把服务器上的远端变化应用到本地工作区。

常用入口：

1. 执行 **SuccApp: 拉取变化**（英文界面为 **SuccApp: Pull Changes**）。
2. 点击 Changes 视图顶部的拉取按钮。
3. 在某个远端变化上选择 **拉取文件**。

拉取适合以下场景：

1. 开始工作前同步其他人的服务器修改。
2. push 被远端变化阻止后，先把服务器变化拉到本地。
3. 需要接受服务器上的最新内容。

::: warning 注意
拉取可能修改本地文件。拉取前如果有未提交的重要修改，应先确认 Changes 视图中的本地变化，必要时先提交 Git。

如果拉取到旧版本元数据文件，SuccApp 会提示编辑前建议先升级。拉取本身不会自动升级本地内容。
:::

## 推送本地变化{#push}

推送会把本地工作区变化提交到当前活跃服务器。

常用入口：

1. 执行 **SuccApp: 推送变化**（英文界面为 **SuccApp: Push Changes**）。
2. 点击 Changes 视图顶部的推送按钮。
3. 在某个本地变化上选择 **推送文件**。
4. 打开文件后执行 **SuccApp: 推送当前文件**（英文界面为 **SuccApp: Push Current File**）。
5. 使用快捷键 `Ctrl+Shift+Up`，macOS 使用 `Command+Shift+Up`。

通过 **SuccApp: 推送变化**（英文界面为 **SuccApp: Push Changes**）执行工作区推送时，SuccApp 会展示准备推送的文件列表。确认无误后再继续。

Changes 视图中的单文件推送、顶部批量推送，以及 **SuccApp: 推送当前文件**（英文界面为 **SuccApp: Push Current File**）更偏向快速操作，可能不会再次展示完整文件列表。使用这些入口前，应先在 Changes 视图和 diff 中确认变化范围。

如果本地修改的元数据内容版本和当前服务器版本不一致，推送不会自动升级，也不会因为内容版本差异阻止提交。推送成功后，SuccApp 会提示旧版本文件建议升级；如果本地内容版本高于当前服务器版本，会提示确认兼容性。可以手动执行 **SuccApp: 升级文件**（英文界面为 **SuccApp: Upgrade File**），不传目标时升级当前编辑器文件；在资源管理器中对文件或文件夹执行时，会升级对应文件或文件夹下可支持的元数据文件。手动升级只会改写本地 workspace 中的文件，不会修改远端服务器数据；只有后续执行推送时，升级后的本地文件才会提交到服务器。

使用 CLI 时，可以执行 `succapp workspace file upgrade --dry-run` 先查看所有本地已同步项目中的升级候选文件；指定 `sysdata`、项目名、目录或文件路径时，只预演对应范围。去掉 `--dry-run` 后会升级本地文件，但仍不会直接修改远端服务器数据。

推送成功后，服务器会立即使用新的元数据。测试环境推送后应及时在浏览器中预览效果。

## 推送被阻止怎么办{#push-blocked}

如果服务器上存在未拉取的远端变化，push 可能被阻止。此时通常会看到以下选择：

1. 查看差异。
2. 拉取服务器变化。
3. 强制推送。

推荐处理顺序：

1. 先查看差异，确认服务器上是谁改了什么。
2. 如果服务器变化需要保留，先拉取并解决冲突。
3. 如果确认服务器变化可以被覆盖，再由负责人决定是否强制推送。

::: danger 生产环境禁止随意强制推送
生产环境中出现 push 被阻止时，应先暂停发布，确认远端变化来源和业务影响。不要为了完成操作直接强制覆盖。
:::

如果本地和服务器都修改了同一个资源，可能需要处理冲突。详细步骤请阅读[冲突处理](../troubleshoot/conflict-handling.md)。

## 放弃修改{#discard}

如果本地修改不需要保留，可以在 Changes 视图中选择 **放弃修改**。

放弃修改会用本地同步基线恢复本地文件，必要时会删除本地新增文件。它不会实时从服务器重新下载最新内容。执行前请确认这些修改不再需要。

使用 SuccApp CLI 时，可以放弃指定路径的本地修改：

```bash
succapp workspace discard <path>
```

如果不指定路径，表示放弃整个工作区中的本地修改，需要显式确认：

```bash
succapp workspace discard --force
```

如果希望先以服务器当前内容为准，应先拉取服务器变化，或对整个项目执行 **从服务器重置本地项目**。

对于已经提交到 Git 的修改，也可以通过 Git 回退，但需要注意 Git 回退和 SuccApp 同步状态是两套机制。回退后仍应刷新 SuccApp 同步状态。

## 自动推送和自动拉取{#auto-sync}

SuccApp 支持自动推送和自动拉取。

自动推送适合测试环境中快速调试脚本或元数据。开启后，保存文件会在延迟后自动推送到服务器。

自动推送可以通过 **SuccApp: 开启自动推送**（英文界面为 **SuccApp: Enable Auto Push**）和 **SuccApp: 关闭自动推送**（英文界面为 **SuccApp: Disable Auto Push**）控制，也可以通过 `succapp.sync.autoPush` 设置项配置。

自动拉取通过 `succapp.sync.autoPull` 和 `succapp.sync.autoPullInterval` 设置项控制。自动拉取会按配置间隔拉取服务器变化，可能修改本地文件，适合少数需要持续跟随服务器变化的协作场景。

::: warning 注意
不建议在生产环境中开启自动推送或自动拉取。多人协作场景中也应谨慎开启自动拉取，避免本地修改被未预期的服务器变化打断。生产环境应通过手工检查差异和发布确认后再同步。
:::

## 配置同步忽略规则{#ignore}

可以通过 `succapp.sync.ignore` 设置同步忽略规则，也可以执行 **SuccApp: 配置同步忽略规则**（英文界面为 **SuccApp: Configure Sync Ignore Rules**）打开配置。

适合忽略的内容包括：

1. 临时文件。
2. 日志文件。
3. 本地生成文件。
4. 与当前项目交付无关的辅助文件。

不要用忽略规则隐藏真实业务元数据变化。否则团队可能以为没有变化，实际服务器和本地已经不一致。

## 查看日志{#log}

执行 **SuccApp: 查看日志**（英文界面为 **SuccApp: Show Logs**）可以打开 SuccApp 日志面板。

当 push、pull、clone 或状态刷新失败时，日志通常能帮助判断原因，例如认证状态过期、网络失败、权限不足、文件过大或服务器返回错误。

需要查看更多诊断信息时，在 Output 面板的 SuccApp 日志通道右侧点击日志级别按钮，将级别临时调整为 **Debug**。

## 推荐流程{#recommended-flow}

日常修改建议按以下流程执行：

1. 从 Git 拉取最新代码。
2. 连接测试服务器。
3. 拉取服务器变化。
4. 修改本地元数据。
5. 刷新同步状态。
6. 查看差异。
7. 推送到测试服务器。
8. 预览效果。
9. 提交 Git。
10. 发起评审或通知团队。