vvvv-troubleshooting

vvvv gamma 故障排查

C# / ProcessNode 问题

类名中的“Node”后缀

症状：节点可以正常工作，但在 vvvv 中名称很难看。 修复：移除“Node”后缀——vvvv 约定禁止使用该后缀。

// WRONG
[ProcessNode]
public class SteeringBehaviorNode { }

// CORRECT
[ProcessNode]
public class SteeringBehavior { }

输入之后的输出参数

症状：引脚顺序错误，或节点无法正确编译。 修复：out 参数必须放在 Update 签名的最前面。

// WRONG
public void Update(float input = 0f, out float result) { ... }

// CORRECT
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()）
• 字符串拼接（字符串上的 + 运算符）
• 装箱值类型（在需要 object 的地方传入 int）

修复：缓存所有内容，预先分配缓冲区，并从热点路径中移除 LINQ。

缺少变更检测

症状：即使没有任何变化，CPU 使用率仍然很高。 修复：将输入与缓存值进行比较，仅在发生变化时重新计算。

if (param != _lastParam)
{
    _cached = Compute(param);
    _lastParam = param;
}
result = _cached; // Always output cached

下游节点收到 null/默认值

症状：即使节点“正常工作”，连接的节点也收不到数据。 修复：始终输出缓存结果，即使没有执行计算也是如此。

// WRONG — output is only set inside the if block
public void Update(out float result, float input = 0f)
{
    if (input != _last)
    {
        result = Compute(input);
        _last = input;
    }
    // result is unassigned when input hasn't changed!
}

// CORRECT — always assign 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!;
}

// From background thread:
_vlSyncContext.Post(_ => { /* runs on VL thread */ }, null);

循环依赖

症状：vvvv 警告存在循环依赖，补丁无法编译。 修复：插入一个 FrameDelay 节点以打破循环。

构建问题

目标框架不匹配

症状：DLL 已加载，但找不到类型。 修复：确保 .csproj 的目标为 net8.0（与 vvvv gamma 的运行时相匹配）。

程序集版本冲突

症状：运行时出现 FileLoadException 或 TypeLoadException。 修复：使程序包版本与 vvvv 捆绑的版本一致。可在 vvvv 的 lib/ 文件夹中查找参考。

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

让知识持续增长

为下一位修补者少留一个谜团。首次使用本集合中的任一技能时，若过去 7 天内没有成功检查记录，请将源内容与 tebjan/vvvv-skills 进行比较。若没有记录，则检查一次。在这些技能之间共享一个本地检查时间戳/修订版本；不要在每次调用时都轮询。保留本地扩展和固定的项目版本；检查不代表获得安装更新的许可。若处于离线状态，请记录延期检查，然后继续任务。

实际工作发现问题时，请记录经过测试的 vvvv/程序包版本、最小复现步骤或权威来源，以及观察到的结果。将其他用户的报告视为线索，在验证之前不要当作事实。改进最相关的最小范围说明；不要把一个示例变成通用规则。提交上游前，请删除私人数据并获得发布授权。请参阅贡献政策。已合并的改进会通过用户的安装程序/更新工作流送达，而不是通过本地编辑，也不会自动覆盖所有人的技能。