JSDoc入门使用指南 -- 手摸手教你用JSDoc（超好用的js文档生成工具）

关注

原创最新推荐文章于 2026-06-28 07:58:48 发布 1.6w 阅读 AI 写同款· GEO 优化 ›

使用JSDoc生成漂亮的文档 JSDoc是一个用于 JavaScript 的API文档生成器，类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描您的源代码并为您生成一个 HTML 文档网站。阅读详情

安装

准备

Node.js 8.15.0+

通过npm安装

全局安装：npm install -g jsdoc
- 若出现权限问题，如 EACCES报错，最佳实践为用node版本管理器（nvm等）重装npm
本地安装：npm install --save-dev jsdoc
- 命令行工具目录：./node_modules/.bin/jsdoc

鉴于JSDoc的文档生成工具的本质，建议使用 --save-dev的本地安装模式

使用

书写JSDoc标签

jsdoc的使用方式非常简单，在编写代码时根据jsdoc的规则在块级注释中添加相应标签即可：

/**
* 功能：将时间戳格式化为指定格式的字符串
* @param {Number} milliSec - 要转换的时间，可以为秒、毫秒、微秒、或Date类型
* @param {String} [formatStr] - 目标格式字符串 可选 默认为：'yyyy-MM-dd hh:mm:ss'
* @returns {String} - 根据目标时间格式，将时间数值（或Date）转换成的时间字符串
*/
function formatTime(milliSec, formatStr = DEFAULT_FORMAT_STR) {
    // code
}

其中 @param、@returns即为jsdoc的常用标签，具体标签及用法可通过传送门到官网或中文文档查看

生成JSDoc文档

代码编写完成后，即可通过命令行生成jsdoc文档

基本用法

/path/to/jsdoc yourSourceCodeFile.js

// 全局安装
jsdoc yourSourceCodeFile.js
// 本地安装
./node_modules/.bin/jsdoc yourSourceCodeFile.js

jsdoc提供了大量命令行选项满足使用需求，这里列出一些常用选项：
- -c 或 --configure：指定JSDoc配置文件的路径。默认为安装JSDoc目录下的conf.json或conf.json.EXAMPLE
- -d 或 --destination：指定输出生成文档的文件夹路径。JSDoc内置的Haruki模板，使用console 将数据转储到控制台。默认为 ./out
- -r 或 --recurse：扫描源文件和导览时递归到子目录
- -R 或 --readme：用来包含到生成文档的README.md文件。默认为在源路径中找到的第一个README.md文件
- -t 或 --template：用于生成输出文档的模板的路径。默认为templates/default，JSDoc内置的默认模板
- -v 或 --version：显示jsdoc版本号
更多选项可通过 -h 或 --help选项查看，或通过传送门到官网或中文文档查看
每次都输入一长串命令行太过繁琐，可在配置文件中的opts参数中指定这些选项

用conf.json配置JSDoc

{
    "tags": {
        "allowUnknownTags": true
    },
    "source": {
        "include": ["./src"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_",
        "exclude": ["./src/index.js"]
    },
    "plugins": [],
    "opts": {
        "template": "./doc/templates/docdash",
        "encoding": "utf8",
        "destination": "./doc/doc-page/",
        "recurse": true
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false,
        "default": {
            "outputSourceFiles": true
        }
    }
}

其中：

tags：控制那些标签允许被使用和解析
source：指定要用jsdoc生成文档的文件
- include：路径组成的数组，jsdoc将为它们生成文档
- exclude：路径组成的数组，jsdoc应忽略的路径
- includePattern：正则表达式字符串，只有文件名匹配的文件才会被jsdoc扫描。默认为 .+.js(doc)?$ 即 .js 或 .jsdoc 结尾的文件才会被扫描
- excludePattern：正则表达式字符串，文件名匹配的文件将被jsdoc忽略。默认为 (^|\\/|\\\\)_ 即下划线开头的文件或下划线开头的目录下的所有文件
- 结合起来，jsdoc的执行过程是：
  - 扫描include中的所有文件（若使用了 -r 命令将在子目录中递归搜索）
  - 在上一步搜索到的文件中，使用includePattern匹配文件名，只保留相匹配的文件
  - 在上一步匹配到的文件中，使用excludePattern匹配文件名，剔除相匹配的文件
  - 在上一部生于的文件中，如果文件路径在exclude中，该文件将被剔除
  - 最终剩下的文件将通过jsdoc进行解析
opts：配置命令行选项，与上面讲的选项相对应
plugins：要启用的插件，在数组中添加插件相对于JSDoc文件夹的路径即可
templates：配置jsdoc所生成的文档的模板

配置完成后使用 ./node_modules/.bin/jsdoc -c path/to/yourconf.json 生成jsdoc文档即可

其他

改变模板

如果你觉得默认模板不好看，可以通过GitHub下载喜欢的模板，例如：
- jaguarjs-jsdoc
- DocStrap (example)
- jsdoc3Template (example)
- minami
- docdash (example)
- tui-jsdoc-template (example)
- better-docs (example)
将下载好的模板文件夹放入 ./node_modules/jsdoc/templates/ 中
变更命令行选项中的 template/-t 选项为新的模板文件夹
重新生成jsdoc文档即可

添加主页

主页中可以添加对项目的描述、使用说明、注意事项等等。稳妥起见，我们不采用jsdoc自动搜索的方式

在合适的目录下新建md文件，如 ./doc/HOMEPAGE.md
变更命令行选项中的 readme/-r 为新建的文件 ./doc/HOMEPAGE.md
重新生成jsdoc文档即可

通过npm命令生成文档

如果你仍不满足使用conf.json配置后的命令行简洁程度，可以看过来

打开项目的package.json
在scripts中添加一行 "jsdoc": "node_modules/.bin/jsdoc -r -c doc/conf.json -R doc/HOMEPAGE.md"
执行 npm run jsdoc 即可

gulp中的JSDoc插件：gulp-jsdoc3

安装：npm install --save-dev gulp-jsdoc3
使用：

var jsdoc = require('gulp-jsdoc3');

gulp.task('doc', function (cb) {
    // jsdoc的配置文件
    var config = require('./doc/conf.json');
    gulp.src(['README.md', './src/**/*.js'], {read: false}).pipe(jsdoc(config, cb));
});