unref 是 Vue 3 用于解包 ref 的工具函数，若参数为 ref 则返回其 .value，否则原样返回，支持泛型兼容场景；它不递归解包，仅处理单层 ref，适用于防抖、校验等需统一 ref/普通值输入的工具函数。
unref 是 Vue 3 提供的一个实用工具函数，用于“解包”响应式引用（ref），它能自动判断传入的值是否为 ref：如果是，就返回其 .value；如果不是，就原样返回。这个特性让它成为编写**同时支持 ref 和普通值（即“泛型兼容”）工具函数**的关键。
unref 的基本用法
它本质就是一个简洁的条件判断：
- 当参数是 ref（即有
.value属性且是 ref 实例），返回val.value - 否则直接返回
val
示例：
import { ref, unref } from 'vue'const countRef = ref(42)
const countPlain = 100
console.log(unref(countRef)) // 42
console.log(unref(countPlain)) // 100
为什么需要 unref？解决“类型不确定”的痛点
在封装可复用逻辑（比如自定义 Hook 或工具函数）时，用户可能传 ref（便于响应式联动），也可能传普通值（简单场景）。如果函数内部只按 ref 处理，就会报错；只按普通值处理，又丢失响应式能力。unref 让你无需提前判断或要求调用方统一包装，自然桥接两种输入。
立即学习“前端免费学习笔记（深入）”；
Vue 3 组合式 API 与 最佳实践，涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应式优化及功能抽取。
常见适用场景包括：
• 计算属性的依赖项归一化
• 表单校验、防抖、节流等工具函数的参数标准化
• 封装第三方库（如 Chart.js）的响应式适配层
实战：写一个兼容 ref/普通值的 debounce 函数
下面是一个基于 unref 的防抖工具函数，支持传 ref 或原始值：
import { ref, unref, onBeforeUnmount } from 'vue'import { debounce as _debounce } from 'lodash-es'
export function useDebouncedValue(source, delay = 300) {
const debouncedRef = ref(unref(source)) // 初始值解包
const debouncedFn = _debounce((val) => {
debouncedRef.value = val
}, delay)
// 监听 source 变化（支持 ref 响应式更新）
if (typeof source === 'object' && source?.value !== undefined) {
watch(source, (newVal) => {
debouncedFn(newVal)
})
} else {
// 普通值不监听，仅用初始值
}
onBeforeUnmount(() => debouncedFn.cancel())
return debouncedRef
}
调用方式统一：
// 传 ref，自动响应变化const searchQuery = ref('')
const debouncedQuery = useDebouncedValue(searchQuery, 500)
// 传普通字符串，只取初始值
const debouncedStatic = useDebouncedValue('hello', 500)
注意事项和边界情况
• unref 不递归：只解一层 ref。如果传入的是 ref(ref(42))，结果是 ref(42)，不是 42。需要多层解包可用 shallowUnwrapRef 或手动链式调用。
• 对 computed/ref 混合使用安全：unref 对 computed ref 同样有效，会触发 getter 并返回计算结果。
• 不能替代 reactive 解构：unref 只处理 ref 类型，对 reactive 对象需用 toRefs 或 toRef 转换后再 unref。
• 注意副作用时机：在 setup 或组合式 API 中使用 unref 是安全的；但在非响应式上下文（如普通函数、事件回调中）调用它只是做值提取，不触发依赖收集。
