页面白屏 + Invalid prop: type check failed for prop "options"?原来是 script setup 的 ref

页面打开一片空白,控制台只有一行很克制的警告:Invalid prop: type check failed for prop "options". Expected Array, got Object。你检查了数据明明是个数组,为什么模板里就变成了 Object?这篇文章从一次真实的 Vue 3 排障出发,讲清楚 script setup 里 ref 自动解包到底解到了哪一层。

一、现象:明明返回数组,模板却提示 Object

业务里常见的一种组织方式是"Hook 组合式函数":把一堆逻辑(查询、分页、筛选状态)收进 useSomething(),页面里解构出来直接用。

某个页面结构大致是这样------一个外层 view 引用了组合函数和子组件:

vue 复制代码
<script setup>
const { baseOptions, tableData, loading } = useSomething();
</script>

<template>
  <MySelect :options="baseOptions" />
  <MyTable :data-source="tableData" loading="loading" />
</template>

子组件里按常规方式声明了 prop 类型:

vue 复制代码
<script setup>
defineProps({
  options: { type: Array, required: true },
  dataSource: { type: Array, default: () => [] },
});
</script>

结果一运行,页面白屏,控制台冒出:

typescript 复制代码
Invalid prop: type check failed for prop "options". Expected Array, got Object

诡异的是,你在 Hook 里把数据 log 出来,它明明就是 [] 或一个真实数组。

二、根因:嵌套对象里的 ref 不会被自动解包

问题出在 Vue 3 的 ref 解包机制 在 script setup 中的边界上。

Vue 3 有个便利特性:在模板里,顶层 ref 会自动解包 ------你写 {{ count }},哪怕 count 是个 ref(0),渲染的也是 0 这个值,不用写 count.value。这是很多人爱 script setup 的原因之一。

但请注意关键字:顶层(top-level) 。只有 script setup 顶层的绑定、且是解构出来的顶层变量,才会在模板里被自动解包。

如果组合函数返回的是嵌套对象,情况就完全不同了:

js 复制代码
export function useSomething() {
  const baseOptions = ref([]);
  const tableData = ref([]);
  return { baseOptions, tableData }; // ref 被包在对象里
}

页面里这样解构:

js 复制代码
const result = useSomething();
// 模板里用 result.baseOptions

此时 result.baseOptions 是一个 ref 对象,而不是数组。模板中 ref 的解包只发生在"顶层绑定"上------

  • const { baseOptions } = useSomething() 解构到顶层 → template 自动解包,正常;
  • const result = useSomething() 用 result.baseOptions → 不自动解包,你拿到的是 ref 对象。

上面那个报错的例子,很可能是把 Hook 的返回值整体接管后,把 ref 包装对象直接丢给了子组件 prop:

js 复制代码
const state = useSomething(); // 嵌套对象里全是 ref

于是 :options="state.baseOptions" 传过去的实际上是个 Ref 对象,而 prop 声明是 Array,类型校验自然炸了------数据确实有,但它不是你以为的形状 。页面空白,是因为模板里拿着 ref 对象去当数组用(length、迭代都取不到正确值),渲染不出来。

三、修复:顶层解构 + 正确的解包位置

修复方式很直接,就是让 ref 落到能被自动解包的位置。

方案 A:顶层解构(最推荐)

把组合函数返回值里你需要的 ref,在 script setup 顶层直接解构出来:

vue 复制代码
<script setup>
// 顶层解构 → 模板自动解包
const { baseOptions, tableData, loading } = useSomething();
</script>

<template>
  <MySelect :options="baseOptions" />
  <MyTable :data-source="tableData" :loading="loading" />
</template>

这样 baseOptions 就是被解包后的数组,prop 类型校验通过,页面恢复显示。

关于"为什么顶层解构的解包能生效"要理解一点:Vue 编译 script setup 的模板时,baseOptions 已成为顶层绑定,模板访问它会走 unref(),把 ref 解开。而 state.baseOptions 这种"属性访问"不会被编译器特殊处理。

方案 B:Hook 内部若必须整体返回对象,用 toRefs 摊平

如果你确实想整体接管返回值(比如在一个函数里统一维护状态),可以这样处理,让每个字段仍是可解包的 ref:

js 复制代码
import { ref, toRefs } from 'vue';

export function useSomething() {
  const stateRef = reactive({ baseOptions: [], tableData: [] });
  return toRefs(stateRef); // 每个都是 ref
}

但在模板里直接 result.baseOptions 依然不会自动解包------除非再解构一层。所以最省心的还是方案 A:在页面 script setup 顶层解构需要传给子组件 prop 的 ref。传 prop 前,让数据要么已是原始值,要么已是可解包的顶层绑定。

四、另一个相关乌龙:Prop 类型自己写翻了

这次排障还带出一个容易和上面混淆的小坑:type: Array 写成了 Array,但实际传的本来就是数组,却仍报错。

常见原因不是解包,而是类型字符串写错 或默认值/工厂函数写错:

js 复制代码
defineProps({
  options: { type: Array, default: [] }, // ❌ 引用类型默认值必须是工厂函数
});

defineProps({
  options: { type: Array, default: () => [] }, // ✅ 正确
});

Vue 会警告"Props with type Object/Array must use a factory function to return the default value"。虽然报错文案不同,但同样会造成页面空白或渲染异常,排查时别漏掉这个更基础的点。

五、方法论:报错前先确认"数据的真实形状"

回看这次排障,最有价值的不是那行修复,而是定位思路:先确认你手里那个值,到底是什么。

  • 控制台 log 一下,看 typeof 和 Array.isArray------它到底是数组还是 ref 包装对象?
  • 看它来自哪里:是顶层解构出来的,还是从嵌套对象属性里取出来的?
  • 如果是嵌套对象,模板里它不会被自动解包,prop 拿到的就是一个 ref 对象。

把"引用怎么传的"和"Vue 在哪一层帮你解包"对上号,这类 Invalid prop 白屏问题通常五分钟内就能定位。

结语

script setup 的 ref 自动解包很爽,但它有明确的边界------只有顶层绑定才会被模板自动解包 。把 ref 塞进嵌套对象再整体传给子组件,就绕开了这个便捷机制,换来一串 Invalid prop 和一次白屏。

记住这句话:传 prop 之前,让数据是"被解包后的原始值"。你就能和大多数诡异的白屏说再见。

你在 Vue 3 里有没有被 ref 解包坑过?欢迎聊聊你遇到过的"Expected X, got Y"查因经历。

相关推荐
aleimu2 分钟前
Windows 11 右键打开 Cmder 2.0:从找不到菜单到默认使用 Cmder
前端·人工智能·后端
tryCbest4 分钟前
Vue系列——第 20 篇:Vue Router 4——路由管理完全指南(上)
前端·javascript·vue.js
feixing_fx5 分钟前
原始类型与引用类型:赋值时到底复制了什么
开发语言·前端·javascript·前端框架
一条破秋裤29 分钟前
【1115】【多线程】【笔记】
前端·chrome·笔记
黑十29 分钟前
FDE 怎么快速搭一个可演示页面?最小前端方案
java·大数据·前端·数据库·人工智能
Funlang32 分钟前
在 Windows 95 上写前端
前端·javascript·windows
cidy_981 小时前
python第7课. 输入与输出
前端
小龙66661 小时前
给 Agent 一张地图,而不是一座迷宫:前端 monorepo 目录结构重构实录
前端·agent
樊小肆1 小时前
agent 不报错才最吓人:自研编码工具半年,我踩了 10 个"看着正常"的运行时坑
前端·人工智能·agent
鲸鹏芯海微电子科技上海有限公司1 小时前
手机直连卫星,射频前端到底要解决什么?
前端·后端