JSDoc 配置文件 #

配置文件概述 #

JSDoc 使用 JSON 格式的配置文件来控制文档生成的行为。默认配置文件名为 jsdoc.json 或 conf.json。

配置文件位置 #

text 
project/
├── jsdoc.json          # 默认配置文件
├── package.json        # 可在 scripts 中引用
└── src/
    └── ...

基本结构 #

javascript 
// jsdoc.json
{
  "source": {
    "include": ["src/"],
    "exclude": ["src/tests/"],
    "includePattern": ".+\\.js(doc)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "plugins": [],
  "opts": {
    "destination": "./docs/",
    "recurse": true
  },
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true
  }
}

使用配置文件 #

命令行指定 #

bash 
# 使用默认配置文件
jsdoc src/

# 指定配置文件
jsdoc -c jsdoc.json

# 指定配置文件和源码目录
jsdoc -c jsdoc.json src/

# 使用 package.json 中的配置
jsdoc -c package.json

package.json 配置 #

javascript 
// package.json
{
  "name": "my-project",
  "scripts": {
    "docs": "jsdoc -c jsdoc.json"
  },
  "jsdoc": {
    "source": {
      "include": ["src/"]
    },
    "opts": {
      "destination": "./docs/"
    }
  }
}

源码配置 #

source.include 包含目录 #

指定要解析的目录或文件：

javascript 
{
  "source": {
    "include": [
      "src/",
      "lib/utils.js"
    ]
  }
}

source.exclude 排除目录 #

排除不需要解析的目录或文件：

javascript 
{
  "source": {
    "include": ["src/"],
    "exclude": [
      "src/tests/",
      "src/mocks/",
      "node_modules/"
    ]
  }
}

source.includePattern 包含模式 #

使用正则表达式匹配要包含的文件：

javascript 
{
  "source": {
    "include": ["src/"],
    "includePattern": ".+\\.js(doc)?$"
  }
}

source.excludePattern 排除模式 #

使用正则表达式匹配要排除的文件：

javascript 
{
  "source": {
    "include": ["src/"],
    "excludePattern": "(^|\\/|\\\\)_"
  }
}

完整源码配置示例 #

javascript 
{
  "source": {
    "include": [
      "src/",
      "lib/"
    ],
    "exclude": [
      "src/tests/",
      "src/mocks/",
      "node_modules/"
    ],
    "includePattern": ".+\\.(js|jsx|ts|tsx|vue)$",
    "excludePattern": "(^|\\/|\\\\)(_|\\.|-)"
  }
}

输出配置 #

opts.destination 输出目录 #

指定文档输出目录：

javascript 
{
  "opts": {
    "destination": "./docs/"
  }
}

opts.recurse 递归处理 #

递归处理子目录：

javascript 
{
  "opts": {
    "recurse": true
  }
}

opts.template 模板路径 #

指定使用的模板：

javascript 
{
  "opts": {
    "template": "node_modules/docdash/"
  }
}

opts.encoding 文件编码 #

指定源文件编码：

javascript 
{
  "opts": {
    "encoding": "utf8"
  }
}

opts.tutorials 教程目录 #

指定教程目录：

javascript 
{
  "opts": {
    "tutorials": "./tutorials/"
  }
}

完整输出配置示例 #

javascript 
{
  "opts": {
    "destination": "./docs/",
    "recurse": true,
    "template": "node_modules/docdash/",
    "encoding": "utf8",
    "tutorials": "./tutorials/",
    "readme": "./README.md",
    "package": "./package.json"
  }
}

插件配置 #

plugins 插件列表 #

启用插件：

javascript 
{
  "plugins": [
    "plugins/markdown",
    "plugins/summare"
  ]
}

内置插件 #

javascript 
{
  "plugins": [
    "plugins/markdown",      // Markdown 支持
    "plugins/summare",       // 摘要生成
    "plugins/sourcetag",     // 源码标签
    "plugins/testdoc",       // 测试文档
    "plugins/overloadHelper" // 重载辅助
  ]
}

第三方插件 #

javascript 
{
  "plugins": [
    "node_modules/better-docs/category",
    "node_modules/jsdoc-plugin-typescript"
  ]
}

插件配置选项 #

javascript 
{
  "plugins": [
    "plugins/markdown"
  ],
  "markdown": {
    "hardwrap": true,
    "idInHeadings": true
  }
}

模板配置 #

templates 模板选项 #

配置模板行为：

javascript 
{
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true,
    "default": {
      "outputSourceFiles": true,
      "includeDate": true
    }
  }
}

default 模板配置 #

javascript 
{
  "templates": {
    "default": {
      "layoutFile": "./layout.tmpl",
      "staticFiles": {
        "include": [
          "./static/"
        ]
      },
      "outputSourceFiles": true,
      "includeDate": true,
      "navType": "vertical",
      "theme": "spacelab",
      "linenums": true,
      "dateFormat": "YYYY-MM-DD"
    }
  }
}

docdash 模板配置 #

javascript 
{
  "opts": {
    "template": "node_modules/docdash"
  },
  "docdash": {
    "static": true,
    "sort": true,
    "sectionOrder": [
      "Classes",
      "Modules",
      "Externals",
      "Events",
      "Namespaces",
      "Mixins",
      "Tutorials",
      "Interfaces"
    ],
    "disqus": "",
    "openGraph": {
      "title": "My API Documentation",
      "type": "website"
    },
    "meta": {
      "title": "My API Documentation",
      "description": "API documentation for my project",
      "keyword": "api, documentation, javascript"
    },
    "search": true,
    "collapse": true,
    "wrap": true,
    "typedefs": true,
    "navLevel": 2,
    "private": false,
    "removeQuotes": "none",
    "scripts": [],
    "menu": {
      "Project Homepage": {
        "href": "https://github.com/user/repo",
        "target": "_blank",
        "class": "menu-item"
      }
    }
  }
}

better-docs 模板配置 #

javascript 
{
  "opts": {
    "template": "node_modules/better-docs"
  },
  "better-docs": {
    "name": "My Project",
    "logo": "./images/logo.png",
    "navigation": [
      {
        "label": "GitHub",
        "href": "https://github.com/user/repo"
      }
    ],
    "css": "./custom.css"
  }
}

类型定义配置 #

sourceType 源码类型 #

指定源码类型：

javascript 
{
  "sourceType": "module"  // "script" | "module"
}

类型解析配置 #

javascript 
{
  "typescript": {
    "module": "commonjs",
    "target": "es2015",
    "lib": ["es2015", "dom"]
  }
}

访问控制配置 #

access 访问级别 #

控制生成的文档访问级别：

javascript 
{
  "opts": {
    "access": "public"  // "all" | "public" | "protected" | "private"
  }
}

多个访问级别 #

javascript 
{
  "opts": {
    "access": ["public", "protected"]
  }
}

标记配置 #

tags 标签配置 #

自定义标签行为：

javascript 
{
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc", "closure"]
  }
}

禁用未知标签警告 #

javascript 
{
  "tags": {
    "allowUnknownTags": [
      "category",
      "security",
      "todo"
    ]
  }
}

完整配置示例 #

基础项目配置 #

javascript 
{
  "source": {
    "include": ["src/"],
    "exclude": ["node_modules/"],
    "includePattern": ".+\\.js(doc)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "plugins": ["plugins/markdown"],
  "opts": {
    "destination": "./docs/",
    "recurse": true,
    "readme": "./README.md"
  },
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true
  }
}

企业级项目配置 #

javascript 
{
  "source": {
    "include": [
      "src/",
      "lib/"
    ],
    "exclude": [
      "node_modules/",
      "dist/",
      "coverage/",
      "**/*.test.js",
      "**/*.spec.js"
    ],
    "includePattern": ".+\\.(js|jsx|ts|tsx)$",
    "excludePattern": "(^|\\/|\\\\)(_|\\.|-)"
  },
  "plugins": [
    "plugins/markdown",
    "plugins/summare",
    "node_modules/better-docs/category"
  ],
  "opts": {
    "destination": "./docs/",
    "recurse": true,
    "template": "node_modules/better-docs",
    "tutorials": "./tutorials/",
    "readme": "./README.md",
    "package": "./package.json",
    "encoding": "utf8"
  },
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true,
    "default": {
      "outputSourceFiles": true,
      "includeDate": true,
      "linenums": true
    }
  },
  "better-docs": {
    "name": "My Project API",
    "logo": "./docs/images/logo.png",
    "navigation": [
      {
        "label": "GitHub",
        "href": "https://github.com/company/project"
      },
      {
        "label": "NPM",
        "href": "https://www.npmjs.com/package/my-project"
      }
    ],
    "css": "./docs/custom.css"
  },
  "markdown": {
    "hardwrap": true,
    "idInHeadings": true
  }
}

TypeScript 项目配置 #

javascript 
{
  "source": {
    "include": ["src/"],
    "exclude": [
      "node_modules/",
      "dist/",
      "**/*.test.ts"
    ],
    "includePattern": ".+\\.ts$"
  },
  "plugins": [
    "plugins/markdown",
    "node_modules/jsdoc-plugin-typescript"
  ],
  "opts": {
    "destination": "./docs/",
    "recurse": true,
    "template": "node_modules/docdash"
  },
  "typescript": {
    "module": "commonjs",
    "target": "es2018",
    "lib": ["es2018", "dom"]
  },
  "docdash": {
    "static": true,
    "sort": true,
    "search": true
  }
}

库开发配置 #

javascript 
{
  "source": {
    "include": ["src/", "index.js"],
    "exclude": ["src/__tests__/"]
  },
  "plugins": ["plugins/markdown"],
  "opts": {
    "destination": "./docs/",
    "recurse": true,
    "template": "node_modules/docdash",
    "readme": "./README.md",
    "package": "./package.json"
  },
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true
  },
  "docdash": {
    "static": true,
    "sort": true,
    "meta": {
      "title": "My Library",
      "description": "A JavaScript library for ...",
      "keyword": "javascript, library, api"
    },
    "menu": {
      "Homepage": {
        "href": "https://mylib.dev"
      },
      "GitHub": {
        "href": "https://github.com/user/mylib"
      },
      "NPM": {
        "href": "https://www.npmjs.com/package/mylib"
      }
    }
  }
}

命令行选项 #

常用命令行选项 #

bash 
# 指定配置文件
jsdoc -c jsdoc.json

# 指定输出目录
jsdoc -d ./docs/

# 指定模板
jsdoc -t node_modules/docdash

# 递归处理
jsdoc -r src/

# 指定 README
jsdoc -R README.md

# 指定 package.json
jsdoc -P package.json

# 指定教程目录
jsdoc -u ./tutorials/

# 显示帮助
jsdoc --help

# 显示版本
jsdoc --version

完整命令行示例 #

bash 
jsdoc \
  -c jsdoc.json \
  -d ./docs/ \
  -t node_modules/docdash \
  -r \
  -R README.md \
  -P package.json \
  -u ./tutorials \
  src/

环境变量 #

JSDOC_CONFIG #

指定默认配置文件：

bash 
export JSDOC_CONFIG=/path/to/jsdoc.json
jsdoc src/

JSDOC_TEMPLATE #

指定默认模板：

bash 
export JSDOC_TEMPLATE=node_modules/docdash
jsdoc src/

配置验证 #

检查配置文件 #

bash 
# 使用 Node.js 验证 JSON 格式
node -e "console.log(JSON.parse(require('fs').readFileSync('jsdoc.json')))"

调试模式 #

javascript 
{
  "opts": {
    "debug": true,
    "verbose": true
  }
}

配置最佳实践 #

分离环境配置 #

javascript 
// jsdoc.base.json - 基础配置
{
  "plugins": ["plugins/markdown"],
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true
  }
}

// jsdoc.dev.json - 开发配置
{
  "extends": "./jsdoc.base.json",
  "opts": {
    "destination": "./docs-dev/",
    "debug": true
  }
}

// jsdoc.prod.json - 生产配置
{
  "extends": "./jsdoc.base.json",
  "opts": {
    "destination": "./docs/",
    "private": false
  }
}

使用脚本管理 #

javascript 
// package.json
{
  "scripts": {
    "docs": "jsdoc -c jsdoc.json",
    "docs:dev": "jsdoc -c jsdoc.dev.json",
    "docs:watch": "onchange 'src/**/*.js' -- npm run docs",
    "docs:serve": "serve docs/"
  }
}

下一步 #

现在你已经掌握了 JSDoc 配置文件，接下来学习 插件扩展 了解如何扩展 JSDoc 功能！

最后更新：2026-03-29