Vue 3 shallowRef 怎样避免大型对象被深度代理

Vue 3 里，如果状态是一个很大的嵌套对象，而且业务更适合“整份快照替换”而不是逐字段编辑，可以用 shallowRef() 避免深度代理。它只让外层的 .value 访问保持响应式，内部对象按原样保存；因此修改嵌套字段不会自动触发更新，替换整个 .value 才是推荐的更新入口。

官方地址：https://vuejs.org/api/reactivity-advanced.html

记住一句话：shallowRef 优化的是“代理深度”，不是让对象完全失去更新能力。把大型数据当作不可变快照替换时，它最清晰；确实要深改时，再显式调用 triggerRef()。

ref 与 shallowRef 的代理深度差异

ref(object) 会把对象值纳入深层响应式转换，读取和修改嵌套属性可以参与依赖追踪。shallowRef(object) 则只追踪 .value 这一层，内部对象不会因为放进 ref 就被递归转换。大型表格数据、外部状态对象或本身已经按不可变方式管理的数据，通常更适合后一种边界。

最小写法如下：

import { ref, shallowRef } from 'vue'

// 大型对象放在普通 ref 中时，嵌套访问也会进入响应式转换
const deepState = ref({
  rows: [{ id: 1, name: '第一行' }]
})

// shallowRef 只把 value 这一层作为更新边界，内部对象保持原样
const snapshot = shallowRef({
  rows: [{ id: 1, name: '第一行' }]
})

// 这里表达的是“换一份快照”，会触发依赖 snapshot.value 的视图更新
snapshot.value = {
  rows: [...snapshot.value.rows, { id: 2, name: '第二行' }]
}

console.log(deepState.value.rows.length)
console.log(snapshot.value.rows.length)

这段代码的重点不在于把所有对象都换成 shallowRef，而是先确认数据更新模型。如果组件需要频繁修改单个嵌套字段，并且希望这些字段自然驱动视图，普通 ref 或更细粒度的响应式状态往往更直观。

大型数据应按不可变快照替换

使用 shallowRef 时，最稳妥的约定是：读取当前快照，基于旧值构造新对象，再一次性写回 state.value。这样更新信号集中在根引用，调用方不必依赖深层代理是否存在。

import { shallowRef } from 'vue'

const tableState = shallowRef({
  version: 1,
  rows: []
})

function appendRows(incomingRows) {
  // 不直接 push 内部数组，先复制数组并创建新快照
  tableState.value = {
    version: tableState.value.version + 1,
    rows: [...tableState.value.rows, ...incomingRows]
  }
}

function replaceRows(nextRows) {
  // 外部数据已经准备好时，直接替换根引用即可触发更新
  tableState.value = {
    version: tableState.value.version + 1,
    rows: nextRows
  }
}

这里的“不可变”是应用层约定，不是 shallowRef 自动冻结对象。为了让约定更可靠，可以让数据生产函数只返回新快照，并在团队代码评审中禁止从组件深处直接修改 tableState.value.rows。

深层修改为什么不会自动触发

如果直接执行 state.value.rows[0].name = '新名称'，修改发生在浅层 ref 的内部对象上，Vue 没有为这个嵌套属性建立深层追踪，因此依赖 state.value 的效果不会因为这次赋值自动重新运行。这不是丢数据，而是更新边界和普通 ref 不同。

当确实需要在原对象上做一次批量深层修改时，可以在所有修改完成后调用 triggerRef()：

import { shallowRef, triggerRef } from 'vue'

const chartState = shallowRef({
  series: [{ name: '订单', values: [10, 20] }]
})

function patchChart() {
  // 这一批修改不会因为嵌套字段本身而自动通知视图
  chartState.value.series[0].values.push(30)
  chartState.value.series[0].name = '订单总量'

  // 所有深层修改完成后，只发出一次根级更新通知
  triggerRef(chartState)
}

triggerRef() 适合封装在明确的批处理函数里，不适合到处补调用。若每次字段修改都要手动触发，说明当前状态模型可能更适合普通 ref、reactive 或拆分后的多个状态。

不要把浅层状态随意嵌进深层响应式树

浅层 API 的边界最好停留在组件或状态模块的根部。如果把一个 shallowRef 管理的对象再塞进深层 reactive 树，读取路径可能同时出现 raw 对象和 proxy 对象，依赖追踪也会变得难以解释。尤其是需要比较对象身份时，不要假设“看起来相同”的嵌套对象一定可以用同一个引用比较。

更简单的组织方式是让状态模块返回一个清晰的快照引用：

import { reactive, shallowRef } from 'vue'

// rootState 管理轻量字段，largeSnapshot 单独管理大对象快照
const rootState = reactive({ loading: false })
const largeSnapshot = shallowRef({ items: [] })

function finishLoading(nextItems) {
  // 先替换大型快照，再更新轻量状态，两个边界各自清楚
  largeSnapshot.value = { items: nextItems }
  rootState.loading = false
}

如果对象来自第三方库、外部状态系统或组件实例，也应先确认它是否适合被 Vue 代理。浅层状态解决的是“不要递归转换这一整棵对象树”，不是自动修复所有第三方对象的身份和生命周期问题。

用最小示例检查三种更新结果

排查“为什么改了数据却没刷新”时，可以把测试缩小到三个动作：嵌套修改、替换 .value、显式 triggerRef()。不要先用复杂组件、异步请求和多个 watcher 叠加验证。

import { shallowRef, triggerRef, watchEffect } from 'vue'

const state = shallowRef({ count: 0 })

watchEffect(() => {
  // 这个效果依赖 state.value 的根访问
  console.log('render count:', state.value.count)
})

// 1. 深层改值：不会自动触发浅层 ref 的依赖
state.value.count += 1

// 2. 显式通知：让依赖在批量深改后重新运行
triggerRef(state)

// 3. 换根引用：shallowRef 的推荐更新方式
state.value = { count: state.value.count + 1 }

这个示例只用于理解更新边界，不把控制台输出当作固定运行结果。真实项目中应根据状态是否按快照替换、是否需要深层字段追踪以及是否存在外部状态管理，选择合适的 API。

常见问题

shallowRef 会不会让大型对象变成只读？

不会。它只改变响应式转换的深度，内部对象仍然可以被 JavaScript 修改；只是嵌套修改不会自动产生 Vue 的更新通知。

为什么替换 shallowRef.value 会触发更新？

因为 .value 本身是浅层 ref 的响应式边界。给它写入新引用时，依赖这个根值的计算属性、watch 或组件渲染可以收到通知。

深层修改后一定要调用 triggerRef 吗？

只有在你希望这次深层修改立即通知依赖时才需要。若改为创建新快照并替换 .value，通常不必额外调用 triggerRef()。

所有大对象都应该使用 shallowRef 吗？

不应该。若业务依赖嵌套字段的自然追踪，普通 ref 或拆分状态更容易维护；只有在根引用替换或显式批量通知符合业务模型时，浅层 ref 才有明确收益。