Vue SFC script setup语法组件级注释位置及VSCode智能感知配置

一、组件级注释的正确放置位置 #

根据Vue版本不同，有两种可行实现方式：

1. Vue 3.3+（推荐）：用defineOptions宏配合JSDoc注释 #

在<script setup>最顶部，给defineOptions添加JSDoc注释，同时定义组件名称：

<script setup lang="ts">
/**
 * 展示歌曲演唱者的信息组件
 * @remarks 支持显示头像、姓名、简介等信息，可自定义是否显示关注按钮
 * @example
 * ```vue
 * <ArtistInfo :artist="currentArtist" showFollowBtn />
 * ```
 */
defineOptions({
  name: 'ArtistInfo'
})

// 组件内部逻辑
const props = defineProps<{
  artist: { id: number; name: string; avatar: string; bio?: string }
  showFollowBtn?: boolean
}>()
</script>

2. Vue 3.3以下：新增单独<script>块导出组件元信息 #

在<script setup>之外添加普通<script>块，在默认导出上方添加JSDoc注释：

<script lang="ts">
/**
 * 展示歌曲演唱者的信息组件
 * @remarks 支持显示头像、姓名、简介等信息，可自定义是否显示关注按钮
 * @example
 * ```vue
 * <ArtistInfo :artist="currentArtist" showFollowBtn />
 * ```
 */
export default {
  name: 'ArtistInfo'
}
</script>

<script setup lang="ts">
// 组件内部逻辑
const props = defineProps<{
  artist: { id: number; name: string; avatar: string; bio?: string }
  showFollowBtn?: boolean
}>()
</script>

二、确保VSCode智能感知生效的配置 #

1. 启用Volar的Take Over Mode

   • 在VSCode扩展面板中，禁用TypeScript and JavaScript Language Features扩展
   • 仅保留Vue Language Features (Volar)扩展启用
   • 重启VSCode后，Volar会完全接管Vue/TS的智能解析，提升注释识别能力

2. 检查tsconfig.json配置
   确保compilerOptions.types包含vue，让TypeScript识别Vue类型定义：

{
  "compilerOptions": {
    "types": ["vue"]
  }
}

关键注意事项 #

• 必须使用多行JSDoc注释（/** ... */），单行//注释无法被智能感知识别
• 注释中的@remarks、@example等标签会被解析展示，能让组件说明更清晰
• 必须通过defineOptions或普通<script>块的name属性明确指定组件名称，否则Volar无法关联注释与组件

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