JSDoc 版本演进全解析：从 3.0.0 到 4.0.0 的变更历史导读

• 开发工具
• 文档

本文以仓库根目录的 CHANGES.md 为蓝本，系统梳理 JSDoc（JavaScript API 文档生成器）从 3.0.0 到 4.0.0 十余年间的版本演进脉络，并结合当前仓库的源码、配置与测试资源，逐一还原每个版本引入的解析能力、标签体系、CLI 参数、配置项与插件生态。读完本文，你将理解 JSDoc 在 Node.js 兼容性、ECMAScript 2015+ 语法支持、Closure Compiler 类型系统、模板与插件机制等关键维度上的完整演变过程，并掌握如何利用配置与命令行参数把这些能力落到实际文档生成工作中。

一、CHANGES.md 是什么：一份可追溯的版本档案

CHANGES.md是 JSDoc 官方维护的变更历史文件，明确说明"本文件描述 JSDoc 自 3.0.0 起每个版本的重要变化"（原文档英文标题为 "JSDoc change history"）。它不仅是用户升级时的对照手册，也是理解 JSDoc 架构演进的权威史料：从 3.0.0（2012 年 5 月，初始发布）到 4.0.0（2022 年 11 月），每个版本记录的内容可分为几类：

• 主要变化（Major changes）：运行时环境、解析器、语义版本策略等影响面最大的变更；
• 增强（Enhancements）：新增的配置项、CLI 参数、标签解析能力；
• Bug 修复（Bug fixes）：针对 ES2015 类/模块、类型表达式、插件、模板的具体问题；
• 插件（Plugins）与模板改进（Template improvements）：官方插件与默认模板/Haruki 模板的行为变化。

阅读本档案时，可配合仓库中的 README.md、packages/jsdoc/conf.json.EXAMPLE 与各packages/子包源码交叉印证，例如配置项的实际默认值可以追溯到 packages/jsdoc-core/lib/config.js 中的defaultConfig对象，命令行参数的精确语义可以追溯到 packages/jsdoc-cli/lib/flags.js。

二、4.0.0（2022 年 11 月）：语义化版本与 TaffyDB 告别

4.0.0 是 JSDoc 进入新纪元的里程碑版本，CHANGES.md 记录了三条核心变化：

1. 采用语义化版本（SemVer）：今后若 JSDoc 出现不向后兼容的变更，主版本号（major version）会相应递增，用户可以根据版本号预判升级风险。
2. 彻底移除taffydb依赖：这是 4.0.0 最具影响力的内部重构。如果用户自研的模板或插件仍在引用taffydb包，需要迁移到替代包@jsdoc/salty。
3. 支持 Node.js 12.0.0 及以上：把运行时下限统一抬升到 Node.js 12。

2.1 为什么用 Salty 替换 TaffyDB

要理解这次替换的意义，需要看仓库中 packages/jsdoc-salty/README.md 的完整说明：JSDoc 3.x 长期使用 TaffyDB 管理 doclet（描述代码信息的对象）——解析完代码后，JSDoc 会把 doclets 以 TaffyDB 对象的形式交给模板，模板再通过 TaffyDB 查询删除无用 doclet、检索生成文档所需的数据。替换的原因有二：

• TaffyDB 早已无人维护，且存在公开的 CVE-2019-10790 记录（虽然 JSDoc 只把代码自身的元数据存于内存、不落盘，实际并不构成真实安全风险，但"存在 CVE"本身就足以让安全审查与依赖扫描工具报警）；
• TaffyDB 的许可证声明长期自相矛盾：README 声称使用 1-clause BSD，package.json声称 2-clause BSD，而 License 文件又声称 MIT，造成合规性隐患。

Salty 是"只支持 JSDoc 历史上用到的那些 TaffyDB 特性"的裁剪版实现，采用 Apache 2.0 许可证，同时解决了安全审查噪音与许可证不确定性。

2.2 把自定义模板从 taffydb 迁移到 @jsdoc/salty

如果使用 JSDoc 4.0.0 自带模板，无需任何改动；只有自定义模板才需要迁移，packages/jsdoc-salty/README.md 给出了五步操作：

1. 在模板的publish.js中定位require('taffydb')语句（常见写法为const taffy = require('taffydb').taffy;或const { taffy } = require('taffydb');）；
2. 把包名替换为@jsdoc/salty，即const { taffy } = require('@jsdoc/salty');；
3. 从模板的package.json中删除taffydb依赖；
4. 在模板的package.json中新增@jsdoc/salty依赖；
5. 在模板目录执行npm install并验证模板行为。

迁移后模板仍可与 JSDoc 3.x 兼容。需要注意的是，Salty 只支持 TaffyDB 的查询、排序、迭代、删除等子集能力，排序顺序比 TaffyDB 更可预测（非空值按标准序 → 空值 → 显式 undefined → 隐式 undefined）。

三、3.6.x 系列（2019—2022）：兼容性维护期

3.6.x 是发布最频繁的维护分支，CHANGES.md 记录的重点如下：

• 3.6.11（2022 年 7 月）：更新依赖版本，使其与 Node.js 12.0.0 及更高版本兼容；
• 3.6.10（2022 年 1 月）：修复 3.6.9 在部分 CI 环境无法安装的问题；
• 3.6.9（2022 年 1 月）：修复npm install jsdoc无法工作的问题；
• 3.6.8 / 3.6.7 / 3.6.4 / 3.6.3 / 3.6.2 / 3.6.1：以依赖更新为主，其中 3.6.2 修复 ES2015 类不出现在生成文档中的问题，3.6.1 防止 Node.js 12 下使用类型应用（type applications）时崩溃；
• 3.6.6（2020 年 9 月）：修复"既是 ES2015 类又被赋值给变量"的接口（interface）成员跟踪错误，例如：

/** @interface */ foo.Bar = class { constructor() { /** 此前该成员会从生成文档中缺失 */ this.baz = null; } };

• 3.6.5（2020 年 7 月）：当两个函数参数使用相同的类型表达式且带有--debug标志时，防止 doclet 出现循环引用；
• 3.6.0（2019 年 5 月）：兼容 Node.js 12 并要求 Node.js 8.15.0+，同时"识别全部已文档化的 Closure Compiler 标签"。

3.1 3.6.0 的增强与修复要点

3.6.0 引入了几个至今常用的配置能力：

• templates.useShortNamesInLinks：链接文本显示符号的短名（如baz）而非完整 longname（如foo.bar.baz）；
• Markdown 插件支持自定义代码块的语法高亮函数；
• 默认模板把命名空间（namespaces）放到 TOC 靠前位置；
• 修复了给 ES2015 构造函数添加 JSDoc 注释时丢失除 description 与 params 之外标签的问题；
• @exports与@enum组合使用时可正常工作；
• Markdown 插件中语言标记为plain的代码围栏不再被 pretty-print。

四、3.5.0（2017 年 7 月）：Babylon 解析器与新标签时代

3.5.0 是 JSDoc 解析能力质变的一次大版本，CHANGES.md 用大篇幅记录了这次升级。

4.1 解析器切换与 ECMAScript 新语法支持

JSDoc 改用 Babylon（Babel 的 JavaScript 解析器），因此能够解析 Babel 编译器支持的任何 JavaScript 或 JSX 文件，包括：

• 装饰器（Decorators）；
• 公有与私有类字段（class fields）；
• 异步迭代器（async iterators）；
• 动态import()；
• 可选链（optional chaining）。

同时，JSDoc 也由此可以解析异步函数（async function foo() {}）并自动检测其为异步，自动检测生成器函数（generator functions）。当前仓库的解析链路中，sourceType会经 packages/jsdoc-parse/lib/parser.js 传入 packages/jsdoc-ast/lib/ast-builder.js 的build(source, filename, sourceType)方法参与构建 AST，与这段历史一脉相承。

4.2 新标签：@async、@generator、@hideconstructor、@package、@yields

3.5.0 新增五个标签（官方提示第三方模板可能不支持这些新标签）：

• @async：标记异步函数。一般情况下无需使用，因为 JSDoc 会自动检测以async function foo() {}声明的函数；
• @generator：标记生成器函数，同样可被自动检测，通常无需手写；
• @hideconstructor：在文档中隐藏类的构造函数；
• @package：标记符号为包私有（package-private）；
• @yields：文档化生成器函数产出的值。

这些标签的定义可继续在 packages/jsdoc-tag/lib/definitions/jsdoc.js 中查看，对应的测试夹具与测试规格分别位于 packages/jsdoc/test/fixtures 与 packages/jsdoc/test/specs/tags。

4.3 新增配置项与事件字段

• sourceType：控制 JS 文件解析方式，默认值module；设为script可抑制隐式严格模式，但也会禁止使用 ES2015 模块。这一默认值在当前仓库的 packages/jsdoc-core/lib/config.js 中依然可见（sourceType: 'module'），且 packages/jsdoc-cli/test/fixtures/configs/conf.json 中也有"sourceType": "script"的测试用例；
• recurseDepth：控制 JSDoc 递归搜索文件的层数，默认值 10；
• JS 配置文件：可以用 JavaScript 文件配置 JSDoc，该文件必须是导出单个配置对象的 CommonJS 模块；
• 事件增强：jsdocCommentFound与symbolFound事件新增columnno属性，报告注释或符号所在的列号；无法解析类型表达式时，日志会输出类型表达式所在行号。

4.4 3.5.0 的主要 Bug 修复

• ES2015 类的构造函数与实例属性可被正确文档化；从 ES2015 模块导出的类的构造函数、导出符号及其子符号的 scope 均正确；
• 修复 UTF-8 JSON 文件带 BOM 时崩溃、@author标签无值崩溃、函数赋给变量时默认/可重复参数自动检测等问题；
• JSDoc 退出时总是调用process.exit()。

五、3.4.x（2015—2016）：Node.js 化与模板体系完善

• 3.4.3（2016 年 11 月）：更新 LICENSE 文件；
• 3.4.2（2016 年 10 月）：修复 ES2015 模块导出类的文档化、插件与模板加载、实验性对象展开运算符导致的崩溃；
• 3.4.1（2016 年 9 月）：tags.allowUnknownTags配置现在可以接受一个允许的标签名数组；默认模板为表格采用合适的样式；新增silent模板（不生成任何输出），便于把 JSDoc 当作"linter"检查注释语法错误与无法识别的标签；
• 3.4.0（2015 年 11 月）：JSDoc 正式放弃 Mozilla Rhino，仅支持在 Node.js 4.0.0+ 上运行；可以解析 ECMAScript 2015 原生类与模块、JSX 文件；const声明被自动视为常量；app与env全局变量被弃用（改用jsdoc/env模块）；模板的publish方法可返回 Promise，从而支持异步模板。

3.4.0 还带来了 Markdown 插件的markdown.idInHeadings配置（为标题自动生成 heading ID）、默认模板的templates.default.useLongnameInNav配置（导航栏显示完整 namepath）等细节。

六、3.3.0（2015 年 5 月）：Node.js 运行能力与接口标签落地

3.3.0 标志着 JSDoc 可以在 Node.js 上运行（#93），并引入一组沿用至今的接口语义：

• @interface与@implements标签：文档化接口及其实现；
• 支持 Closure Compiler 的@inheritDoc与@override；
• 符号带@mixes标签时，所有 mixin 都会出现在文档中；
• --verbose标志：运行中向控制台记录信息（如每个解析文件的名字）；
• -P/--package与-R/--readme标志：可指定任意文件作为文档的 package 或 README 文件；
• --pedantic标志：把所有错误视为致命错误、把警告视为错误，取代了含义相反的--lenient；
• -a/--access标志：控制私有、受保护与公有符号是否出现在文档中。

当前 packages/jsdoc-cli/lib/flags.js 中这些标志的定义仍然完整：access（别名a，可选值all/package/private/protected/public/undefined，默认"除 private 外全部"）、pedantic、verbose、debug、package（别名P）、readme（别名R）等一应俱全。

6.1 配置体系增强

3.3.0 起配置系统显著增强，多数能力沿用至今：

• 配置文件可以包含 JavaScript 注释（JSON 注释形式）；
• source.exclude支持排除-r/--recurse扫描时的子目录；-r模式下教程（tutorials）也递归扫描；
• tags.dictionaries：可启用 Closure Compiler 专用标签字典，取值可为jsdoc、closure或两者；多字典启用时，若某标签在多个字典中有定义，JSDoc 采用第一个包含该标签的字典中的定义。当前 packages/jsdoc-core/lib/config.js 的默认值为dictionaries: ['jsdoc', 'closure']；
• 覆盖符号的 doclet 会新增overrides属性（内含被覆盖符号的 longname）；
• doclet 的type对象会包含隐藏的parsedType属性，即由 Catharsis 生成的类型表达式语法树（格式未来可能变化）；
• 输出文件名允许非 ASCII 字符，必要时 URL 编码；输出文件不以前导下划线开头；id属性尽量保证文件内唯一；
• 无输入文件或命令行选项无法识别时，JSDoc 会显示用法信息。

6.2 3.3.0 的插件与模板改进

• 插件方面：标签定义可增加mustNotHaveDescription属性（为真时，标签文本含描述将告警）；新增summarize插件（根据描述自动生成摘要）与underscore插件（自动把以下划线开头的符号标记为@private）；Markdown 插件默认把@author与@throws标签值转换为 HTML，且不再阻止内联{@link}标签工作。
• 模板方面：可通过templates.default.layoutFile覆盖主布局layout.tmpl；templates.default.outputSourceFiles: false可隐藏源码路径；templates.default.staticFiles.include可复制额外静态文件到输出目录（staticFiles.paths已弃用）；templates.default.includeDate: false可隐藏页脚日期；美化打印的源码带行号；@example中的文本（含 HTML 标签）会被正确转义。

这些插件目前仍以独立文件形式存在于 packages/jsdoc-plugins 目录中，如 summarize.js、underscore.js、comments-only.js、partial.js、event-dumper.js、overload-helper.js 等。

七、3.2.x（2013）：Closure Compiler 类型表达式与事件系统

7.1 3.2.0（2013 年 5 月）

• 可解析任何合法的 Google Closure Compiler 类型表达式；相应地，文件含非法类型表达式时 JSDoc 会退出，可用--lenient（-l）标志阻止退出；
• 新增@listens标签：标记符号监听某个事件；
• 解析器新增parseBegin事件（开始解析前触发，处理器可修改待解析文件列表）与parseComplete事件（全部解析后触发）；
• jsdocCommentFound事件处理器现在可以修改 JSDoc 注释；
• 新增markdown.excludeTags配置：从 Markdown 处理中排除指定标签；
• @typedef配合 Closure 风格类型定义时可省略名称（自动获得Foo.Bar这类名称）；
• 参数描述中可使用内联{@type}标签，例如@param {(boolean|string)} myParam - My special parameter. {@type Foo}会把myParam的类型记录为Foo；
• 新插件overloadHelper便于链接到重载方法；markdown 插件转换@see中的 Markdown 链接。

7.2 3.2.1（2013 年 10 月）与 3.2.2（2013 年 11 月）

• 解析器新增processingComplete事件（全部后处理完成后触发，带doclets属性）；parseComplete事件也新增doclets属性；
• 配置文件source.exclude支持相对路径（相对当前工作目录解析）；
• 带@default标签且默认值为对象字面量时，值以字符串存储并附defaultvaluetype: 'object'，便于模板做语法高亮；
• 内联{@link}可包含换行；JS 文件首行 hashbang（如#!/usr/bin/env node）会被忽略；let等 JS 1.8 关键字不再导致崩溃；
• 继承符号会指明其真正的定义祖先，而非直接父类；
• 默认模板默认生成美化打印的源码文件（可用templates.default.outputSourceFiles: false关闭），源码链接可跳转到符号定义行，@default对象值会显示在输出文件中。

八、3.1.0（2013 年 1 月）：@callback 标签与链接标签体系

3.1.0 引入至今常用的@callback标签，用于描述回调函数签名——先创建独立的 JSDoc 注释，再通过 namepath 引用：

/** * @class */ function MyClass() {} /** * Send a request. * * @param {MyClass~responseCb} cb - Called after a response is received. */ MyClass.prototype.sendRequest = function(cb) { // code }; /** * Callback for sending a request. * * @callback MyClass~responseCb * @param {?string} error - Information about the error. * @param {?string} response - Body of the response. */

内联链接标签也大幅改进：

• {@link}支持用空格分隔链接目标与链接文本；
• 配置项templates.cleverLinks（代码链接用等宽字体、URL 链接用普通文本）与templates.monospaceLinks（所有链接用等宽字体）——注意模板需相应更新才能生效；
• 新增{@linkplain}（强制普通文本链接）与{@linkcode}（强制等宽链接），二者总是覆盖conf.json中的设置。

此外，3.1.0 提供了-l/--lenient选项（遇到非致命错误继续运行）；模板的publish.js应把 publish 函数赋给exports.publish而非定义全局函数；模板辅助函数从默认模板中提取为templateHelper.js；新增-v/--version选项显示版本号；测试支持--nocolor禁用彩色输出。

3.1.0 还新增了一批新插件：

• partial：支持@partial标签，链接到包含 JSDoc 注释的外部文件；
• commentsOnly：删除文件中除 JSDoc 注释外的所有内容，可用于文档化"并非合法 JavaScript"的源码（如其他语言源码）；
• eventDumper：向控制台记录解析器事件信息；
• verbose：向控制台记录每个输入文件名。

九、3.0.x（2012）：初始发布与基础配置

• 3.0.0（2012 年 5 月）：初始发布，JSDoc 3 时代的开端；
• 3.0.1（2012 年 6 月）：conf.json支持source.include与source.exclude——前者指定"总是检查"的文件/目录，后者指定"永不检查"的文件/目录，二者优先级高于基于正则的source.includePattern/source.excludePattern；-t/--template支持绝对路径。

十、跨版本沉淀的实战清单

10.1 配置文件格式与默认值

综合各版本演进，JSDoc 配置体系已支持多种来源：JSON 配置文件（可含注释）、CommonJS/ES2015 模块导出的配置对象、.jsdocrc（JSON/YAML）、jsdoc.config.js以及package.json中的jsdoc字段。当前 packages/jsdoc-core/lib/config.js 中的defaultConfig提供了权威默认值：

仓库中的 packages/jsdoc/conf.json.EXAMPLE 给出了最小可运行示例：

{ "tags": { "allowUnknownTags": true }, "source": { "includePattern": ".+\\.js(doc|x)?$", "excludePattern": "(^|\\/|\\\\)_" }, "plugins": [], "templates": { "cleverLinks": false, "monospaceLinks": false, "default": { "outputSourceFiles": true } } }

10.2 CLI 参数速查

结合 packages/jsdoc-cli/lib/flags.js 中的定义，历次版本沉淀的主要命令行参数如下：

历史版本还记录过-r/--recurse（递归搜索输入目录）、-l/--lenient（非致命错误继续运行，后被--pedantic取代）、-p/--private等参数的引入与语义调整，使用前请以当前版本的--help输出为准。

10.3 值得沿用的配置与插件组合

• 把 JSDoc 当 linter 用：配合silent模板（3.4.1 引入）检查注释中的语法错误与无法识别的标签；
• 异步/生成器函数检测：3.5.0 起自动检测，无需手写@async/@generator；
• 接口与继承语义：@interface、@implements、@mixes、@inheritDoc、@override构成完整的面向对象文档能力；
• 插件全家桶：summarize（自动摘要）、underscore（自动私有化）、overloadHelper（重载链接）、eventDumper（事件日志）、commentsOnly（非 JS 源码文档化）可按需加载。

十一、升级与迁移建议：从 CHANGES.md 提炼的注意事项

1. 先确认 Node.js 版本：4.0.0 要求 Node.js 12+；而当前仓库根目录 package.json 的engines字段要求 Node.js^22.13.0 || >=23.0.0，说明项目的开发环境已随生态继续前进，升级前应核对自身运行环境；
2. 模板与插件检查 TaffyDB 引用：若模板/插件仍引用taffydb，按本文 2.2 节迁移到@jsdoc/salty；
3. 关注新标签支持度：3.5.0 起新增的@async、@generator、@hideconstructor、@package、@yields等标签，第三方模板可能不支持，升级模板前需确认；
4. 配置项兼容性：--lenient已被--pedantic取代；staticFiles.paths已弃用，改用staticFiles.include；jsVersion配置在 3.2.0 已移除；
5. 把本文件作为回归对照：CHANGES.md 中每个版本的 Bug 修复列表，都可作为升级后回归测试的检查清单。

十二、延伸阅读：仓库内的相关资源

• CHANGES.md：本文依据的完整变更历史（含各版本对应的 GitHub issue 引用）；
• packages/jsdoc-core/lib/config.js：配置默认值与加载逻辑（JSON/YAML/JS 配置、package.json的jsdoc字段）；
• packages/jsdoc-cli/lib/flags.js：全部命令行参数定义；
• packages/jsdoc/conf.json.EXAMPLE：最小配置示例；
• packages/jsdoc-salty/README.md：TaffyDB 替换的动机、迁移步骤与 Salty 支持的功能子集；
• packages/jsdoc-plugins：summarize、underscore、partial、commentsOnly、eventDumper、overloadHelper 等官方插件；
• packages/jsdoc/test/fixtures 与 packages/jsdoc/test/specs/tags：与各标签、各版本新特性对应的测试夹具与规格。

• 开发工具
• 文档