Vite构建Vue3组件库 script setup组件无法被IDE识别问题

开发基于Vue3的npm组件库，通过package.json引入到其他项目使用时出现异常：

• 使用<script setup>语法编写的组件无法被IDE（WebStorm）识别
• 使用Options API（非script setup语法）编写的组件可被正常识别
  两类组件实际运行功能均正常，典型现象为test-input组件无法被IDE识别，test-button组件可正常识别。

vite.config.ts 构建配置 #

build: {
  cssCodeSplit: false,
  lib: {
    entry: './src/TestDesignSystemPlugin.ts',
    formats: ['es', 'cjs'],
    name: 'TestDesignSystemPlugin',
    fileName: (format) => (format === 'es' ? 'index.js' : 'index.cjs'),
  },
  rollupOptions: {
    external: ['vue'],
    output: {
      globals: {
        vue: 'Vue',
      },
    },
  },
},

TestButton.vue（Options API实现） #

<template>
  <button>
    <slot />
  </button>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  name: 'TestButton',
})
</script>

TestInput.vue（<script setup>实现） #

<template>
  <input v-model="model" />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const model = ref('')
</script>

组件库入口 TestDesignSystemPlugin.ts（全局注册逻辑） #

import type { App } from 'vue'
import {
  TestButton,
  TestInput,
} from '@/components'

export default {
  install: (app: App) => {
    app.component('TestButton', TestButton)
    app.component('TestInput', TestInput)
  },
}

经初步验证，问题并非出在IDE侧，而是组件库构建环节存在异常。查看构建生成的index.js产物时，发现<script setup>编写的组件与Options API组件的注册逻辑存在明显差异，相关代码片段如下：

var TestDesignSystemPlugin = {
  install: (app) => {
    app.component("TestButton", TestButton);
    app.component("TestButtonSocial", TestButtonSocial);
    app.component("TestInput", _sfc_main$8);
  }
};

• Options API写法的组件手动声明了name属性，构建过程中组件变量名、组件名被完整保留，IDE可以通过注册时的组件对象读取到有效元信息，所以可以正常识别。
• <script setup>是语法糖，默认不会自动注入组件name属性，Vite+Rollup构建时会给这类匿名SFC组件生成_sfc_main$数字格式的混淆变量名，原始组件名信息丢失，IDE无法将注册的组件和标签名做映射，所以出现识别失败的问题。
• 组件库未生成全局组件对应的类型声明文件，IDE缺少组件类型、标签名的映射依据，也会加剧识别异常。

• 给所有<script setup>组件显式声明组件名，二选一即可：
  • 方案1：在SFC文件中新增普通script块声明name，以TestInput.vue为例：

    <script lang="ts">
    export default { name: 'TestInput' }
    </script>
    

  • 方案2：引入vite-plugin-vue-setup-extend插件，配置后可直接在script setup标签上声明name，无需额外写script块：

    <script setup lang="ts" name="TestInput">
    import { ref } from 'vue'
    const model = ref('')
    </script>
    

• 调整构建配置，避免组件变量名被混淆，在vite.config.ts的rollupOptions.output中添加配置：

  rollupOptions: {
    external: ['vue'],
    output: {
      globals: {
        vue: 'Vue',
      },
      minifyInternalExports: false, // 保留内部导出变量名，避免被替换为_sfc_main$xx格式
    },
  }
  

• 新增全局组件类型声明文件，在package.json的types字段指向该文件，文件内容示例：

  import type TestButton from './src/components/TestButton.vue'
  import type TestInput from './src/components/TestInput.vue'
  
  declare module 'vue' {
    export interface GlobalComponents {
      TestButton: typeof TestButton
      TestInput: typeof TestInput
    }
  }
  
  export {}
  

完成以上调整后重新构建发布，IDE即可正常识别所有全局注册的组件，标签提示、属性校验功能都会恢复正常。

内容的提问来源于stack exchange，提问作者Diego Armando Maradona