Vue2项目迁移至Vite后，<docs>标签内Markdown触发JSX语法报错

方案1：自定义Vite插件移除标签内容 #

Vite的import-analysis插件会扫描所有代码内容，把里的JSX代码误判成项目实际使用的JS语法。我们可以写个简单插件，在代码分析前先把标签及其内部内容清掉。

在vite.config.js里加这段代码：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue2'

export default defineConfig({
  plugins: [
    vue(),
    {
      name: 'strip-docs-tags',
      transform(code, id) {
        // 只处理.vue文件
        if (id.endsWith('.vue')) {
          // 匹配并移除所有<docs>标签块（包括带属性的情况）
          return code.replace(/<docs[^>]*>[\s\S]*?<\/docs>/g, '')
        }
        return code
      }
    }
  ]
})

方案2：让Vue2插件忽略自定义块 #

@vitejs/plugin-vue2支持配置自定义块的处理规则，直接把标记为不需要编译的块就行：

修改vite.config.js：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue2'

export default defineConfig({
  plugins: [
    vue({
      customBlocks: [
        // 告诉插件跳过<docs>块的解析，不处理内部内容
        { name: 'docs', transform: () => '' }
      ]
    })
  ]
})

验证与调整 #

• 配置完成后重启Vite开发服务器，之前的import-analysis报错应该会消失
• 两种方案二选一即可，方案2更贴合Vue插件的原生处理逻辑，推荐优先使用

内容的提问来源于stack exchange，提问作者Demiro-FE-Architect