vvvv gamma 故障排除

C# / ProcessNode 问题

类名中的 "Node" 后缀

现象：节点可以正常工作，但在 vvvv 中显示名称不美观。

修复：移除 "Node" 后缀 —— vvvv 的命名规范禁止使用该后缀。

// 错误示例
[ProcessNode]
public class SteeringBehaviorNode { }

// 正确示例
[ProcessNode]
public class SteeringBehavior { }

输出参数位于输入参数之后

现象：引脚顺序错误或节点无法正确编译。

修复：out 参数必须在 Update 签名中排在最前面。

// 错误示例
public void Update(float input = 0f, out float result) { ... }

// 正确示例
public void Update(out float result, float input = 0f) { ... }

节点未出现在节点浏览器中

现象：C# 类已存在，但在 vvvv 中无法显示。

修复：按以下顺序检查：

1. 项目中是否存在 [assembly: ImportAsIs] 特性
2. 类上是否添加了 [ProcessNode] 特性
3. 项目目标框架是否为 net8.0
4. DLL 是否位于相对于 .vl 文档的 lib/net8.0/ 路径下
5. 项目是否无编译错误

内存分配导致帧率下降

现象：垃圾回收（GC）峰值明显，出现卡顿和帧率下降。

诊断：Update 循环中存在内存分配。

常见原因：

• 在 Update 方法中使用 new 关键字
• LINQ 操作符（如 .Where()、.Select()、.ToList()）
• 字符串拼接（使用 + 运算符）
• 值类型装箱（将 int 传递给 object 类型）

修复：缓存所有数据，预先分配缓冲区，避免在性能敏感路径中使用 LINQ。

缺失变更检测

现象：即使没有变化，CPU 使用率也持续偏高。

修复：比较输入值与缓存值，仅在发生变化时重新计算。

if (param != _lastParam)
{
    _cached = Compute(param);
    _lastParam = param;
}
result = _cached; // 始终输出缓存结果

下游节点接收到 null/默认值

现象：连接的节点未收到任何数据，尽管该节点“正常工作”。

修复：始终输出缓存结果，即使未执行计算。

// 错误示例 —— 仅在 if 块内设置 output
public void Update(out float result, float input = 0f)
{
    if (input != _last)
    {
        result = Compute(input);
        _last = input;
    }
    // 当 input 未改变时，result 未赋值！
}

// 正确示例 —— 总是赋值 output
public void Update(out float result, float input = 0f)
{
    if (input != _last)
    {
        _cached = Compute(input);
        _last = input;
    }
    result = _cached;
}

SDSL 着色器问题

关于 SDSL 语法规则、常见错误及正确/错误示例，请参考 vvvv-shaders 技能及其 syntax-rules.md 文件。主要问题包括：static const 作用域、缺少分号、缺少 override、枚举绑定格式错误。

运行时问题

内存泄漏

现象：内存占用随时间持续增长。

原因：

• 具有原生资源的节点未实现 IDisposable
• COM 对象（如 ComPtr<T>）未被释放
• 事件处理器订阅未取消

线程安全

现象：间歇性崩溃或数据损坏。

修复：Update() 在主线程运行。在构造函数中捕获 SynchronizationContext，然后将后台线程的结果回传到主线程：

private SynchronizationContext _vlSyncContext;

public MyNode()
{
    _vlSyncContext = SynchronizationContext.Current!;
}

// 从后台线程调用：
_vlSyncContext.Post(_ => { /* 在 VL 线程上执行 */ }, null);

循环依赖

现象：vvvv 提示存在循环依赖，补丁无法编译。

修复：插入一个 FrameDelay 节点以打破循环。

构建问题

目标框架不匹配

现象：DLL 加载成功但类型找不到。

修复：确保 .csproj 文件的目标框架为 net8.0（与 vvvv gamma 的运行时一致）。

程序集版本冲突

现象：运行时出现 FileLoadException 或 TypeLoadException。

修复：将包版本与 vvvv 自带版本对齐。可检查 vvvv 的 lib/ 文件夹中的引用。

有关详细错误与解决方案的对应关系，请参阅 [error-catalog.md](error-catalog.md)。