第一版功能已接近就绪先从项目介绍了解适用场景和节点体系。
Script Graph

使用指南

高阶教程 / 插件节点和关联插件完整指南

系统讲解插件节点的适用场景、关联插件声明、provider/service/entry 状态、面板管理、使用点检查、禁用风险、迁移和排查。

16

插件节点是把自定义节点能力从“当前项目”提升到“跨项目复用”的方式。它适合团队公共能力、平台能力、SDK 接入、统一资源流程、通用 UI 流程等稳定能力。

这篇不只说明“在哪里打开面板”，而是讲清楚插件节点从声明、启用、扫描、使用、诊断到禁用的完整链路。

阅读前提和学习路线

阅读前建议先理解：

本页按插件节点的生命周期组织：

确认是否需要跨项目复用
  -> 声明关联插件
  -> 扫描 provider、service 和 entry
  -> 在节点栏使用
  -> 查看使用点
  -> 处理版本兼容和诊断
  -> 发布前批量编译

插件节点比项目内自定义节点影响范围更大，所以本页会反复强调“启用前验收、禁用前查引用、发布前批量编译”。这是为了保护已经落到真实 .sgw 里的节点引用。

自定义节点和插件节点的边界

对比项自定义节点插件节点
存放位置当前项目 assets/ScriptGraph/CustomNode由 Cocos 扩展提供
适合范围当前项目专属逻辑多项目、多团队复用
管理方式随项目资源一起管理通过“关联插件”面板管理
更新方式当前项目改文件更新提供节点的扩展
典型用途当前游戏角色、关卡、UI 逻辑支付、广告、账号、公共 UI、资源框架

推荐演进路径：

  1. 先在当前项目写自定义节点。
  2. 在真实工作流中验证输入输出。
  3. 当多个项目都需要时，再整理成插件节点。
  4. 通过关联插件面板启用。
  5. 用批量编译检查引用关系。

这样可以避免把还在变化的业务规则过早做成跨项目依赖。

适合做成插件节点的能力

类型示例
平台能力登录、支付、广告、排行榜
团队公共流程打开统一弹窗、播放统一音效、上报事件
资源框架统一加载资源、缓存 Prefab、加载配置
玩法工具生成伤害数字、播放受击反馈、创建掉落物
接口适配对接远程配置、埋点、存档、账号系统

如果能力只适合一个项目，留在自定义节点里更简单。如果能力涉及多个项目一致性，插件节点更合适。

关联插件面板

从菜单进入：

扩展 / 脚本图编辑器 / 关联插件

面板会做几件事：

  • 扫描当前项目扩展中声明的 Script Graph 能力。
  • 展示插件提供方、服务和节点。
  • 展示诊断信息。
  • 查看工作流是否正在引用插件节点。
  • 启用或停用某个插件。
  • 启用或停用某个插件服务。

面板中常见层级：

层级含义
provider提供插件节点的 Cocos 扩展
serviceprovider 里的某类服务，当前节点服务类型是 workflowNodes
entry单个节点入口，指向一个节点定义文件
manifest扫描 entry 后得到的节点清单
diagnostic诊断信息，例如协议不支持、路径不可用、节点文件有问题

如果面板显示“暂无关联插件”，通常表示当前项目扩展没有声明 contributions.scriptGraph。

关联插件声明结构

插件节点由提供方扩展在 package.json 中声明。核心结构是 contributions.scriptGraph。

概念性示例：

{
  "name": "my-workflow-nodes",
  "title": "My Workflow Nodes",
  "contributions": {
    "asset-db": {
      "mount": {
        "path": "assets",
        "readonly": true
      }
    },
    "scriptGraph": {
      "version": 1,
      "services": [
        {
          "id": "ui-nodes",
          "kind": "workflowNodes",
          "displayName": {
            "zh": "UI 节点",
            "en": "UI Nodes"
          },
          "entries": [
            {
              "id": "play-ui-sound",
              "path": "nodes/PlayUiSound.ts",
              "runtime": "assets/workflow-nodes/PlayUiSound.ts"
            }
          ]
        }
      ]
    }
  }
}

字段含义：

字段说明
version关联插件协议版本，当前为 1
services该插件提供的 Script Graph 服务列表
kind当前支持的节点服务类型为 workflowNodes
entries节点入口列表
entry.id入口稳定 ID
entry.path节点定义文件路径
entry.runtime运行时导入路径；不填时通常复用 path
asset-db.mount当 runtime 用相对路径时，需要让资源系统可访问该路径

如果 runtime 直接使用 db:// 路径，可以被直接解析。如果使用相对路径，需要确保它位于 asset-db.mount.path 内。

provider、service 和 entry 状态

面板里的状态可以按下面理解：

状态含义
provider 启用这个扩展整体允许提供节点
service 启用这个服务允许提供节点
service 支持kind 是 Script Graph 当前支持的类型
service 活跃provider 启用、service 启用且类型受支持
entry 可用节点定义文件存在且可扫描
manifest 可用节点定义被解析成可加入节点栏的清单

某个层级不活跃，下游节点就不会进入可用状态。

节点如何进入节点栏

插件节点大致经过这条链路：

扩展 package.json
  -> contributions.scriptGraph
  -> workflowNodes service
  -> entries
  -> 扫描节点定义
  -> 生成节点清单
  -> 左侧节点栏“插件节点”

当你看不到插件节点时，不要只看最后一步。要按链路往前查：

  1. 插件是否安装在当前项目扩展目录。
  2. package.json 是否有 contributions.scriptGraph。
  3. version 是否为当前支持版本。
  4. services 是否为数组。
  5. kind 是否是 workflowNodes。
  6. entry 的 path 是否存在。
  7. runtime 是否可被资源系统导入。
  8. 关联插件面板中是否有 error 级诊断。

禁用前必须看使用点

插件节点一旦被拖进 .sgw，工作流就依赖提供它的插件。禁用 provider 或 service 之前，先打开关联插件面板查看使用点。

禁用前问三个问题：

问题处理方式
哪些 .sgw 正在使用它？在面板中查看引用列表
是否有替代节点？先迁移工作流，再禁用
是否只是临时排查？排查后立即恢复启用

如果存在使用点，直接禁用可能导致编译失败或运行失败。更稳的顺序是：

  1. 记录引用该插件节点的 .sgw。
  2. 打开每个工作流。
  3. 用新节点或项目内自定义节点替换。
  4. 保存并单文件编译。
  5. 跑批量编译。
  6. 再禁用 provider 或 service。

版本和兼容

插件节点需要更严格的兼容意识，因为它会影响多个项目。

改动风险建议
改标题、说明、颜色低可以直接更新
新增可选输入中必须提供默认值
新增输出低一般不破坏旧图
改端口 ID高新建节点类型或提供迁移说明
删除端口高先发布替代节点，旧节点保留一段时间
改 node.type极高视为全新节点
改执行语义高需要明确版本和验证范围

稳定插件节点最好使用语义明确的类型名，例如：

CustomPluginPlayUiSound
CustomPluginLoadRemoteConfig
CustomPluginOpenCommonDialog

如果必须大改，优先新增 V2 节点，而不是原地破坏旧节点。

从自定义节点迁移为插件节点

推荐步骤：

  1. 确认自定义节点在当前项目里已经稳定。
  2. 收敛端口，删除临时输入输出。
  3. 补齐标题、说明、Tooltip、默认值和错误处理。
  4. 移动到提供节点的扩展目录。
  5. 在扩展 package.json 声明 contributions.scriptGraph。
  6. 打开关联插件面板确认 provider、service 和 entry 都可用。
  7. 在测试项目中拖入插件节点。
  8. 单文件编译。
  9. 批量编译。
  10. 再迁移真实项目中的工作流引用。

迁移后，旧项目内自定义节点可以先保留一段时间，等所有工作流完成替换再清理。

诊断信息怎么读

关联插件诊断通常有三个级别：

级别处理方式
error会阻断节点可用，必须处理
warning不一定阻断，但说明能力不完整
info提示信息，通常用于确认状态

常见诊断：

诊断方向常见原因处理
协议版本不支持version 不是当前支持版本改为支持的版本
services 无效services 不是数组修正 package.json
service 类型不支持kind 不是 workflowNodes改成当前支持类型
节点文件不存在entry path 指向错误修正路径
runtime 不可导入相对路径缺少 asset-db.mount 或不在 mount 内声明 mount 或改用 db://
节点定义无效节点文件没有正确导出定义按自定义节点规则修复

使用插件节点的项目侧流程

拿到一个插件节点后，不要直接铺到大量工作流里。先按这个流程验收：

  1. 打开关联插件面板，确认没有 error。
  2. 新建一个测试 .sgw。
  3. 从“插件节点”分类拖入目标节点。
  4. 用最小输入跑通。
  5. 打印关键输出。
  6. 编译测试 .sgw。
  7. 在真实工作流里替换一处。
  8. 再跑批量编译。

这样可以把“插件没有正确接入”和“真实业务图本身有问题”分开。

排查速查表

现象优先检查
面板显示暂无关联插件当前项目扩展是否声明 contributions.scriptGraph
能看到 provider，但没有节点service 是否启用，entry 是否有诊断
节点栏没有插件节点provider 和 service 是否活跃
编译失败节点类型是否仍存在，端口 ID 是否变更
禁用后工作流失败是否仍有 .sgw 引用插件节点
只在某个项目失败插件版本、Script Graph 版本、Cocos Creator 版本是否一致
runtime 路径报错是否使用了相对路径但没有正确 mount

插件节点发布前检查清单

  • provider 的 package.json 能被当前项目扫描到。
  • contributions.scriptGraph.version 是当前支持版本。
  • services 是数组。
  • 每个服务都有稳定 id。
  • 节点服务的 kind 是 workflowNodes。
  • 每个 entry 都有稳定 id 和存在的 path。
  • runtime 路径可导入。
  • 节点定义符合 自定义节点完整指南 的约束。
  • 关联插件面板没有 error 级诊断。
  • 测试 .sgw 能拖入节点、运行、编译。
  • 真实项目跑过批量编译。

和批量编译配合

插件节点变更后，必须用批量编译检查引用。原因很简单：插件节点影响的不是一个文件，而是所有引用它的 .sgw。

推荐顺序：

  1. 更新插件。
  2. 打开关联插件面板确认状态。
  3. 检查使用点。
  4. 单独打开一个关键 .sgw 编译。
  5. 运行批量编译。
  6. 再做场景预览。

继续阅读：原生代码编译和批量编译。