如何让Vite忽略Vue单文件组件中的<docs>代码块？

针对你遇到的Vite解析代码块导致语法错误、vite-plugin-vuedoc无法安装的问题，提供以下3种可行解决办法：

方案1：自定义Vite插件忽略块 #

自己编写一个极简Vite插件，在编译阶段移除.vue文件中的块，避免Vite将其当作JS代码解析。

在vite.config.js中添加以下配置：

export default {
  plugins: [
    {
      name: 'ignore-docs-block',
      transform(code, id) {
        if (id.endsWith('.vue')) {
          // 匹配并移除所有<docs>标签及内部内容
          return code.replace(/<docs>[\s\S]*?<\/docs>/g, '')
        }
      }
    }
  ]
}

该插件不会影响vue-docgen-cli对块的解析，因为vue-docgen-cli是直接读取文件内容，不受Vite编译流程影响。

方案2：用JS注释包裹块内容 #

在块内部用合法的JS注释包裹文档内容，让Vite将其识别为注释跳过解析，同时不影响vue-docgen-cli提取文档。

示例写法：

<docs>
/*
组件文档说明：
- is 属性：用于控制组件的显示状态，布尔类型，默认值为false
- 使用示例：<MyComponent :is="true" />
*/
</docs>

如果文档内容包含*/这类会中断注释的字符，可以改用模板字符串包裹：

<docs>
`
组件文档说明：
- is 属性：用于控制组件的显示状态，支持*/特殊字符
`
</docs>

方案3：改用vue-docgen-cli支持的注释式文档 #

放弃块，改用vue-docgen-cli兼容的JS注释标记，直接在script标签内编写文档，Vite会将其当作正常注释处理，不会报错。

示例写法：

<script setup>
/**
 * @docs
 * 组件名称：MyComponent
 * 属性说明：
 * - is: 控制组件显示状态的布尔值，默认false
 * 使用示例：
 * ```vue
 * <MyComponent :is="visible" />
 * ```
 */
const props = defineProps({
  is: {
    type: Boolean,
    default: false
  }
})
</script>

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