上周帮同事看一个后台的订单筛选页。左边一列条件:关键词、订单状态、下单时间;右边是表格和分页。他为了少写几个 form.,把表单对象解构了一下:

const form = reactive({ keyword: "", status: "all" });
const { keyword } = form;
const list = computed(() => filterOrders(form.keyword, form.status));

模板里输入框绑的是解构出来的 keyword,列表用的是 form.keyword。结果是:输入框里的字确实在变,但接口参数永远是空字符串,列表一动不动。他先怀疑 computed 不工作,改成普通函数调用,还是不变;又怀疑请求层缓存了,清缓存也没用。

问题就在那一行解构上:它取出来的是一次性的字符串,不是会跟着变化的值。这篇就把这件事讲透,顺手把 Vue 3 组合式 API 里最容易踩的几个点(ref 和 reactive 的选择、模板自动拆包、computed 的缓存、watch 的触发时机、v-if 与 v-for 的优先级)一起理清楚。

先说明范围:本文按 Vue 3 加 <script setup> 的组合式 API 讲,不把选项式 API 当主线。选项式写法在大量老项目里还在用,能读懂就行;新写代码时,组合式更接近普通 JavaScript,逻辑拆分和复用也更自然。文中示例默认运行在 Vite 创建的 Vue 3 项目里,版本差异比较大的地方会单独标出来。

先把这条故障链走通

别急着改代码,先弄清楚为什么解构会断掉。Vue 的响应式依赖 Proxy:你访问 form.keyword 时,会触发代理对象的读取拦截,当前正在执行的渲染函数或 computed 就被记成这个属性的订阅者。之后给 form.keyword 赋值,订阅者收到通知,重新执行。

一次输入之后实际发生了什么
输入框写入局部变量 keyword
form.keyword 没有变化
computed 的依赖没有被触发
列表仍然渲染旧数据

解构那一下,代理的读取拦截确实触发了,但拿到的是当时那个字符串的副本。字符串是原始值,按值复制,之后 form.keyword 变成什么,都跟这个局部变量没有关系。更糟的是 v-model 绑在局部变量上,用户的输入全都写进了这个孤立的值里,源对象那边一直没被改过。

修复方式有三种,按改动量从大到小排:模板里老老实实写 form.keyword;用 toRefs 把字段转成 ref;用带 getter 和 setter 的 computed 包一层。前两种见得多,第三种适合要对值做额外处理(比如统一转小写)的场景。

官方文档明确写了 reactive 对象解构会丢失响应式,这不是版本 bug。团队里如果有统一约定,最省事的一条是:表单整体用一个 reactive 对象往下传,模板里一律写 form.xxx,只有单个独立状态才用 ref。

ref 和 reactive 到底怎么选

这两个东西经常被讲成「都行,看习惯」,其实它们的边界很清楚。先把各自的行为记准,再谈选择。

ref:脚本里要写 .value,模板里自动拆

ref 是一个带 value 属性的容器,里面可以放任何类型,包括对象和数组。它最大的好处是整体替换安全:换掉 .value 指向的对象,依赖照常更新。

const count = ref(0);
count.value += 1;              // 脚本里必须写 .value

const list = ref([]);
list.value = await fetchOrders();   // 整体换掉,视图照样更新

模板里不需要写 .value:

<span>共 {{ count }} 条</span>
<input v-model="keyword">

这种自动拆包只发生在模板的顶层绑定上。<script setup> 里声明的 ref,模板可以直接当普通值用;但如果你把它塞进另一个普通对象再带进模板,就要看那个对象是不是响应式的。reactive 对象的属性如果是 ref,访问时会自动拆包:

const count = ref(0);
const state = reactive({ count });

state.count += 1;              // 可以直接改,不用 .value
console.log(state.count);      // 1,读到的是数字,不是 ref

这里的坑在于:state.count 读出来是数字,你就没法再写 state.count.value,运行时是 undefined。所以把一个 ref 塞进 reactive 之后,就当它是普通字段用,别在两种写法之间来回切。

reactive:整体替换就断链

reactive 返回的是对象的代理,用起来像普通对象,但不能把变量重新赋成一个新对象,那样模板还连着旧代理:

let state = reactive({ list: [], page: 1 });

// 页面不会更新,模板订阅的还是原来的代理
state = { list: [], page: 1 };

// 想换内容,改属性或者用 Object.assign
Object.assign(state, { list: [], page: 1 });

数组也一样。用 reactive([]) 时,state = [] 会断链,得用 splice(0) 或 length = 0 清空。如果这个数组需要频繁整体替换(比如每次请求回来都换一份),一开始就该用 ref,省得后面反复解释。

还有一层开销要提:reactive 是深层的,嵌套对象也会被代理。一个装了几万行订单的大数组放进 reactive,创建代理和后续比较的成本都不低。这种只读的大块数据用 shallowRef 装,或者用 markRaw 标成不需要响应式。

判断标准:谁负责替换,谁负责改字段

选 ref 的场景

基础类型(字符串、数字、布尔);需要整体替换的对象或数组;要作为参数传给组合式函数再被返回;需要跨组件传递并且可能被替换。代价是脚本里到处写 .value,读起来略吵。

选 reactive 的场景

一张表单、一组筛选条件、一个面板的多个开关。字段固定、只做局部修改、基本不整体替换。模板里少写 .value,代价是解构会丢响应式、整体赋值会断链。

我自己的习惯:能整体换掉的数据用 ref,字段级更新的表单用 reactive。同一个项目里两种风格混着用不算问题,但同一个模块里别一会儿 ref 一会儿 reactive,接手的人要来回切换思路。

computed 和 watch:依赖到底是谁在收集

很多人从 React 转过来,最不适应的就是这里:React 要你手写依赖数组,写漏了就是 bug;Vue 不用写,读取时自动记。方便归方便,它只认「执行期间同步读到的响应式属性」,别的东西一概不算。

computed 的缓存靠依赖收集

const orders = ref([]);
const keyword = ref("");

const filtered = computed(() =>
  orders.value.filter((o) => o.customer.includes(keyword.value.trim()))
);

第一次读取 filtered.value 时,getter 执行,期间读了 orders.value 和 keyword.value,这两个 ref 的依赖表里就记下了这个 computed。任意一个变化,computed 被标脏,下次读取时重新计算。没人读它的时候,它不会主动算,这也是缓存的一部分。

几个容易出错的点:

  • getter 里不能做异步请求,也不该改别的状态。它的定位是「根据已有状态算出一个值」,有副作用就说明位置放错了。
  • 依赖必须是响应式的。如果 getter 里读的是一个普通变量,或者前面解构出来的副本,算一次之后就永远是那个结果。
  • 每次重新计算返回的对象都是新引用。拿 computed 返回的对象直接去 watch,回调会随着每次重算触发,这通常是想要的,但别误以为它只在字段变化时触发。
  • 缓存不等于节流。输入框每敲一个字都会重算,列表大、过滤逻辑重的时候,卡顿是真实存在的。这种场景把重活挪到 watch 里加防抖,或者干脆交给后端。

需要可写的派生值,用带 getter 和 setter 的写法,别在 watch 里反向同步,那样容易出现来回触发:

const fullName = computed({
  get: () => `${form.first} ${form.last}`.trim(),
  set(v) {
    const [first, last] = v.split(" ");
    form.first = first || "";
    form.last = last || "";
  }
});

watch 拿得到旧值,watchEffect 拿不到

watch 要显式写监听源,回调里有新值和旧值,默认不立即执行:

watch(keyword, (next, prev) => {
  console.log("从", prev, "变成", next);
});

// 多个来源,回调参数是两个数组
watch([keyword, status], ([kw, st], [oldKw, oldStatus]) => {
  console.log(kw, st, oldKw, oldStatus);
});

监听对象的某个属性,写成 getter,别直接把整个对象丢进去再开 deep:

watch(() => form.status, (next) => {
  page.value = 1;
});

watchEffect 不写源,函数体里读到什么就订阅什么,而且会立刻执行一次:

watchEffect(() => {
  document.title = (form.keyword || "全部订单") + " - 订单管理";
});

它拿不到旧值,适合「状态变了就同步到外部」的简单场景,比如改标题、写本地存储。有个细节必须记牢:第一个 await 之后读到的响应式属性不会被收集。所以异步逻辑要用 watch 显式指定源,别指望 watchEffect 帮你猜。

在 <script setup> 里创建的 watchEffect 会随组件卸载自动停止,watch 也是。手动调用返回的停止函数只在需要提前关闭时才有意义,比如条件满足后不再监听。

flush 决定回调在 DOM 更新的前面还是后面

默认 flush: "pre",回调在组件重新渲染之前执行,这时候 DOM 还是旧的。要读新渲染出来的节点,改成 "post":

watch(visible, async (open) => {
  if (!open) return;
  await nextTick();               // 等这一轮 DOM 更新结束
  console.log(dialogRef.value?.clientHeight);
}, { flush: "post" });

flush: "sync" 是同步触发,每次源变化立刻执行,多个源同时变就会执行多次,性能差,只在极少数需要「立刻」的场景用。大部分「我明明改了值却拿到旧 DOM」的问题,都是默认的 pre 造成的,改成 post 或者加一个 nextTick 就解决了。

顺带说一句和 React 的差别:React 用依赖数组告诉框架什么时候重跑,Vue 靠运行时读取自动收集。两边都不会替你检查依赖是否完整,改完之后还得自己确认那个值有没有被读到。

模板里的三个高频坑

v-if 和 v-for 别放在同一个元素上

Vue 3 里 v-if 的优先级高于 v-for,写在同一个元素上时,v-if 的表达式先求值,这时候循环变量还不存在:

<!-- 会报 item is not defined -->
<li v-for="item in list" :key="item.id" v-if="item.visible">{{ item.name }}</li>

要么把 v-for 提到外层 <template>,要么先用 computed 过滤好再循环。后者更好,列表的过滤规则集中在一处,模板里只剩渲染。

const visibleList = computed(() => list.value.filter((i) => i.visible));

此外要清楚 v-if 和 v-show 的区别:前者切换时销毁重建,子组件里的输入内容、滚动位置、内部状态都会丢;后者只是切 display,状态留着。表单和带内部状态的组件,频繁显隐用 v-show 更稳。

v-for 的 key 用 index,删一行就串位

下面这种写法在静态展示里看不出问题,一旦行里有输入框就会暴露:

<tr v-for="(row, index) in rows" :key="index">
  <td>{{ row.orderNo }}</td>
  <td><input v-model="row.remark"></td>
</tr>

删除第二行之后,第三行顶上来,index 从 2 变成 1,Vue 认为这还是原来那个节点,于是复用了它,输入框里的内容跟着位置一起串了。把 key 换成数据自己的唯一 id,Vue 才能正确判断哪些节点该留、哪些该删。

如果列表会排序、翻页、局部刷新,key 更必须稳定。用随机数或者时间戳当 key 也不对,那样每次渲染都会重建所有节点。

v-model 在原生元素上就是语法糖

v-model 在 input 上等于 :value 加一个 input 监听,所以它只能绑到能读写的响应式源。几个修饰符要记清楚:

  • .trim 去掉首尾空格,适合搜索框和账号输入。
  • .number 尝试转成数字。注意输入框被清空时会拿到空字符串,因为转换失败保留了原值,别默认它是 0,后端校验要单独处理。
  • .lazy 从 input 事件改成 change 事件,输入过程中不更新,失焦或回车才写回。

复选框绑数组、单选绑单值、下拉多选绑数组,这些是原生元素的规则,和框架无关。组件上的 v-model 走的是另一套约定,需要 modelValue 和 update:modelValue,下一篇细讲。

生命周期在组合式 API 里长什么样

<script setup> 顶层的代码相当于在 setup 阶段执行,这时候组件实例已经有了,但 DOM 还没挂到页面上。所以想拿元素尺寸、初始化依赖 DOM 的库,一律放 onMounted:

onMounted(() => {
  chart = createChart(elRef.value);
});

更重要的是收尾。watch 和 watchEffect 会自动停,但你手动注册的监听、定时器、WebSocket、请求不会:

onMounted(() => {
  window.addEventListener("resize", onResize);
  timer = setInterval(poll, 5000);
});

onUnmounted(() => {
  window.removeEventListener("resize", onResize);
  clearInterval(timer);
  controller?.abort();
});

卸载回调执行时组件已经不在页面上,DOM 也被移除了,所以别在这里做「再读一次节点」的操作。配合 keep-alive 时,页面缓存不会触发卸载,切回来走的是 onActivated,这种页面里定时器要在 onDeactivated 里停掉,否则后台一直在跑。

「切换页面后接口还在返回,报 Cannot read properties of null」这类线上报错,几乎都是卸载时没取消请求。请求回来时组件已经销毁,赋值那一步照样执行,只是视图没了。

完整场景走查:一个筛选页从能跑到能上线

需求本身很常见:订单筛选页,三个条件(关键词、状态、日期区间),关键词输入后停顿 300 毫秒再请求,切条件时页码回到第一页,快速切换不能让旧结果覆盖新结果,离开页面要取消未完成的请求,表格里的备注可以直接编辑。上线后还要支持从别的页面带着筛选条件跳进来。

第一版通常是这样的,功能都能跑,问题埋在细节里:

const form = reactive({ keyword: "", status: "all", dateRange: [] });
const { keyword } = form;
const page = ref(1);

watch(keyword, async (kw) => {
  const res = await fetch("/api/orders?keyword=" + kw + "&page=" + page.value);
  rows.value = (await res.json()).list;
});

上线前后陆续暴露的问题,按出现顺序:

  1. 输入框有字,请求参数是空的。就是开头那条,解构断了响应式。
  2. 每敲一个字发一次请求,中文输入法拼一个词能发四五次。没有防抖,也没有判断输入法是否还在组合状态。
  3. 先输「A」再输「AB」,AB 的结果先回来,A 的结果后到,把列表盖回 A。没有请求序号,也没有取消。
  4. 从第三页切到「已发货」,请求带的是 page=3,出现空白页。切条件时没有重置页码。
  5. 表格里编辑了第二行的备注,删除第一行之后,备注跑到了别的行上。key 用了 index。
  6. 切到别的页面,控制台开始报 null。请求没取消,回调还在操作已经卸载的组件。

改法是把筛选逻辑收进一个组合式函数,状态、请求、清理集中在一处,组件里只留渲染:

import { ref, reactive, computed, watch, onUnmounted } from "vue";

export function useOrderFilters() {
  const form = reactive({ keyword: "", status: "all" });
  const page = ref(1);
  const pageSize = ref(20);
  const rows = ref([]);
  const total = ref(0);
  const loading = ref(false);
  const error = ref("");

  let timer = null;
  let controller = null;
  let seq = 0;

  const query = computed(() => ({
    keyword: form.keyword.trim(),
    status: form.status === "all" ? "" : form.status,
    page: page.value,
    pageSize: pageSize.value
  }));

  // 条件变了就回到第一页,创建顺序在请求监听之前
  watch(() => [form.keyword, form.status], () => {
    page.value = 1;
  });

  async function run(filters) {
    const mine = ++seq;
    controller?.abort();
    controller = new AbortController();

    const qs = new URLSearchParams({
      keyword: filters.keyword,
      page: String(filters.page),
      pageSize: String(filters.pageSize)
    });
    if (filters.status) qs.set("status", filters.status);

    loading.value = true;
    try {
      const res = await fetch("/api/orders?" + qs.toString(), {
        signal: controller.signal
      });
      if (!res.ok) throw new Error("HTTP " + res.status);
      const data = await res.json();
      if (mine !== seq) return;        // 回来晚的请求直接丢弃
      rows.value = data.list;
      total.value = data.total;
    } catch (err) {
      if (err.name !== "AbortError") error.value = err.message;
    } finally {
      if (mine === seq) loading.value = false;
    }
  }

  watch(query, (filters) => {
    clearTimeout(timer);
    timer = setTimeout(() => run(filters), 300);
  }, { immediate: true });

  onUnmounted(() => {
    clearTimeout(timer);
    controller?.abort();
  });

  return { form, page, pageSize, rows, total, loading, error };
}

几处关键对应着上面的问题。解构没了,query 里读的是 form 的属性,任何输入都会让 query 重算。防抖放在 watch 里,而不是每个输入事件里现场创建,否则每次都是新的定时器,旧的永远清不掉。序号 seq 在发请求前自增,回调回来先比对,对不上就丢,乱序覆盖从根上没了。页码重置的 watch 写在请求监听之前,两个都是 pre 阶段、按创建顺序执行,同一次输入只会产生一个请求。卸载时清定时器并中断请求,控制台那串 null 报错也消失了。

模板那边把 :key="row.id" 补上,备注输入不再串行。最后加上地址栏同步,只做一小段,在筛选条件变化时替换 query:

const route = useRoute();
const router = useRouter();

onMounted(() => {
  form.keyword = String(route.query.keyword || "");
  form.status = String(route.query.status || "all");
  page.value = Number(route.query.page) || 1;
});

watch(() => ({ ...query.value }), (q) => {
  router.replace({
    query: {
      keyword: q.keyword || undefined,
      status: q.status || undefined,
      page: String(q.page)
    }
  });
});

注意这里的初始化顺序:先读地址栏再打开请求监听,否则会先发一次空条件请求,再发一次带条件的,页面上能看到列表闪两下。

还有一个没写进代码的点:中文输入法拼写过程中 input 事件也在触发,用户输得慢时,300 毫秒防抖兜不住,会拿半截拼音去查。严格一点的做法是在组合期间跳过请求,或者给搜索框加 .lazy。

错误现象对照

下面这些现象都来自真实项目,先看「看到什么」,再看「其实是什么」。凡是「数据变了但页面没变」的,八成都是响应式链断了,而不是框架没更新。

现象真实原因第一步查什么
输入框有字,列表和请求参数都不变 从 reactive 对象解构出的是普通值,已经和代理断开 搜代码里的解构语句,确认 v-model 绑的是不是 form 的属性
改了数据,视图不刷新,控制台打印却是新值 整个 reactive 对象被重新赋值,模板还连着旧代理 搜 form =、state = 这类整体赋值,改成改属性或 Object.assign
computed 怎么都不重算 依赖是普通变量、解构副本或 props 的拷贝,不是响应式源 在 getter 里临时打印依赖,确认读到的确实是 ref 或 reactive 属性
watch 回调里读到的 DOM 是旧的 默认 flush 为 pre,回调在组件更新之前执行 看回调是否依赖 DOM,改成 flush: "post" 或加一个 nextTick
删除列表中间一行,下面几行的输入内容串位 key 用了 index,节点被复用,内部状态跟着位置走 检查 v-for 的 :key 是不是数据的稳定唯一 id
切换筛选条件后连发两个请求,列表闪一下 重置页码和查询各触发了一次副作用,或者初始化顺序不对 打开 Network 看请求次数和参数,确认两个 watch 的创建顺序与依赖范围
离开页面后接口仍返回,控制台报 null 请求没有取消,回调继续操作已卸载的组件 查 onUnmounted 里有没有 abort、clearTimeout

边界与代价

组合式 API 写起来顺手,但它不是没有成本。下面几种情况要提前想清楚,不然代码会越长越难改。

  • 组件里超过五六个 watch 就开始失控。回调之间有先后顺序、有互相改值,这时候该抽组合式函数,一个函数只管一摊事,把顺序固定在文件里。
  • reactive 的深层代理在大数据上有真实开销。几万行的表格数据如果整块塞进去,创建代理和更新检查都要时间。只读数据用 shallowRef,或者请求回来直接放进一个普通数组,用 ref 整体替换。
  • computed 没有节流能力。搜索建议这种每次输入都要重算的场景,只靠它扛不住,重逻辑必须自己控制频率。
  • 模块级单例的 reactive 是隐式全局状态。在一个文件里 export const store = reactive({...}),任何组件都能改,改了谁都看不出来。小项目够用,模块一多就需要明确的写入入口,这部分留到状态管理那篇。
  • 团队里如果还有大量选项式 API 的老组件,混着写会让新人分不清 this.xxx 和 ref 的边界,迁移尽量按整个组件推进。
  • 自动依赖收集不等于「不用想依赖」。它只收集同步执行期间读到的响应式属性,异步、解构、普通对象里的值都不会被记上。写的时候还是要问自己一句:这个分支真的读到了那个响应式源吗。

小结与练习

把这篇的要点压成四句:响应式靠访问属性来收集依赖,所以解构、展开、整体赋值都会把链弄断;ref 适合会整体替换的数据,reactive 适合字段级更新的表单;computed 有缓存但没节流,watch 有旧值,watchEffect 自动收集但异步之后就断了;收尾比初始化更容易漏,定时器、监听、请求都要在卸载时清掉。

数据层:选对容器,ref 负责替换,reactive 负责改字段,别在两者之间来回转换。
派生层:computed 只算值,watch 管副作用,重活加防抖,读 DOM 用 post。
视图层:key 用稳定 id,v-if 与 v-for 不共用元素,v-model 只绑真正响应式的源。
生命周期:挂载时初始化,卸载时清理,切页不清理的定时器迟早会出问题。

下面几条今晚就能自己验证,不需要业务代码:

  1. 用 Vite 建一个 Vue 3 项目,写一个 reactive 表单并解构其中一个字段绑 v-model,在 computed 的 getter 里放一个计数器,确认输入时计数器不涨;改成不解构,再输入,确认计数器开始涨。
  2. 把上一步改成 toRefs 写法,模板只改绑定名,确认行为和不懈构一致。再试着把 form 整体赋成一个新对象,观察视图是否更新。
  3. 写两个 watch 监听同一个 v-if 控制的弹窗显示状态,一个用默认 pre,一个用 post,两个都打印节点数量,看差异。
  4. 做一个小列表,每行一个输入框,先用 index 当 key,输入内容后删除中间一行,看内容是不是串位;换成 id 再试一次。
  5. 在 onMounted 里开一个每两秒打印一次的定时器,切换路由十次,看控制台打印频率有没有翻倍;补上 onUnmounted 的清理再对比。

下一篇讲Vue 组件通信。原因是这一篇里所有状态都还留在一个组件内部,而真实页面是一棵树:筛选页要拆成工具栏、表格、分页,弹窗要拆成外壳和内容。一旦拆开,数据怎么往下传、子组件怎么把动作报上去、跨了三层又不想一层层传,这些问题会立刻顶上来。先把单组件内的响应式用熟,再学组件之间怎么说话,顺序才对得上。基础部分如果还不熟,可以顺手翻一下对象与原型链和模块,Vue 的响应式代理和组合式函数的导出方式,都建立在那两篇的基础上。