JSDoc 这件工具本身不复杂：装上、写个配置、跑一条命令，文档就出来了。出问题的地方几乎都在conf.json—— 参数名多、层级深，抄错了不报错，只是生成出来的东西不对。
下面按实际顺序走一遍。环境是 node v10.17.0 + jsdoc v3.6.3，现在的新版本命令是一样的。
1. 装
全局装最新版：
npm install jsdoc -g要锁版本（比如跟着团队统一到 v3.6.3）：
npm install jsdoc@3.6.3 -g2. 写配置：先用默认模板
在项目根目录建一个conf.json：
{ "tags": { "allowUnknownTags": true }, "recurseDepth": 10, "source": { "include": ["./encmap/"], "includePattern": ".+\\.js(doc)?$", "excludePattern": "(^|\\/|\\\\)_" }, "templates": { "cleverLinks": true, "monospaceLinks": true, "default": { "outputSourceFiles": false }, "applicationName": "demo", "openGraph": {}, "meta": {}, "recurse": true } }几个关键项：
| 字段 | 作用 |
|---|---|
source.include | 要扫的目录，数组，可写多个 |
source.includePattern | 扫哪些文件，默认.+\\.js(doc)?$（只认.js和.jsdoc） |
source.excludePattern | 排除规则，默认排除下划线开头的文件 |
recurseDepth | 目录递归深度 |
tags.allowUnknownTags | 遇到不认识的标签是报错还是忽略，建议true |
3. 生成
jsdoc -c conf.json -r-c指定配置，-r递归子目录。默认模板会给源文件生成适合打印的文档 —— 结构完整、能看，但样式比较朴素。
4. 想要好看：换 docdash 模板
默认模板最大的问题是导航和搜索都比较弱，项目一大就得靠 Ctrl+F。换成docdash会舒服很多：
npm install docdash然后改conf.json。注意换模板后opts块是新增的，模板路径、输出目录、编码都在这里：
{ "tags": { "allowUnknownTags": true }, "source": { "include": ["encmap", "encmap/README.md"], "includePattern": "\\.js$", "excludePattern": "(node_modules/|docs)" }, "plugins": ["plugins/markdown"], "opts": { "template": "node_modules/docdash", "encoding": "utf8", "destination": "docs/", "recurse": true, "verbose": true }, "templates": { "cleverLinks": false, "monospaceLinks": false, "default": { "outputSourceFiles": false } }, "docdash": { "static": true, "sort": true, "search": true, "menu": { "Demo": { "href": "http://localhost:8080/demo/", "target": "_blank", "class": "menu-item", "id": "demo_link" } } } }两处配置的差别值得记一下：
source.include变成了具体文件（encmap目录 + 里面的README.md），说明它既吃目录也吃单个文件；excludePattern换成排除node_modules/和生成目录docs/，否则递归会把依赖和上次的产物一起扫进来；- 多了
plugins：plugins/markdown让你能在注释里直接写 Markdown； docdash块是模板专属配置：static静态资源、sort排序、search搜索框，menu可以往顶部导航塞自定义链接。
模板的完整可选项在 docdash 官方仓库 有列表，常用的就上面这几个。
5. 加个 npm script，省得每次敲长命令
在package.json里加：
"scripts": { "generate-docs": "node_modules/.bin/jsdoc -c jsdoc.json" }之后生成文档就变成：
npm run generate-docs小结
- 装 + 配 + 跑，核心就一条
jsdoc -c conf.json -r； - 默认模板够用，要导航和搜索就上 docdash；
- 配置里最容易踩的是
includePattern/excludePattern这两个正则 —— 写宽了会把node_modules扫进来，写窄了会漏文件，改完记得看一眼生成结果里文章数量对不对。
