一、引言

二、技术背景

1. Vue 3 组合式 API 的演进

<script>
import { ref } from 'vue';

export default {
  setup() {
    const count = ref(0); // 响应式数据
    const increment = () => { count.value++; }; // 方法

    // 必须显式返回模板中使用的变量/方法
    return { count, increment };
  }
}
</script>

<template>
  <button @click="increment">{{ count }}</button> <!-- 需通过返回值访问 -->
</template>

• ​​冗余返回​​：模板中使用的变量（如 count）和方法（如 increment）必须手动通过 return暴露，否则模板无法访问；
• ​​代码嵌套深​​：逻辑聚合虽灵活，但语法层面仍需显式处理返回值，降低了代码的直观性。

2. <script setup>语法糖的诞生

<script setup>
import { ref } from 'vue';

const count = ref(0); // 直接定义响应式数据
const increment = () => { count.value++; }; // 直接定义方法

// 无需手动 return！模板中可直接使用 count 和 increment
</script>

<template>
  <button @click="increment">{{ count }}</button> <!-- 直接访问 -->
</template>

• ​​更简洁​​：移除 setup()函数包裹和显式 return，代码量减少约 30%；
• ​​更直观​​：模板与脚本的变量/方法映射关系更直接（如同选项式 API 的 data和 methods）；
• ​​性能优化​​：编译时确定模板依赖，减少运行时开销。

三、应用使用场景

1. 基础组件开发（高频交互逻辑）

2. 复杂逻辑聚合（多个功能模块）

3. 组件通信（Props/Emits 优化）

4. 第三方库集成（如 Vue Router/Pinia）

四、不同场景下详细代码实现

场景 1：基础计数器组件（对比传统 setup() 与 <script setup>）

传统 setup() 写法

<!-- CounterTraditional.vue -->
<script>
import { ref } from 'vue';

export default {
  setup() {
    const count = ref(0); // 响应式数据
    const increment = () => { count.value++; }; // 方法
    const decrement = () => { count.value--; };
    const reset = () => { count.value = 0; };

    // 必须显式返回模板中使用的变量和方法
    return { count, increment, decrement, reset };
  }
}
</script>

<template>
  <div>
    <p>当前计数: {{ count }}</p>
    <button @click="increment">+1</button>
    <button @click="decrement">-1</button>
    <button @click="reset">重置</button>
  </div>
</template>

<script setup> 写法（语法糖优化）

<!-- CounterScriptSetup.vue -->
<script setup>
import { ref } from 'vue';

const count = ref(0); // 直接定义响应式数据
const increment = () => { count.value++; }; // 直接定义方法
const decrement = () => { count.value--; };
const reset = () => { count.value = 0; };

// 无需 return！模板中可直接访问 count/increment/decrement/reset
</script>

<template>
  <div>
    <p>当前计数: {{ count }}</p>
    <button @click="increment">+1</button>
    <button @click="decrement">-1</button>
    <button @click="reset">重置</button>
  </div>
</template>

• 传统 setup()需要显式 return { count, increment, ... }，而 <script setup>直接在模板中使用顶层变量/方法，代码量减少 4 行，可读性更高。

场景 2：用户表单组件（逻辑聚合）

<!-- UserForm.vue -->
<script setup>
import { ref, computed } from 'vue';

// 表单数据（响应式）
const name = ref('');
const age = ref('');

// 计算属性：验证状态（逻辑聚合）
const isNameValid = computed(() => name.value.trim() !== '');
const isAgeValid = computed(() => /^\d+$/.test(age.value) && parseInt(age.value) > 0);
const isFormValid = computed(() => isNameValid.value && isAgeValid.value);

// 提交方法
const handleSubmit = () => {
  if (isFormValid.value) {
    console.log('提交数据:', { name: name.value, age: parseInt(age.value) });
    alert(`注册成功！姓名: ${name.value}, 年龄: ${age.value}`);
  } else {
    alert('请填写正确的姓名（非空）和年龄（正整数）');
  }
};
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <div>
      <label>姓名（必填）:</label>
      <input v-model="name" placeholder="请输入姓名" />
      <span v-if="name && !isNameValid" style="color: red;">姓名不能为空</span>
    </div>
    <div>
      <label>年龄（正整数）:</label>
      <input v-model="age" type="text" placeholder="请输入年龄" />
      <span v-if="age && !isAgeValid" style="color: red;">年龄必须是正整数</span>
    </div>
    <button type="submit" :disabled="!isFormValid">注册</button>
  </form>
</template>

• 所有表单逻辑（数据、验证规则、提交方法）集中在 <script setup>的顶层作用域，无需拆分到不同选项；
• computed计算的验证状态直接在模板中绑定，代码结构清晰。

五、原理解释

1. <script setup>的本质

• ​​顶层变量自动暴露​​：在 <script setup>中定义的顶层变量（如 const count = ref(0)）、函数（如 const increment = () => {}）和导入的组件（如 import MyComponent from './MyComponent.vue'），会被编译器自动视为模板中可用的内容，无需手动 return；
• ​​编译时优化​​：模板中的表达式（如 {{ count }}）会被静态分析，仅依赖 <script setup>中定义的变量，减少运行时响应式追踪的开销；
• ​​特殊宏支持​​：通过编译器宏（如 defineProps、defineEmits、defineExpose）处理组件通信，这些宏在编译时会被转换为正确的运行时逻辑。

2. 执行时机与生命周期

• ​​执行时机​​：<script setup>中的代码会在 ​​组件初始化阶段（与 setup()函数相同）​​ 执行，即在组件实例创建时、模板编译前运行。此时可以访问组件的 props、context等初始信息；
• ​​生命周期钩子​​：在 <script setup>中使用生命周期钩子时，需导入 Vue 提供的 ​​组合式 API 形式的钩子​​（如 onMounted、onUpdated），它们会在对应阶段触发（与 setup()中调用钩子的时机完全一致）。

<script setup>
import { onMounted, ref } from 'vue';

const message = ref('组件已挂载');

// onMounted 是组合式 API 的生命周期钩子，在组件挂载后执行
onMounted(() => {
  console.log(message.value); // 输出：组件已挂载
});
</script>

<template>
  <div>{{ message }}</div>
</template>

3. 与普通 setup()函数的关系

• ​​功能等价​​：<script setup>最终会被编译为传统的 setup()函数，二者在运行时行为完全一致（响应式系统、生命周期、组件通信机制均相同）；
• ​​语法差异​​：<script setup>通过编译时优化省略了 setup()函数包裹和显式 return，但底层逻辑（如响应式数据的创建、钩子的注册）与普通 setup()无本质区别。

六、核心特性

七、原理流程图及原理解释

原理流程图（<script setup> 执行过程）

+-----------------------+       +-----------------------+       +-----------------------+
|     开发者编写代码     |       |     Vue 编译器        |       |     运行时组件实例    |
|  (Vue 模板 + <script setup>) |  (语法糖转换)         |  (传统 setup() 逻辑)  |
+-----------------------+       +-----------------------+       +-----------------------+
          |                             |                             |
          |  1. 编写 <script setup> 代码 |                             |  
          |  (定义顶层变量/函数/导入组件) |                             |  
          |--------------------------->|  2. 编译时转换为 setup() 函数 |  
          |                             |  (自动暴露顶层变量，省略 return) |  
          |                             |--------------------------->|  3. 组件初始化时执行 setup() |  
          |                             |                             |  (响应式数据创建、钩子注册) |  
          |                             |                             |--------------------------->|  4. 模板渲染时访问变量/方法 |  
          |                             |                             |  (直接使用编译时确定的依赖) |

原理解释

1. ​​开发阶段​​：开发者编写 <script setup>代码（如定义 const count = ref(0)和方法 increment），无需考虑显式返回值；
2. ​​编译阶段​​：Vue 编译器将 <script setup>代码转换为传统的 setup()函数逻辑——将顶层变量/函数收集到作用域中，并自动将这些内容作为模板可用的依赖（相当于隐式 return），同时将 defineProps/defineEmits等宏转换为运行时逻辑；
3. ​​运行时阶段​​：组件初始化时，转换后的 setup()函数执行（与普通 setup()时机相同），创建响应式数据、注册生命周期钩子；模板渲染时，直接访问编译时确定的依赖（如 count和 increment），无需运行时动态解析。

八、环境准备

1. 开发工具

• ​​Vue 3 版本​​：需使用 Vue 3.2 及以上版本（<script setup>是 3.2 正式引入的语法糖）；
• ​​构建工具​​：推荐使用 Vite（官方推荐，对 Vue 3 支持最佳）或 Vue CLI（需确保 Vue 版本 ≥ 3.2）；
• ​​IDE 支持​​：VS Code + Vue 官方插件（Volar），可提供 <script setup>的语法高亮、类型推断和代码提示。

2. 项目初始化

npm create vue@latest my-script-setup-demo # 选择 Vue 3.2+ 模板
cd my-script-setup-demo
npm install
npm run dev

vue create my-script-setup-demo --default # 选择 Vue 3 配置

九、实际详细应用代码示例实现

完整示例：待办事项列表组件（<script setup> 实现）

<!-- TodoList.vue -->
<script setup>
import { ref, computed } from 'vue';

// 待办事项列表（响应式数据）
const todos = ref([
  { id: 1, text: '学习 Vue 3', completed: false },
  { id: 2, text: '写项目文档', completed: true }
]);

// 输入框的新任务文本
const newTodoText = ref('');

// 计算属性：未完成任务数量
const pendingCount = computed(() => 
  todos.value.filter(todo => !todo.completed).length
);

// 添加新任务
const addTodo = () => {
  if (newTodoText.value.trim()) {
    todos.value.push({
      id: Date.now(), // 简单的唯一 ID
      text: newTodoText.value.trim(),
      completed: false
    });
    newTodoText.value = ''; // 清空输入框
  }
};

// 删除任务
const deleteTodo = (id) => {
  const index = todos.value.findIndex(todo => todo.id === id);
  if (index > -1) {
    todos.value.splice(index, 1);
  }
};

// 切换任务完成状态
const toggleComplete = (id) => {
  const todo = todos.value.find(todo => todo.id === id);
  if (todo) {
    todo.completed = !todo.completed;
  }
};
</script>

<template>
  <div class="todo-container">
    <h2>待办事项列表 (未完成: {{ pendingCount }})</h2>
    
    <!-- 添加新任务 -->
    <div class="add-todo">
      <input 
        v-model="newTodoText" 
        placeholder="输入新任务..." 
        @keyup.enter="addTodo" 
      />
      <button @click="addTodo">添加</button>
    </div>

    <!-- 任务列表 -->
    <ul class="todo-list">
      <li v-for="todo in todos" :key="todo.id" class="todo-item">
        <input 
          type="checkbox" 
          :checked="todo.completed" 
          @change="toggleComplete(todo.id)" 
        />
        <span :class="{ completed: todo.completed }">{{ todo.text }}</span>
        <button @click="deleteTodo(todo.id)" class="delete-btn">删除</button>
      </li>
    </ul>
  </div>
</template>

<style scoped>
.todo-container { max-width: 400px; margin: 20px auto; padding: 20px; }
.add-todo { display: flex; gap: 10px; margin-bottom: 20px; }
.add-todo input { flex: 1; padding: 8px; border: 1px solid #ddd; border-radius: 4px; }
.add-todo button { padding: 8px 16px; background: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer; }
.todo-list { list-style: none; padding: 0; }
.todo-item { display: flex; align-items: center; gap: 10px; padding: 10px; border-bottom: 1px solid #eee; }
.todo-item span { flex: 1; }
.completed { text-decoration: line-through; color: #999; }
.delete-btn { padding: 4px 8px; background: #dc3545; color: white; border: none; border-radius: 4px; cursor: pointer; }
</style>

• 页面显示待办事项列表，顶部提示未完成任务数量（如“未完成: 1”）；
• 输入框支持回车键或点击按钮添加新任务；
• 勾选复选框可标记任务完成（文字变删除线），点击“删除”按钮移除任务；
• 所有逻辑（数据、方法、计算属性）集中在 <script setup>中，模板直接使用顶层变量/方法，代码简洁直观。

十、运行结果与测试步骤

测试步骤（以 TodoList 组件为例）

1. ​​初始状态验证​​：打开页面，确认初始待办事项（如“学习 Vue 3”未完成，“写项目文档”已完成）正确显示，未完成任务数量为 1；
2. ​​添加任务测试​​：在输入框输入“买菜”，点击“添加”按钮或按回车键，确认新任务出现在列表中，未完成任务数量更新为 2；
3. ​​完成任务测试​​：勾选“学习 Vue 3”的复选框，确认文字变为删除线，未完成任务数量更新为 1；
4. ​​删除任务测试​​：点击“买菜”任务的“删除”按钮，确认该任务从列表中移除，未完成任务数量更新为 1；
5. ​​边界测试​​：在输入框输入空格或直接点击“添加”按钮，确认不会添加无效任务。

十一、部署场景

1. 前端部署（静态资源）

• ​​Vite 项目​​：运行 npm run build生成 dist目录，可将静态文件（HTML/CSS/JS）部署到 Nginx、Vercel、Netlify 等平台；
• ​​Vue CLI 项目​​：运行 npm run build生成 dist目录，部署方式同上。

2. 与后端集成

• 若待办事项需要持久化存储（如保存到数据库），可在 <script setup>中调用后端 API（通过 fetch或 axios），例如：

  const addTodo = async () => {
    if (newTodoText.value.trim()) {
      const res = await fetch('/api/todos', {
        method: 'POST',
        body: JSON.stringify({ text: newTodoText.value.trim() }),
        headers: { 'Content-Type': 'application/json' }
      });
      const data = await res.json();
      todos.value.push(data); // 将后端返回的任务添加到列表
      newTodoText.value = '';
    }
  };

十二、疑难解答

Q1：为什么 <script setup>中定义的变量模板可以直接使用？

Q2：<script setup> 与普通 setup() 的生命周期钩子调用时机一样吗？

Q3：如何获取父组件传递的 Props 和 Emits？

<script setup>
// 定义 Props（类型可通过 TypeScript 增强）
const props = defineProps({
  title: String, // 父组件传递的 title 属性
  initialCount: Number
});

// 定义 Emits（事件名和参数类型）
const emit = defineEmits(['updateCount']); 

// 使用 Props 和触发 Emits
console.log(props.title); // 访问父组件传递的 title
const handleClick = () => { emit('updateCount', 10); }; // 触发父组件的 updateCount 事件
</script>

十三、未来展望

1. 技术趋势

• ​​更强大的类型推导​​：随着 Vue 3 与 TypeScript 的深度集成，<script setup>将进一步优化类型推断（例如自动推断 props和 emits的类型），提升开发体验；
• ​​编译时优化增强​​：未来的 Vue 版本可能进一步优化 <script setup>的编译结果（如更小的运行时体积、更快的模板渲染速度）；
• ​​跨框架复用​​：<script setup>的逻辑聚合特性可能推动跨框架（如 React/Vue）的逻辑复用方案（例如通过 Unocss 或通用组合式函数）。

2. 挑战

• ​​学习成本​​：对于习惯传统 setup()或选项式 API 的开发者，需要适应 <script setup>的顶层作用域逻辑和编译时特性；
• ​​调试复杂度​​：由于编译时转换，调试时可能需要关注生成的 setup()函数逻辑（可通过 Vue Devtools 观察组件状态）；
• ​​宏的兼容性​​：defineProps、defineEmits等宏是编译器特定的语法，在非 Vue 环境（如纯 JavaScript 文件）中无法直接使用。

十四、总结