Vue 3组合式API中，`defineProps`或`defineEmits`未在setup顶部调用报错

Question

**问题：** 在 Vue 3 组合式 API 中，若将 `defineProps` 或 `defineEmits` 写在 `setup()` 函数内部（如条件语句、异步回调、或普通函数调用之后），而非**顶层（top-level）直接调用**，会触发编译错误：`'defineProps' is not defined` 或 `cannot be used as a function`（Volar/Vue TS 插件报错），甚至导致 props/emits 无法被正确推导、类型丢失、热更新失效。这是因为 `defineProps`/`defineEmits` 是编译时宏（compile-time macros），需在 `<script></script>

Answer 1

```html

一、现象层：编译报错与开发体验断层

开发者在 Vue 3 单文件组件（SFC）中误将 defineProps 写入 setup() 函数体内（如 if (loading) { defineProps(...) }），立即触发 Volar 插件红波浪线提示：'defineProps' is not defined 或 cannot be used as a function。TS 类型检查失效，IDE 无法推导 props 接口，HMR（热模块替换）跳过该组件更新，导致局部刷新失灵。

二、机制层：编译时宏的本质与限制

defineProps 和 defineEmits 并非运行时函数，而是由 Vite + @vue/compiler-sfc 在 <script setup> 编译阶段识别的“语法糖宏”（Syntax Macro）。其核心行为如下：

• 仅在 <script setup> 的顶层作用域（top-level）被静态解析；
• 编译器据此生成 __props 类型声明、props 响应式代理及 emit 类型约束；
• 若嵌套于条件/循环/异步回调中，AST 解析器无法定位其声明位置，直接忽略或报错。

三、影响层：多维技术链路的级联故障

维度	具体表现
类型系统	TS 无法 infer props 接口，PropType 失效，ref/computed 中访问 props.xxx 报 any 类型警告
开发工具链	Volar 自动补全中断、Vue Devtools 显示 props: {} 空对象、Emits 面板无事件列表
构建与部署	Vite 生产构建时因宏解析失败抛出 ParseError，CI/CD 流水线中断

四、验证层：最小可复现案例与 AST 分析

<!-- ❌ 错误写法：宏在 setup 内部 -->
<script setup>
const setup = () => {
  if (true) {
    const props = defineProps({ msg: String }); // 编译器完全忽略此行
  }
};
setup();
</script>

<!-- ✅ 正确写法：顶层调用 -->
<script setup>
// 必须在此处（script setup 根作用域）直接调用
const props = defineProps({ msg: String });
const emit = defineEmits(['update:modelValue']);
</script>

五、原理层：Vue SFC 编译流水线深度拆解

下图展示 defineProps 在 Vue 3 编译流程中的关键节点：

graph LR A[<script setup> 源码] --> B{编译器扫描顶层语句} B -->|匹配 defineProps/defineEmits| C[提取参数生成 TS 接口] B -->|未在顶层发现| D[跳过宏处理 → 类型丢失] C --> E[注入 __default__ 类型定义到 __VUE_SFC_OPTIONS__] E --> F[VS Code/Volar 读取类型元数据] D --> G[TS Server 返回 unknown]

六、解决方案层：合规写法与工程化兜底策略

1. 强制约定：所有 defineProps/defineEmits 必须置于 <script setup> 最外层，禁止包裹任何逻辑块；
2. 类型即文档：使用泛型语法 defineProps<{ msg: string }>() 替代运行时对象，提升类型优先级；
3. ESLint 规则加固：启用 @vue/vue3-define-props-declaration 插件，自动检测非法嵌套位置；
4. 构建时校验：在 Vite 插件中 hook transform 阶段，对 AST 中 CallExpression.callee.name === 'defineProps' 进行作用域深度判断，抛出明确错误。

七、演进层：Vue 官方设计哲学与未来兼容性

Vue 团队明确将 defineProps 定义为“编译时契约”（Compile-time Contract），其设计初衷是解耦类型系统与运行时逻辑，避免像 Vue 2 的 props: {} 那样导致类型擦除。在 RFC 438（Script Setup Macros）中强调：“Macros are not functions — they are compile-time directives that shape the component’s type and runtime behavior.” 这意味着即使未来支持 defineProps 动态参数（如基于 import.meta.env 的条件 props），也必通过编译器预处理实现，而非运行时分支。

```