# Vue 3 `＜script setup＞` 中变量声明的正确姿势：何时必须使用 `ref()`？

在使用 Vue 3 的 <script setup> 语法糖进行开发时，很多开发者会遇到一个常见问题：

"为什么我直接修改变量会报错？明明在模板里能用啊！"

本文将彻底讲清楚这个核心规则，并提供最佳实践建议。

---

🔥 核心规则

在 Vue 3 的 <script setup> 中：

所有需要被修改的变量都必须使用 ref() 包装！

无论该变量是否在模板中使用。

---

❓ 为什么会这样？

<script setup> 内部会对顶层绑定的变量进行只读处理 （类似 Object.freeze()），这是 Vue 3 的有意设计，目的包括：

1. 防止意外修改：避免直接赋值导致响应式系统失效
2. 性能优化：只读变量可被编译器更好地优化
3. 明确意图 ：通过 ref() 显式声明"这是一个可变的响应式数据"

---

🚫 错误示例 vs ✅ 正确写法

❌ 错误：直接声明并修改普通变量

// 报错！TypeError: "xxx" is read-only
const noMoreData = false;
noMoreData = true;  // ❌ 运行时错误！

✅ 正确：使用 ref() 包装

import { ref } from 'vue';

const noMoreData = ref(false);
noMoreData.value = true;  // ✅ 完全正常

💡 注意：修改时要通过 .value，但在模板中使用时无需 .value（Vue 自动解包）

---

📋 实际开发中的使用指南

变量类型	是否需要 ref()	示例
模板中使用的数据	✅ 必须	const list = ref([])
需要动态修改的状态	✅ 必须	const loading = ref(false)
分页/加载控制标志	✅ 必须	const noMoreData = ref(false)
常量（永不修改）	❌ 不需要	const PAGE_SIZE = 20
配置项/URL 基础路径	❌ 不需要	const BASE_URL = 'https://api.example.com'
工具函数	❌ 不需要	const formatDate = (date) => {...}

---

✅ 推荐代码结构

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

// ✅ 需要 ref() 的变量（会变化 or 模板使用）
const userList = ref([])
const isLoading = ref(false)
const currentPage = ref(1)
const hasMore = ref(true)

// ❌ 不需要 ref() 的变量（常量/函数）
const PAGE_SIZE = 10
const API_BASE = '/api'
const formatTime = (timestamp) => {
  return new Date(timestamp).toLocaleString()
}

// 计算属性（自动响应式，无需 ref）
const totalUsers = computed(() => userList.value.length)
</script>

---

⚠️ 常见误区提醒

• 误区1 ："只要不在模板里用，就可以不用 ref"

  → 错！只要需要修改，就必须用 ref

• 误区2 ："用 let 声明就能修改"

  → 错！<script setup> 中的 let 变量同样会被冻结

• 误区3 ："可以用 reactive 代替 ref"

  → 对于基础类型（boolean/number/string），reactive 无效，必须用 ref

---

✅ 总结

在 Vue 3 <script setup> 中，请牢记：

• 要修改？→ 用 ref()
• 不修改？→ 普通变量即可

这不仅是语法要求，更是 Vue 3 响应式系统的设计哲学------让可变性显式化，让代码更安全、更清晰！

遵循这一原则，你将避免绝大多数"只读错误"，写出更健壮的 Vue 3 应用！🚀