#诊断码表

每条诊断都带位置、原因和修复建议，底下那行链接就指向本页对应的锚点。

error[DIR-204] tab 缺少指令标题
  --> 方案.md:3:1
  |
3 | :::tab
  | ^
  |
  = 指令标题写在方括号里：:::tab[指令标题]。Tab 的指令标题就是那个可以点的按钮
  https://lazygophers.github.io/pamphlet/reference/diagnostics.html#dir-204

#码怎么读

四个码段，码本身不编码严重程度：

严重程度是独立字段（error / warning），因为 --fail-on-warn 能把警告也变成失败 —— 如果码里写死了 E / W 前缀，那个开关就自相矛盾了。

#DOC-1xx 文档与 frontmatter

#DOC-101

spec 高于编译器支持的版本。 严重程度 error。

这份文档要求的语法版本比你装的 Pamphlet 新。升级编译器，或把 spec 改回去。

本编译器支持的版本是 1。

#DOC-102

frontmatter 里有未知字段，已忽略。 严重程度 warning。

认识的字段只有 spec / title / theme / lang / toc / engines，toc 里面只有 enable / deep / skipTabs / position。见 frontmatter 参考。

不静默忽略是有意的 —— 静默忽略会让你以为配置生效了。

#DOC-103

frontmatter 不是合法 YAML，或某个字段的类型不对。 严重程度 error。

常见的几种：

诊断会定位到出问题那个字段所在的行，不是笼统地指向 frontmatter 开头。

#DOC-104

字段值合法，但本版本还没实现。 严重程度 warning。

目前只有一处：engines（自定义引擎）—— 这段声明暂时不起作用，内置引擎照常工作。

（toc.position: side 曾经也报这条。侧边菜单实现之后它成了缺省值，不再报任何东西。）

#DOC-105

用了脚注，本版本不支持。 严重程度 error。

GFM 的脚注（[^1] 加 [^1]: 注释）解析得出来，但组装器没有对应的处理 —— 引用会渲染成空字符串，定义的正文会被原地插进正文流。

报错而不是静默丢弃：静默丢掉意味着你写的注释在产物里凭空消失，而你不会发现。

替代写法见提示块。

引用和定义各报一条，孤立的定义（没有任何引用）也报。

#DOC-106

指定的主题名不存在。 严重程度 error。

--theme 或 frontmatter 的 theme: 写了一个不认识的名字。提示里一套一行地列出全部内置主题，每个名字后面跟着它适合写哪一类文档，所以不必去翻文档就能挑对。

报错但不中断编译：退回 default 照样产出产物 —— 主题错了只影响长相，内容是对的。

是 error 而不是 warning，因为静默换一套主题会让你以为写的那个生效了。

见内置主题。

#DIR-2xx 容器指令

#DIR-201

未知指令，内容已按普通段落输出。 严重程度 warning。

只是警告不是错误，因为不认识的指令仍然会把内容原样输出，不会丢字。

诊断会尽力指路，认得出别的工具的写法：

编辑距离 ≤ 2 的拼写错误也会给出「是不是想写 X？」。

#DIR-202

指令用错了位置或形态。 严重程度 error。

两种情况：

• 写成了非容器指令。 全部九个指令都是容器指令，必须用成对的冒号包住内容
• tab 没有直接放在 tabs 里。 提示会告诉你：外层的冒号要比内层多一个（::::tabs 里面套 :::tab[指令标题]）

#DIR-203

指令未闭合。 严重程度 error。

闭合栅栏优先匹配相同冒号数；被跨过的内层一律记为未闭合。这样报错位置指向真正没关的那一个，而不是最外层。

#DIR-204

指令缺少必需的部分。 严重程度 error。

#DIR-205

同一组 tabs 里有多个 {default}。 严重程度 error。

只能有一个 tab 标 {default}；都不标时选中第一个。

报错而不是静默取第一个 —— 静默猜测会产出和你意图不同的产物。

#DIR-206

属性值不在允许的取值里。 严重程度 error。

目前只有 reveal{effect=…}：可用值是 fade-up（缺省）/ fade-in / slide-left / slide-right。诊断会把可用值全部列出来。

#DIR-207

这个指令不认识这个属性，已忽略。 严重程度 warning。

提示会列出该指令认识的属性；一个属性都不接受时会直说「不接受任何属性」。

#DIAG-3xx 图表引擎

#DIAG-301

渲染这种图表需要的引擎没装。 严重程度 error。

两种消息：

• 没有装能画 X 的引擎 —— 根本没有引擎认领这个围栏语言。本版本只实现了 Mermaid，所以 d2 / dot / math 等都会走到这里
• 渲染 X 图表需要 Y 引擎 —— 引擎存在但可选依赖没装，提示里带完整的安装命令

先跑 pamphlet doctor 看各引擎的安装状态。见其余七种图表。

#DIAG-302

单张图的 SVG 过大。 严重程度 warning。门槛 200KB。

图太大通常意味着节点太多，读者也看不清；考虑拆成几张。

#DIAG-303

渲染超时或失败。 严重程度 error。

超时是 10 秒。这个数字有实测依据：第 1 张含浏览器冷启动 733ms，之后 364ms，40 节点大图 412ms —— 10 秒约是最坏值的 13 倍。

图源语法错时，提示会建议贴到 https://mermaid.live 上定位。

图没画出来时产物仍然会写出来，那张图的位置留一个占位框，同时退出码为 1。这样你能立刻看出问题只在那一张图上。

#DIAG-304

引擎输出里有硬编码色值，换不成主题变量。 严重程度 warning。

这些颜色不会跟着主题变；切到深色主题时留意这张图有没有看不清的地方。

诊断会把换不掉的色值列出来。这条警告存在的唯一理由，就是防住「引擎升级后颜色替换规则静默失效」—— 那种失效不报出来根本发现不了。

#DIAG-305

结构化图表的块写错了。 严重程度 error。

结构化写法（:::flow 这一路）的指令体是「块名一行、条目缩进写在它下面」。这条码覆盖四种写法错误：

那张图的位置留占位框，文档照常编译。

#DIAG-306

结构化图表的关系写错了。 严重程度 error。

关系块里的一行读不成一条关系，或者它引用了声明块里没有的名字：

• a -> ghost，而 ghost 没在 nodes: 里声明过
• 饼图的数值不是数字（样式 : 很多）
• 甘特图的任务挂在一个没声明过的阶段上
• git 分支图用了不认识的操作

提示会把已经声明过的名字列出来，方便对拼写。

#DIAG-307

结构化图表用了不认识的形状。 严重程度 error。

a = triangle "甲" 里的 triangle 不在这种图认识的形状表里。提示会列全能用的那几个（流程图是 box / round / stadium / diamond / circle / hexagon / cylinder / parallelogram）。

数据图表的 {type=donut} 也走这条码。

#EMB-4xx 资源内嵌

#EMB-401

单个资源超过字节上限。 严重程度 error。上限 2MB。

提示会给出具体办法：压一下再放进来（PNG 试 pngquant --quality=70），或者改用图表围栏画成 SVG。

上限存在是因为 base64 编码会让体积膨胀 33.3%（RFC 2045 §6.8、RFC 4648 §4）。

#EMB-402

读不到这个资源。 严重程度 error。

图片路径相对于源文档所在目录解析，不是相对于你跑命令的目录。见图片与资源。

#EMB-403

引用了远程资源，自包含不允许。 严重程度 error。

![图](https://example.com/图.png)   ❌
![图](./图.png)                      ✅

把它下载到本地再引用 —— 一本 pamphlet 打开时不向网络要任何东西。

没有绕过开关。远程资源直接报错而不是静默下载，这样就不会有人不小心产出一个需要联网的产物。

#EMB-404

这种字体格式不能子集化。 严重程度 error。

.ttc（字体集合，一个文件里装了好几套字体）不能直接子集化。用 --font 时换成单独的 .ttf / .otf。

子集化失败（字体文件损坏等）也报这条，消息里带底层原因。