Vue3搭配jsdoc-vuejs 4生成组件文档为空的问题如何解决？

问题原因 #

你目前的配置存在3个核心错误，共同导致生成空文档：

• 配置文件中includePattern格式错误：用字符串形式书写正则时，转义符\会被JS自身转义，实际生效的匹配规则为.(vue|js)$，无法正确识别.vue、.js后缀的文件，插件未解析任何组件内容
• 命令行参数与配置文件冲突：package.json的docs脚本指定了-d docs参数，优先级高于.jsdoc.js中配置的destination: 'docs-tui'，会造成输出路径混淆
• 缺少ES模块解析配置：未指定sourceType: 'module'，无法正确识别Vue组件的ES模块导出语法

修正方案 #

1. 更新.jsdoc.js配置文件 #

修改为以下内容：

module.exports = {
    plugins: [
        "jsdoc-vuejs"
    ],
    source: {
      include: [
        'src/'
      ],
      // 直接使用正则对象，避免转义问题
      includePattern: /\.(vue|js)$/,
      // 新增ES模块解析配置
      sourceType: 'module'
    },
    opts: {
      encoding: 'utf8',
      // 统一输出路径为docs
      destination: './docs',
      template: './node_modules/tui-jsdoc-template'
    }
};

2. 更新package.json的docs脚本 #

删除冲突的输出路径参数：

{
  "scripts": {
    // 保留其他原有脚本不变
    "docs": "rm -rf docs && jsdoc -c .jsdoc.js"
  }
}

3. 验证生成 #

执行npm run docs即可正常生成组件文档，你提供的HelloWorld组件注释无需修改即可被正确识别。

内容的提问来源于stack exchange，提问作者Radosław Andraszyk