使用指南
高阶教程 / 原生代码编译和批量编译完整指南
详细说明原生代码编译的使用时机、支持面分析、诊断处理、批量编译流程、结果解读和发布前验证顺序。
当工作流进入真实项目阶段，单个文件能跑只是第一步。你还需要确认所有 .sgw 都能编译、关键逻辑性能足够、类型引用没有断、自定义节点和插件节点仍然可用。
这篇讲两个高阶能力：
- 原生代码编译：把支持范围内的工作流转成更直接的 TypeScript 代码，用于性能敏感路径。
- 批量编译：一次检查项目内多个
.sgw，用于发布前和大改后的全局验证。
阅读前提和学习路线
阅读前建议已经理解：
- 工作流文件、Flow 和文件类型。
- 编译、运行和日志排查。
- 组件、函数库、类、接口、枚举、结构体这些文件类型的基本用途。
本页的阅读顺序很重要：
先理解原生代码编译适合什么
-> 再看支持面和诊断
-> 再处理自定义节点影响
-> 最后用批量编译做全局验证不要把原生代码编译当成“一键加速”。它更像一条更严格的编译路径：能帮助性能敏感逻辑，但也会把不支持的节点、断掉的数据依赖和不明确的异步行为更早暴露出来。
原生代码编译解决什么问题
普通工作流更适合搭建、验证和调试。原生代码编译适合在逻辑稳定后提升关键路径性能。
适合开启的场景：
| 场景 | 原因 |
|---|---|
| 每帧移动、计时、状态更新 | 调用频率高 |
| 大量对象循环处理 | 节点执行次数多 |
| 高频 UI 刷新 | 容易造成卡顿 |
| 输入响应和物理控制 | 对延迟更敏感 |
| 发布前性能收敛 | 需要更稳定的执行成本 |
不建议一开始就开启：
| 场景 | 原因 |
|---|---|
| 正在探索玩法 | 先保证逻辑正确 |
| 节点还频繁替换 | 支持面变化会干扰调试 |
| 只是低频按钮或菜单逻辑 | 性能收益不明显 |
| 还没有排查清楚错误 | 原生编译会增加排查维度 |
推荐节奏是：先普通方式跑通，再用打印节点排查正确性，最后再开启原生代码编译优化关键路径。
开关位置和含义
项目设置里有“启用工作流原生代码生成”开关。说明中明确它是实验性开关：开启后，支持范围内的工作流会编译为真实 TypeScript 代码直接执行；不支持的节点会导致编译失败，不会悄悄退回普通执行方式。
这意味着：
- 开启后要认真看编译错误。
- 不支持就是不支持，不能指望系统自动绕过去。
- 最好逐步开启，而不是在发布前一次性给所有工作流开启。
原生编译会先做可行性分析
编译前会分析整张工作流，确认入口、节点、数据依赖、事件绑定、自定义节点等是否在支持范围内。
分析会关注：
| 检查方向 | 说明 |
|---|---|
| 主 Flow 是否存在 | 没有主 Flow 无法生成 |
| 入口是否可识别 | 生命周期、全局事件、方法入口等 |
| 执行节点是否支持 | 不支持的执行节点会产生诊断 |
| 数据节点是否支持 | 上游数据依赖也必须可生成 |
| 事件绑定是否支持 | 事件相关节点需要满足规则 |
| 自定义节点是否可生成 | bridge 和 operation 需要被识别 |
| 异步能力是否明确 | 需要等待的 Flow 会进入 await 模式 |
诊断通常会带上 Flow、节点 ID、节点类型和原因码。处理时先修第一条，因为后续错误可能是第一条引起的连锁反应。
自定义节点和原生编译
自定义节点会影响原生编译。大致规则：
| 节点执行方式 | 原生编译注意点 |
|---|---|
bridge | 可被识别；如果异步，节点要标记 isAsync: true |
operation | 可被识别；适合包装已有操作语义 |
| 未明确执行方式 | 可能无法进入支持范围 |
如果自定义节点里有等待过程，例如加载资源、等待事件、请求外部结果，必须明确标记异步。否则生成代码时会错误理解执行顺序。
发布前处理自定义节点：
- 确认
node.type稳定。 - 确认端口 ID 与返回字段一致。
- 确认异步节点标记正确。
- 在一个小工作流中单独编译。
- 再放入真实工作流。
原生编译失败时怎么排查
按这个顺序处理：
- 先看第一条诊断的节点类型。
- 打开对应
.sgw，定位节点。 - 判断是节点不支持、数据依赖不支持，还是事件绑定不支持。
- 如果是自定义节点，检查
bridge、operation、isAsync和输出端口。 - 如果是资产管理或构造类逻辑，确认该 Flow 是否适合原生编译。
- 临时替换成普通支持节点，再重新编译验证。
常见诊断方向：
| 诊断方向 | 含义 | 处理方式 |
|---|---|---|
| missing-main-flow | 主 Flow 缺失 | 重新打开 .sgw 检查文件类型和主 Flow |
| unsupported-execution-node | 执行节点不支持 | 替换节点或暂不开启原生编译 |
| unsupported-data-node | 上游数据节点不支持 | 改造数据来源 |
| unsupported-node-type | 节点类型不在支持面内 | 替换或等待支持 |
| missing-data-source-node | 数据来源节点缺失 | 修复断线或删除失效引用 |
| unsupported-asset-management-constructor-flow | 构造流程里用了不合适的资产管理节点 | 把资源加载移到更合适的 Flow |
逐步开启策略
不要一次性把所有工作流都改成性能模式。推荐按风险分层：
| 阶段 | 处理范围 | 验证方式 |
|---|---|---|
| 1 | 一个简单组件工作流 | 单文件编译、场景预览 |
| 2 | 一个高频组件工作流 | 加打印、对比行为 |
| 3 | 相关函数库 | 单文件编译、调用方编译 |
| 4 | 一组玩法工作流 | 批量编译 |
| 5 | 发布前全项目 | 批量编译、真实场景跑通 |
每一步都保存一份可回退版本。性能优化不应该和大规模逻辑改造混在一起做。
批量编译解决什么问题
批量编译用来检查多个 .sgw 的编译状态，特别适合改动影响范围不明显的时候。
适合运行批量编译的时机：
- 发布前。
- 修改了枚举、结构体、接口或类之后。
- 修改了函数库之后。
- 修改自定义节点之后。
- 更新或禁用插件节点之后。
- 重命名、移动或删除
.sgw文件之后。 - 大量复制、整理、替换节点之后。
- 开启或关闭原生代码编译相关配置之后。
批量编译不是替代单文件调试，而是验证“全项目引用关系仍然成立”。
批量编译入口
从菜单进入：
扩展 / 脚本图编辑器 / 批量编译它会扫描项目内可编译的 .sgw 资产。当前覆盖这些文件类型：
| 类型 | 是否纳入批量编译 |
|---|---|
| 组件 | 是 |
| 类 | 是 |
| 函数库 | 是 |
| 接口 | 是 |
| 枚举 | 是 |
| 结构体 | 是 |
批量编译会跳过不属于这些类型或无法识别的数据。
批量编译会保存已打开面板
如果某个 .sgw 正在工作流面板里打开，批量编译会先请求该面板保存，再读取文件编译。保存等待有超时限制；如果面板没有及时响应，该文件会失败并给出保存相关错误。
这条规则很重要：
- 批量编译前先处理未完成的编辑。
- 不要让多个未保存的工作流长期打开。
- 如果提示等待保存超时，先手动保存该工作流，再重新批量编译。
批量编译结果怎么读
结果应按依赖层级读，不要只看失败数量。
优先级：
- 枚举、结构体、接口。
- 类。
- 函数库。
- 自定义节点和插件节点相关问题。
- 组件工作流。
原因是上层组件可能依赖底层类型和函数库。先修底层，一个错误可能会让多个组件恢复。
结果字段可以按下面理解：
| 信息 | 用途 |
|---|---|
| 文件名 | 找到失败的 .sgw |
| 资源 URL | 确认项目内位置 |
| 文件路径 | 必要时定位磁盘文件 |
| 成功/失败 | 判断是否生成输出 |
| 错误摘要 | 第一时间看懂问题 |
| 错误详情 | 需要深挖时再看 |
| 输出路径 | 成功时确认生成文件位置 |
推荐验证顺序
发布前或大改后，按这个顺序走：
- 保存所有打开的
.sgw。 - 单独编译刚改过的文件。
- 编译枚举、结构体、接口。
- 编译类和函数库。
- 编译引用自定义节点或插件节点的关键组件。
- 运行批量编译。
- 打开真实场景预览。
- 清理临时打印。
不要把“批量编译通过”当成“玩法完全正确”。它证明文件能生成，不证明每条业务路径都已在场景里跑过。
大改后的分批策略
如果项目有很多 .sgw，一次看到大量失败会很难处理。可以分批：
| 批次 | 目标 |
|---|---|
| 类型文件 | 枚举、结构体、接口 |
| 领域模型 | 类 |
| 复用逻辑 | 函数库 |
| 基础组件 | UI、角色、关卡根节点 |
| 高频组件 | 更新、输入、物理、循环 |
| 插件引用 | 使用插件节点的工作流 |
每批通过后再处理下一批。这样能避免同一个底层错误在几十个组件里重复出现。
常见失败原因和处理
| 失败原因 | 典型表现 | 处理方式 |
|---|---|---|
| 类型引用失效 | 枚举、结构体或类找不到 | 重新选择目标类型 |
| 节点不支持原生编译 | 原生编译诊断指向某个节点 | 替换节点或暂不开启原生编译 |
| 自定义节点变化 | 端口 ID、输出字段或 node.type 不一致 | 恢复旧契约或迁移工作流 |
| 插件节点不可用 | 节点类型无法解析 | 打开关联插件面板检查 |
| 资产路径失效 | 加载节点失败或默认值丢失 | 用选择器重新指定 |
| 已打开面板未保存 | 保存超时或文件内容不是最新 | 手动保存后重跑 |
| 文件类型不适合 | 批量编译跳过或报不可编译 | 检查 .sgw 主类型 |
原生编译和批量编译如何配合
推荐流程：
- 先普通方式跑通工作流。
- 单独开启关键工作流的原生编译路径。
- 修复所有原生编译诊断。
- 在场景里对比行为。
- 再用批量编译确认引用范围。
- 最后做发布前预览。
如果批量编译中有大量原生编译相关错误，先缩小范围，挑一个最简单的失败工作流处理。不要同时修改所有失败工作流。
性能优化时不要丢掉可读性
原生代码编译不是让你把所有逻辑塞进一张大图。可维护性仍然重要：
- 高频逻辑可以优化，但文件职责仍要清楚。
- 循环里少做资源加载。
- 更新事件里少做节点查找。
- 重复计算可以放进函数库。
- 大量对象数据可以用结构体组织。
- 关键输入输出保留清晰命名。
性能问题通常不是一个开关解决，而是“职责拆分、节点选择、资源时机、编译路径”一起处理。
发布前完整检查清单
- 所有关键
.sgw已保存。 - 单文件编译通过。
- 枚举、结构体、接口先通过。
- 类和函数库通过。
- 自定义节点和插件节点状态正常。
- 原生代码编译诊断已处理。
- 批量编译通过。
- 真实场景预览跑通关键路径。
- 临时打印已经清理。
- 资产包、场景和资源进入构建配置。
- 禁用的插件服务没有被工作流引用。
失败时的最短处理路径
如果你只想快速定位问题，按这个顺序：
- 看失败文件名。
- 看第一条错误摘要。
- 打开对应
.sgw。 - 在入口后加打印，确认是否能普通运行。
- 如果普通运行也不对，先修逻辑。
- 如果普通运行正确，再处理原生编译支持面。
- 单文件通过后，再跑批量编译。
继续阅读：
- 自定义节点相关问题：自定义节点完整指南。
- 插件节点相关问题：插件节点和关联插件完整指南。
- 普通运行问题：编译、运行和日志排查。