诊断

DreamShader » 诊断

DreamShader 的诊断出现在哪里、如何读懂一条诊断，以及 1.x 生成器的消息后来怎么样了。一次编译报出的每条诊断都有一个稳定的 DSHnnnn 码*（自 2.0.0 起）*；码是契约，措辞不是。目录在 README.md——每个码及其严重级别和消息——每个码在其页面上都有一节，DSH1xxx.md … DSH9xxx.md，列有它名下报出的每条消息、报出它的位置、原因和修复方法。

[!NOTE] 到 1.9.x 为止大多数消息没有码：1.x parser 给自己的消息编了码，1.x 生成器约 560 个 报错点只报裸文本，本页当时也逐字收录那些文本。生成器和 parser 已经删掉，那些字符串 一条都不会再报出。如果你在旧日志或搜索结果里见到一条，1.x 消息及其码 列出了常见的那些。

诊断出现在哪里

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

诊断归属于产生它的源文件和产生它的那次运行。运行有三种：一个源文件的编译、它生成的某个材质的 shader 编译，以及对一个文件的启动时 VirtualFunction 扫描。

同一个文件里，记录按「编译、shader 编译、VirtualFunction 扫描」排序，各自内部按源文件排，所以一个文件的第一个错误是它编译时的错误。见 Bridge。

[!NOTE] bridge 从不在 commandlet 里运行。-run=DreamShader、-run=Cook 以及任何其他 commandlet 进程都不写 diagnostics.json、不写分片、不写 bridge.db 行；消息只存在于 日志中（以及一个 -DiagnosticsOut 文件中）。bridge 也会被 -NoDreamShaderEditorBridge 禁用。 见 Commandlet。

严重级别

一次编译按每条记录被报出时的级别登记它自己的记录——失败的编译登记全部，成功的编译登记它的警告和 note*（自 2.1.0 起；在此之前，每条入库的诊断都是 error，成功编译的警告只到达 Output Log）*。编译不解释的记录——generate-error、material-compile、virtual-function-sync——是 error。该字段及其取值见 Bridge。

不属于任何编译记录、只写日志的警告（UE_LOG(LogDreamShader, Warning, …)）从不进入存储。客户端遇到缺失或未知的严重级别时，按 error 处理。

消息位置

诊断按 MSVC 风格打印，带着它的码：

I:/Project/DShader/Materials/M_Sample.dsm(8,19): DSH4200: 'Tin' is not declared in this scope.

（自 2.0.0 起） 每个文件单独做词法和语法分析，所以位置从不从拼起来的文本映射回去。到 1.9.x 为止，解析错误带的是一个指向「import 内联之后的文本」的 near index {Index} 偏移，section 体里的位置是错的，大多数语句级消息根本没有位置。

一个阶段会报出它的全部错误——parser 和绑定器遇到一个错误后会继续往下走——而有错误的阶段会在下一阶段开始前停下流水线：有语法错误的文件不会进入绑定，绑定不过的文件不会被发射。

读懂一个码

首位数字是报出它的阶段；完整分配见 DreamShaderLang 2.0。

旧版规则（DSH5275–DSH5292）是 1.x 做过、而 1.x 源文件今天仍然会得到的行为，只是现在会说出来：只靠大小写才对得上的名字（DSH5275、DSH5276）、GLSL 拼写（DSH5277）、宽向量被截到窄位置（DSH5289）、一条赋值顺带声明了变量（DSH5292）。它是 .dsm / .dsf 上的 warning 或 info，从不出现在 .dss 里，而 dsc migrate 会把每一条都写成显式的 2.0 文本。

1.x 消息及其代码

1.x 解析器和生成器的常见消息，以及今天由什么报告同样的状况。{…} 代表消息里填入的内容。

不在表里的消息：到 README.md 里搜它所描述情况的一个词， 或者把文件编译一遍、读它现在报的码。

1.x 静默接受的写法

1.x 生成器一声不吭地接受、然后构建出与文本不符的东西（或者把文本说的东西丢掉）的情况。（自 2.0.0 起）每一种都有诊断。

1.x 写进文档、1.x 源文件仍在依赖的写法 —— 换了大小写的名字、GLSL 拼写、写进 float3 位置的 float4 —— 照样构建， 作为一条把它说出来的 legacy 规则。

VirtualFunction 同步

启动服务会重新读取每一个 VirtualFunction 声明，并从它的 UMaterialFunction 资产刷新它，以及 Material Function 工具栏和上下文菜单上的编辑器操作。 这些消息没有 DSHnnnn 码，DSH9001 除外 —— 用于使用 #if 的源文件。

同步诊断通过 stage = virtualFunctionSync、code = virtual-function-sync 和 source = DreamShader VirtualFunction 进入存储。编辑器操作消息是 toast 通知和 日志行；它们不会被存储。

[!NOTE] 同步服务按裸关键字 VirtualFunction 找声明，区分大小写， 两边要有标识符边界 —— 和 legacy 前端对块关键字的要求一样。 小写的 virtualfunction 两边都看不见。

其他日志行

不属于任何编译、永远不入库的行。

commandlet 自己的运行行、用法横幅和退出码在 命令行；反编译器的在反编译导出。

示例

Graph 块里的一个拼写错误，到达各个界面时的样子。

// 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): DSH4200: 'Tin' is not declared in this scope.

Saved/DreamShader/Bridge/diagnostics.json：

{
  "version": 1,
  "updatedAtUtc": "2026-10-04T11:04:22Z",
  "files": [
    {
      "path": "I:/Project/DShader/Materials/M_Sample.dsm",
      "diagnostics": [
        {
          "message": "'Tin' is not declared in this scope.",
          "detail": "I:/Project/DShader/Materials/M_Sample.dsm(8,19): DSH4200: 'Tin' is not declared in this scope.",
          "stage": "bind",
          "code": "DSH4200",
          "line": 8,
          "column": 19,
          "severity": "error",
          "source": "DreamShader Lang2"
        }
      ]
    }
  ]
}

同一条记录还会写进 Bridge/diagnostics/<md5>.json 和 Bridge/bridge.db 的 diagnostics 表，并出现在 Material Content Browser 里这个源文件的那一行。stage 由 码的范围决定：preprocess、parse、bind、ir、generate 或 tools。

另请参阅

• README.md — 每个码，及其严重级别和消息
• 桥接 — 请求文件、WebSocket 协议和诊断产物
• Material Content Browser — 显示每个源文件记录的那个标签页
• 命令行 — -run=DreamShader、-DiagnosticsOut、它的开关和退出码
• DreamShaderLang 2.0 — 完整的码范围
• dsc migrate — 以 2.0 文本写出的 legacy 规则
• 源文件 — 多个码所强制执行的文​件类型规则
• import — 头部如何被读取，以及 import 的码
• 测试 — 固定了许多这些码的语料库夹具