Skip to main content
本地应用开发围绕着同步展开：CLI 会重建你的 manifest，而服务器只会应用它与工作区中已存在元数据之间的差异。 本页介绍在不同情况下应使用哪个命令、如何阅读同步修改内容，以及当本地状态看起来不一致时——按顺序——应该怎么做。

​
在什么情况下用哪个命令

在日常本地迭代中，你几乎总是需要 yarn twenty dev。 Deploy 和 publish 用于发布版本，而不是用于本地循环。
yarn twenty dev --once 和 yarn twenty dev --once --dry-run 仍然可以作为已弃用的别名使用，对应 yarn twenty apply 和 yarn twenty plan。

​
本地同步不需要提升版本号

严格递增的 version 规则（在 deploy 时为 VERSION_ALREADY_EXISTS，在 install 时为 APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION）适用于 app:publish / app:install——即发布路径。 yarn twenty dev 就地同步你的 manifest，且从不要求修改版本，因此你无需为了迭代去改动 package.json。 如果你发现自己为了测试本地改动而不断提升版本号，说明你在想要使用开发循环时却走了发布路径。

​
阅读同步输出

每次同步都会打印它实际应用的（或在使用 plan 时将要应用的）元数据更改，Terraform 风格——每个实体一个区块，包含其属性，然后是一行总结：
这是你的首要诊断工具：它会准确告诉你哪些对象、字段和布局发生了变化，这样你就可以在查看 UI 之前确认同步是否按预期进行。 破坏性更改（to destroy）会列出它们会删除的内容（例如 objectMetadata "auditNote" — drops the table and all its rows），并且需要交互式确认，或者在脚本中使用 --force。 当同步在某个实体上失败时，错误信息会给出有问题的实体及其 universalIdentifier，例如：
使用该标识符在 manifest 中（以及在需要时在工作区中）定位该实体，而不是猜测哪个实体发生了冲突。

​
预览更改（计划）

yarn twenty plan 会构建你的 manifest，向服务器请求迁移计划并打印出来——不会实际应用任何内容。 这是在真正执行前，以安全方式回答“这次同步会改动什么？”的办法。
一个计划：
  • 不会写入任何内容——不会进行元数据迁移、不会更新应用记录、不会更改默认角色/标签，也不会生成 API 客户端。
  • 返回与真实同步将要应用的相同 diff，这样你可以预先审查将被创建 / 更新 / 删除的实体。
  • 在执行高风险改动之前、在审查 AI 生成的改动时，或在某些如果即将落地意外变更就应当失败的脚本中，dry run 都非常有用。
计划只会预览元数据更改，并且要求应用至少已经同步过一次（这样工作区才知道它的存在）。 如果你在一个从未同步过的应用上运行它，服务器会报告该应用尚未安装——先运行一次 yarn twenty dev。

​
恢复梯子

当本地元数据看起来不对时，按以下顺序逐步升级，并在问题解决后立即停止。 每一步都比前一步更具破坏性。
  1. 重新同步。 再次运行 yarn twenty apply。 同步是幂等的——在干净的 manifest 上重新运行是安全的，并且通常可以解决瞬时故障。
  2. 预览计划。 运行 yarn twenty plan，在不应用变更的前提下，准确查看下一次同步打算修改什么。
  3. 阅读具名错误。 如果同步失败，记录消息中的元数据类型和 universalIdentifier（见上），并在 manifest 中定位该实体。 冲突通常指向重复或被重复使用的标识符。
  4. 卸载并重新安装。 先执行 yarn twenty app:uninstall，然后再次同步（yarn twenty dev）。 这会在保留你工作区其余部分不变的情况下，从零重建该应用的元数据。
  5. 完全重置（最后手段）。 执行 yarn twenty docker:reset，然后重新播种并重新同步。
yarn twenty docker:reset 会删除本地实例中的所有数据——包括每个工作区、记录和应用。 只有在前面步骤全部无效时才使用它。
遇到元数据错误了吗？ 请提交 issue，并附上失败的迁移消息（包含其中的元数据类型和 universalIdentifier）、同步时的 Metadata changes 输出，以及你执行过的命令。

​
避免在同一工作区上并发同步

同步会应用元数据迁移。 在同一个工作区同时运行多个同步、部署或安装操作——例如多个终端或多个 AI 代理并行迭代——会让这些迁移交错执行，从而让元数据处于部分应用的状态。 服务器会按工作区串行化同步以防止这种情况，但你仍然应当通过单一进程来处理敏感的元数据操作，而不要并发触发。 如果你使用多个代理来编排开发，请将它们的同步 / 部署 / 安装调用通过一个队列进行排队，这样任何时刻只有一个操作在运行。

​
区分不同类型的失败

当出现问题时，元数据 diff 和具名错误可以帮助你定位失败位置：
  • Manifest 构建错误——CLI 在同步前失败（MANIFEST_BUILD_FAILED、TYPECHECK_FAILED）；请修复你的应用源代码。
  • 同步 / 迁移错误——构建成功，但在应用 diff 时失败，并给出实体名称和 universalIdentifier；请修复冲突的元数据。
  • 应用代码运行时错误 — 同步成功，但你的逻辑函数或组件在运行时行为异常；请检查函数日志。
  • 本地实例状态 — 不属于以上任何一种情况，但工作区仍然显示异常；请按照恢复步骤逐级排查。