Vue 3 如何使用 defineOptions 宏在 `<script setup>` 中定义组件选项名称

defineOptions是Vue 3.3+专为<script setup>设计的编译宏，用于声明name、inheritAttrs等组件选项，替代双<script>写法，提升类型安全与代码一致性。

` 中定义组件选项名称">

在 Vue 3.3+ 中，defineOptions 是专为 <script setup> 设计的编译宏，用于声明原本无法直接写在 setup 脚本中的组件选项（如 name）。它不需要导入（Vue 3.4+ 可直接使用），但推荐显式引入以获得完整类型提示和 IDE 支持。

基础用法：设置组件 name

最常见、最刚需的用途就是显式指定组件名，替代默认的文件名推导：

1. 不写 defineOptions 时，组件名默认取自文件名（如 UserCard.vue → UserCard），但调试工具中可能显示为 <AnonymousComponent>
2. 添加后，DevTools、<KeepAlive> 匹配、错误堆栈都会准确识别该名称

示例（TypeScript 推荐写法）：

<script setup lang="ts">import { defineOptions } from 'vue'defineOptions({name: 'UserProfileCard'})const props = defineProps<{ userId: string }>()</script>

支持的常用选项不止 name

defineOptions 不仅限于命名，还能集中管理多个关键配置项：

1. inheritAttrs: false：关闭 attribute 自动继承，适用于封装透传属性的高阶组件
2. emits: ['submit', 'cancel']：显式声明触发事件（虽可用 defineEmits，但此处更集中）
3. components: { CustomButton }：局部注册子组件（仍建议优先用 import + 模板中直接使用）

多选项合并示例：

<script setup lang="ts">import { defineOptions } from 'vue'import CustomButton from './CustomButton.vue'defineOptions({name: 'FormContainer',inheritAttrs: false,emits: ['submit', 'cancel']})</script>

注意事项与避坑点

使用时需注意几个关键细节：

1. 不能在 defineOptions 中定义响应式数据（如 ref、reactive），只用于声明组件元信息
2. 不支持 props、emits、expose、slots —— 这些已有专用宏（defineProps 等）处理
3. 避免混用旧方式：<script setup name="xxx"> 属于非标准写法，兼容性差，已不推荐
4. 若项目使用 Vue < 3.3，需升级或改用插件（如 vite-plugin-vue-setup-extend），但该插件维护停滞，存在兼容风险

为什么比双 script 标签更优？

相比传统“一个 <script setup> 写逻辑 + 一个普通 <script> 写选项”的方式：

1. 代码不割裂：所有组件配置与逻辑共处同一作用域，结构清晰
2. 类型安全：TypeScript 下自动获得选项对象的类型推导（Volar / Vue Language Features 支持良好）
3. 构建友好：作为编译时宏，无运行时开销，打包后不影响性能