不能处理注释的web资源

上周帮朋友排查一个前端 bug，处理折腾了三个小时才发现问题出在一段被压缩工具吃掉的注释资源注释上。代码逻辑本身没问题，处理但构建后的注释资源文件里，原本标注接口参数含义的处理那行 // 0 表示禁用，1 表示启用 消失了，注释资源接手的处理人把 0 当成了默认值直接传进去，后端炸了。注释资源

这事让我重新注意到一个老问题：很多 web 资源压根不打算让你好好写注释。处理HTML、注释资源CSS、处理JavaScript 都算上，注释资源它们对注释的处理态度其实挺分裂的。

HTML 的注释资源注释语法 <!-- --> 从 1993 年活到现在，看起来稳如磐石。处理但你要是把注释写在标签属性中间试试？<div <!-- 这里不行 --> class="box">，浏览器直接把它当垃圾扔掉，连报错都懒得给。更微妙的是条件注释——IE 时代那套 <!--[if IE]> 的 hack，现代浏览器会把它当作普通注释忽略，可如果你用某些模板引擎渲染，它又可能被当成特殊指令处理。同一个字符串，在不同解析器眼里完全是两种东西。

CSS 那边更干脆。/* */ 是唯一合法的注释形式，// 这种在 Sass/Less 里活得好好的写法，到了原生 CSS 文件里就是语法错误。我见过有人把预处理器的输出直接丢给浏览器，结果整段样式表从注释那行开始全部失效。浏览器不会告诉你“这里有个注释不合法”，它只是默默停下解析。调试的时候你盯着 DevTools 里缺失的规则，根本想不到是两行注释惹的祸。

JavaScript 的注释倒是宽容，// 和 /* */ 都认。但问题出在工具链上。UglifyJS、Terser 这些压缩器默认会把所有注释删干净——这本来合理，注释不占运行逻辑。可如果你用 /*! */ 这种带感叹号的写法，它又会保留。这个规则没有任何标准文档规定，纯粹是工具作者们的约定俗成。换个压缩器，行为可能就变了。更别提 source map 里的注释映射，有时候压缩后的代码和原始注释对不上号，你在浏览器里看到的“源码”其实是错位的。

JSON 最绝。它从设计之初就不支持注释。Douglas Crockford 当年故意去掉的，理由是“注释会被滥用”。结果呢？配置文件里想写点说明，只能塞个 "_comment": "..." 这种假字段进去，解析的时候还得手动过滤掉。VS Code 的 settings.json 倒是允许注释，但那是因为它用了 JSONC 这个超集，跟标准 JSON 不是一回事。你要是把带注释的配置文件丢给一个严格的 JSON 解析器，直接报错没商量。

XML 看起来规矩，<!-- --> 用了几十年。但 XML 注释里不能出现 --，这个限制让很多人踩坑。你想写“双横线分隔符”这种说明，得拆成 - - 或者换个说法。而且注释不能嵌套，一层套一层直接语法错误。处理 XML 的库有时候还会把注释节点保留在 DOM 里，遍历子节点的时候得额外判断类型，不然就会拿到一堆注释对象。

这些限制背后其实有个共同逻辑：注释在解析器眼里不是“给人看的说明”，而是“可以安全丢弃的字节”。一旦某个工具决定丢弃它，你就别指望能找回来。压缩、打包、转译、序列化——每经过一道工序，注释就少一层保障。有的工具会保留 license 注释，有的会保留 @preserve 标记，但这些都是特例，不是通例。

我现在的习惯是：关键参数说明写在文档里，代码里只留最简短的标记。如果非要在代码里写注释，优先用工具链明确支持的格式，比如 /*! */ 或者 @license。至于那些会被吃掉的注释，就当它们从来没存在过。毕竟浏览器和构建工具不会为你的注释负责，它们只关心解析结果对不对。