引入better-docs的@component插件后Vue版本不匹配报错

在Vue3项目中尝试添加JSDoc注释，引入better-docs的@component插件后出现版本不匹配错误：

Vue packages version mismatch:
- vue@3.3.4 (C:\Users\patre\OneDrive\Pulpit\Work\instore\app\node_modules\vue\index.js)
- vue-template-compiler@2.7.14 (C:\Users\patre\OneDrive\Pulpit\Work\instore\app\node_modules\vue-template-compiler\package.json)

This may cause things to work incorrectly. Make sure to use the same version for both.
If you are using vue-loader@>=10.0, simply update vue-template-compiler.
If you are using vue-loader@<10.0 or vueify, re-installing vue-loader/vueify should bump vue-template-compiler to the latest.

需求仅为提取.vue文件中<script>部分的JSDoc注释，不需要解析Vue组件语法，尝试过安装vue-loader、vue-template-compiler及重装依赖均无效。

问题原因 #

better-docs的component插件是为Vue2设计的，它内部依赖Vue2的vue-template-compiler包，而Vue3项目使用的是@vue/compiler-sfc，两者生态不兼容，导致强制安装的Vue2版本依赖与项目中的Vue3冲突。

解决方案 #

1. 调整依赖包

卸载无用的vue-template-compiler，安装支持Vue3的jsdoc-vue-plugin（仅用于提取.vue文件中script部分的JSDoc）：

npm uninstall vue-template-compiler
npm install jsdoc-vue-plugin --save-dev

2. 修改jsdoc.json配置

移除better-docs/component插件，替换为jsdoc-vue-plugin，同时修正输出路径配置（需为文件夹而非文件）：

{
    "plugins": [
        "jsdoc-vue-plugin",
        "better-docs" // 若需要better-docs的模板样式则保留，无需可删除
    ],
    "source": {
        "includePattern": "\\.(vue|js)$",
        "include": [
            "./src/App.vue"
        ]
    },
    "sourceType": "module",
    "recurseDepth": 10,
    "opts": {
        "destination": "./docs", // 修正为文件夹路径
        "recurse": true
    },
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": [
            "jsdoc",
            "closure"
        ]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

3. 生成文档

运行JSDoc命令即可正常生成包含.vue文件JSDoc注释的文档，且不会再出现版本冲突错误。

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