Vue3中JSDoc无法正常生成文档，生成的index.html为空

问题描述 #

开发了一个简单的Vue3应用，尝试用JSDoc生成代码文档，但生成的index.html内容为空，执行生成命令时未抛出任何错误。以下是相关文件内容：

jsdoc.conf.json #

{
  "source": {
    "include": ["src/views/"],
    "includePattern": "\.(vue|js)$",
    "excludePattern": "(node_modules/|docs)"
  },
  "opts": {
    "recurse": true,
    "destination": "./docs"
  },
  "plugins": ["plugins/markdown", "node_modules/jsdoc-vuejs"],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false
  }
}

生成的index.html #

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>JSDoc: Home</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>

<body>

<div id="main">

    <h1 class="page-title">Home</h1>




    <h3> </h3>







</div>

<nav>
    <h2><a href="index.html">Home</a></h2>
</nav>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.3</a> on Sat May 11 2024 13:50:02 GMT+0200 (hora de verano de Europa central)
</footer>

<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>

排查与解决步骤 #

1. 修复正则转义问题 #

includePattern中的正则未正确转义，JSON里的反斜杠需要双重转义，将"\.(vue|js)$"修改为"\\.(vue|js)$"，否则JSDoc无法匹配到目标文件。

2. 规范Vue文件的JSDoc注释 #

jsdoc-vuejs插件需要Vue文件中的注释符合JSDoc规范，示例如下：

<template>
  <div>{{ message }}</div>
</template>

<script>
/**
 * 首页组件
 * @module views/Home
 */
export default {
  name: 'HomeView',
  data() {
    return {
      /** 欢迎消息 */
      message: 'Hello Vue3!'
    }
  },
  /**
   * 初始化消息方法
   * @returns {void}
   */
  mounted() {
    this.initMessage()
  },
  methods: {
    initMessage() {
      this.message = 'Welcome to JSDoc!'
    }
  }
}
</script>

确保组件、方法、属性都添加了对应注释，无注释的内容不会被生成到文档中。

3. 验证插件安装与配置 #

执行npm install jsdoc-vuejs --save-dev确认插件已正确安装，可尝试将配置中的插件路径简化为"jsdoc-vuejs"（局部安装时通常可识别）。

4. 测试文件匹配有效性 #

暂时将include改为指定单个Vue文件（如["src/views/HomeView.vue"]），运行生成命令测试是否能识别文件并生成内容，以此排查路径或正则的问题。

5. 查看调试日志 #

运行生成命令时添加--verbose参数（如jsdoc -c jsdoc.conf.json --verbose），查看日志中是否有文件被扫描到，以及是否存在隐藏的警告信息。

内容的提问来源于stack exchange，提问作者Fargex12