Vue3基于Proxy重构了响应式系统，提供了一套灵活的API矩阵——核心的ref与reactive、浅响应式的shallowRef/shallowReactive、只读封装的readonly/shallowReadonly。这些API看似功能重叠，实则各有适配场景，误用易导致响应式失效或性能冗余。本文将从特性本质、核心区别、代码示例、适用场景四个维度，系统拆解六大API，帮你精准选型、规避踩坑。

一、核心基础：ref 与 reactive

ref和reactive是Vue3响应式开发的基石，均用于创建响应式数据，但针对的数据类型、访问方式有明确边界，是后续衍生API的设计基础。

1. 核心特性与区别

维度	ref	reactive
支持类型	基本类型（string/number/boolean等）+ 引用类型	仅支持引用类型（对象/数组），基本类型传入无响应式效果
实现原理	封装为Ref对象（含.value属性），基本类型靠Object.defineProperty拦截.value，引用类型内部调用reactive	直接通过Proxy拦截对象的属性读取/修改，天然支持嵌套属性响应式
操作方式	脚本中需通过.value访问/修改，模板中自动解包（无需.value）	脚本、模板中均直接操作属性（无.value冗余）
解构特性	解构后丢失响应式，需用toRefs/toRef转换保留	直接解构失效，通过toRefs可将属性转为Ref对象维持响应式
响应式深度	默认深响应式（嵌套对象属性变化触发更新）	默认深响应式（嵌套对象属性变化触发更新）

2. 代码示例

import { ref, reactive, toRefs } from 'vue';

// ref使用：基本类型+引用类型
const count = ref(0);
count.value++; // 脚本中必须用.value
console.log(count.value); // 1

const user = ref({ name: '张三', age: 20 });
user.value.age = 21; // 嵌套属性修改，触发响应式

// reactive使用：仅引用类型
const person = reactive({ name: '李四', info: { height: 180 } });
person.name = '王五'; // 直接操作属性
person.info.height = 185; // 嵌套属性深响应式

// 解构处理
const { name, age } = toRefs(user.value); // 保留响应式
name.value = '赵六'; // 触发更新

3. 适用场景

ref：优先用于基本类型响应式（如计数器、开关状态、输入框值）；单独维护单个引用类型数据（无需复杂嵌套解构）；组合式API中作为默认选择，灵活性更高。

reactive：适用于复杂引用类型（如用户信息、列表数据、表单聚合状态）；希望避免.value冗余，追求更直观的属性操作；组件内部状态聚合管理（相关属性封装为一个对象，可读性更强）。

二、性能优化：shallowRef 与 shallowReactive

ref和reactive的深响应式会递归处理所有嵌套属性，对大型对象/第三方实例而言，可能产生不必要的性能开销。浅响应式API仅拦截顶层数据变化，专为性能优化场景设计。

1. 核心特性与区别

维度	shallowRef	shallowReactive
支持类型	基本类型 + 引用类型（同ref）	仅引用类型（同reactive）
响应式深度	仅拦截.value的引用替换，嵌套属性变化不触发更新	仅拦截顶层属性变化，嵌套属性变化无响应式效果
更新触发	需替换.value引用（如shallowRef.value = 新对象）；嵌套修改需用triggerRef手动触发更新	仅修改顶层属性触发更新，嵌套属性修改完全不拦截
使用成本	嵌套修改需手动触发更新，有额外编码成本	无需手动触发，但需牢记仅顶层响应式，易踩坑

2. 代码示例

import { shallowRef, shallowReactive, triggerRef } from 'vue';

// shallowRef示例
const shallowUser = shallowRef({ name: '张三', info: { age: 20 } });
shallowUser.value.info.age = 21; // 嵌套修改，无响应式
shallowUser.value = { name: '李四', info: { age: 22 } }; // 替换引用，触发更新
triggerRef(shallowUser); // 手动触发更新（嵌套修改后强制同步）

// shallowReactive示例
const shallowPerson = shallowReactive({
  name: '王五',
  info: { height: 180 }
});
shallowPerson.name = '赵六'; // 顶层修改，触发更新
shallowPerson.info.height = 185; // 嵌套修改，无响应式

3. 适用场景

shallowRef：引用类型数据仅需整体替换（如大型图表配置、第三方库实例、不可变数据）；明确不需要嵌套属性响应式，追求极致性能（避免递归Proxy开销）。

shallowReactive：复杂对象仅需顶层属性响应式（如表单顶层状态、静态嵌套数据的配置对象）；大型对象场景下，规避深响应式的性能损耗，且无需频繁修改嵌套属性。

注意：浅响应式API并非“银弹”，仅在明确不需要深层响应式时使用，否则易导致响应式失效问题，增加调试成本。

三、只读防护：readonly 与 shallowReadonly

在父子组件通信、全局常量管理等场景，需禁止数据被修改，此时可使用只读API。它们会拦截修改操作（开发环境抛警告），同时保留原数据的响应式特性（原数据变化时，只读数据同步更新）。

1. 核心特性与区别

维度	readonly	shallowReadonly
支持类型	引用类型为主（基本类型只读无实际意义）	引用类型为主（基本类型只读无实际意义）
只读深度	深只读：顶层+所有嵌套属性均不可修改	浅只读：仅顶层属性不可修改，嵌套属性可正常修改
修改拦截	任何层级修改均被拦截，开发环境抛警告	仅顶层修改被拦截，嵌套修改无拦截、无警告
响应式保留	保留深响应式：原数据任意层级变化，只读数据同步更新	保留浅响应式：原数据变化（无论层级），只读数据同步更新

2. 代码示例

import { readonly, shallowReadonly, reactive } from 'vue';

// 原始响应式数据
const original = reactive({
  name: '张三',
  info: { age: 20 }
});

// readonly示例
const readOnlyData = readonly(original);
readOnlyData.name = '李四'; // 顶层修改，被拦截（抛警告）
readOnlyData.info.age = 21; // 嵌套修改，被拦截（抛警告）
original.name = '李四'; // 原数据变化，只读数据同步更新
console.log(readOnlyData.name); // 李四

// shallowReadonly示例
const shallowReadOnlyData = shallowReadonly(original);
shallowReadOnlyData.name = '王五'; // 顶层修改，被拦截（抛警告）
shallowReadOnlyData.info.age = 22; // 嵌套修改，正常执行（无警告）
console.log(shallowReadOnlyData.info.age); // 22

3. 适用场景

readonly：完全禁止修改的响应式数据（如全局常量配置、接口返回的不可变数据）；父子组件通信的Props（Vue内部默认对Props做readonly处理，防止子组件修改父组件状态）；需要严格防护数据完整性的场景。

shallowReadonly：仅需禁止顶层属性修改，嵌套属性允许微调（如父组件传递给子组件的复杂对象，子组件可修改嵌套细节但不能替换整体）；追求性能优化，避免深只读的递归拦截开销（大型对象场景更明显）。

四、API选型总指南与避坑要点

1. 快速选型流程图

1. 明确需求：是否需要响应式？→ 不需要则直接用普通变量；需要则进入下一步。
2. 数据类型：基本类型→只能用ref；引用类型→进入下一步。
3. 修改权限：需要禁止修改→readonly（深防护）/shallowReadonly（浅防护）；允许修改→进入下一步。
4. 响应式深度：仅需顶层响应式→shallowRef/shallowReactive；需要深层响应式→ref/reactive。
5. 操作习惯：避免.value→reactive；接受.value或基本类型→ref。

2. 常见坑点规避

• ref解构丢失响应式：务必用toRefs/toRef转换，而非直接解构。
• reactive传入基本类型：无响应式效果，需改用ref。
• 浅响应式嵌套修改失效：shallowRef需用triggerRef手动触发，shallowReactive避免依赖嵌套属性更新。
• readonly修改原数据：只读API仅拦截对自身的修改，原数据仍可修改，需注意数据溯源。
• ref嵌套对象修改：无需额外处理，内部已转为reactive，直接修改.value.属性即可。

五、总结

Vue3的响应式API设计围绕“灵活性”与“性能”两大核心：ref/reactive构建基础响应式能力，适配绝大多数日常场景；shallow系列API针对性优化性能，降低大型数据的响应式开销；readonly系列API保障数据安全性，适配只读场景。

核心原则是“按需选型”——无需为简单场景引入复杂API，也无需为性能牺牲开发效率。掌握各API的响应式深度、修改权限、操作方式，就能在项目中精准运用，打造高效、健壮的响应式系统。