错误速查

每一次编译失败都表现为一条 诊断：一条消息，归属于一个源文件，通常带着行号和列号。本页讲清楚这些消息出现在哪里、 怎么读，然后按产生它的阶段列出实际项目里真正会撞上的那些。

诊断出现在哪里

三个 bridge sink 每次更新都一起写，所以它们永远不会互相矛盾。Output Log 是另一条独立路径，也是唯一还会显示 成功 消息的界面。

诊断归属于产生它的源文件。重新编译 A.dsm 只清掉 A.dsm 产生的记录 —— 包括归到某个被 import 的 .dsh 上的记录 —— 而不会动另一个材质在同一个头文件上的诊断。

只有一种严重级别

Severity 默认是 "error"，插件里任何地方都不会把它赋成别的值。三个值得知道的后果：

• 解析 warning —— 被弃用的写法、缺少 Outputs 的提醒 —— 从不入库。它们被追加到编译结果消息上，只在 Output Log 里出现。
• 只写日志的 warning 同样不入库。
• 按严重级别上色的扩展，会把每一条 DreamShader 记录都画成 error。

Gen 页对缺失或非 error 的 severity 采取过滤而不是报错，所以将来加一个新级别不会把它弄坏。

读懂一条消息

带位置的诊断按 MSVC 风格格式化：

I:/Project/DShader/Materials/M_Sample.dsm(37,9): Unknown Graph identifier 'Tin'.

{Placeholder} 约定

下面每张表里的运行时替换都写成 {Placeholder}。后面跟着 ... 的花括号 —— 比如 Graph = { ... } —— 是消息的字面文本，不是占位符。

下面的消息全部 逐字 引用，包括标点不一致的那些。确实有一条消息末尾没有句点，出现的地方已经标出。

解析

词法扫描、顶层块头，以及 import 内联器。它们跑在任何 section 体被检查之前；这里失败会中止整个文件。

Section 与声明

section 分派、Outputs 自己的文法、Layout、#Region、Group(…) 作用域，以及输出声明和绑定的解析后校验。

Graph 语句与表达式

Graph = { … } 内部的语句与表达式语言，外加构造器、swizzle 和强制转换。这里的解析阶段消息通常被语句级前缀 In Graph statement '{Statement}': {Detail} 包起来。

内置节点

Graph 里的 UE.* 与 Substrate.* 调用面、Properties 里的 UE.* 声明形式、数学内置节点，以及共用的反射值写入器。 {Namespace} 是 UE 或 Substrate。

函数与调用

从 Graph 调用 Function、GraphFunction、ShaderFunction、ShaderLayer、ShaderLayerBlend 和 VirtualFunction，以及生成的 HLSL helper include。{Kind} 是调用种类。

Properties 与参数

Properties 声明、[ … ] 元数据块、参数节点构造、Path( … ) 资产引用，以及从 Graph 读取参数。

Settings

Shader 的 Settings section —— 特殊键加上反射到 UMaterial 的属性路径 —— 以及材质函数 Settings 认可的四个键。 {Key} 回显的是 小写化后 存下来的键，不是作者书写的写法。

资产生成与保存

流水线闸门、资产命名与 root 解析、节点图填充、归属守卫，以及 package 保存。

命令行

-run=DreamShader 与 cook 阶段的生成钩子。这些都不会进入诊断存储 —— bridge 不在 commandlet 进程里运行。

VirtualFunction 同步

启动时重新读取每个 VirtualFunction 声明、并从它的 UMaterialFunction 资产刷新的那个服务。这些会以 stage = virtualFunctionSync 入库。

警告

警告不会让编译失败，也不会进入诊断存储。它们被追加到编译结果消息上，或者记在 LogDreamShader 下。

其他值得认得的警告：

什么都不报的时候

有些错误根本不会产生消息。数量最大的一类是 表达式截断：Graph 的词法器把它不认识的每一个字符 —— %、&、|、^、<、>、?、[、! 等等 —— 变成表达式结束 token，然后 parser 接受它前面那段表达式。 a % b 编译成 a，if (x > 0 && y > 0) 编译成 if (x > 0)。

不支持的写法 用一整页讲这件事。其余静默情况的简表在 当前限制。

成功消息

同一条流水线在成功时返回下面这些 —— 在脚本里编译并匹配输出时很有用。

一条错误，四个界面

// DShader/Materials/M_Sample.dsm
Shader(Name="Materials/M_Sample")
{
    Properties = { vec3 Tint = vec3(1.0, 0.4, 0.1); }
    Outputs    = { vec3 Color; Base.EmissiveColor = Color; }
    Graph      = {
        vec2 UV = UE.TexCoord(Index = 0);
        Color   = Tin * UV.x;          // typo: Tin, not Tint
    }
}

Output Log：

LogDreamShader: Error: I:/Project/DShader/Materials/M_Sample.dsm(8,19): Unknown Graph identifier 'Tin'.

Saved/DreamShader/Bridge/diagnostics.json：

{
  "version": 1,
  "updatedAtUtc": "2026-07-29T11:04:22Z",
  "files": [
    {
      "path": "I:/Project/DShader/Materials/M_Sample.dsm",
      "diagnostics": [
        {
          "message": "Unknown Graph identifier 'Tin'.",
          "detail": "I:/Project/DShader/Materials/M_Sample.dsm(8,19): Unknown Graph identifier 'Tin'.",
          "stage": "generate",
          "code": "generate-error",
          "line": 8,
          "column": 19,
          "severity": "error",
          "source": "DreamShader Generate"
        }
      ]
    }
  ]
}

同一条记录还会写进 Bridge/diagnostics/<md5>.json 和 Bridge/bridge.db 的 diagnostics 表，并出现在 Dream Shader Gen 页的源文件列表里 —— 这也正是 VSCode 和 Rider 扩展用来画波浪线的数据。

按顺序修

一个文件报出一大堆消息时，请自上而下地修。后面的阶段跑在前面阶段的产物上，所以一个解析错误能凭空生出十几条下游抱怨。

继续阅读