toRaw 是 Vue 3 中用于获取响应式对象原始目标的工具，适用于第三方库兼容、序列化、原型校验等场景，需注意仅对 Vue 响应式对象有效且不递归处理嵌套属性。
toRaw 是 Vue 3 响应式系统中用于“脱敏”的关键工具，它能快速获取被 reactive、ref 或 shallowRef 包裹后的原始对象，绕过 Proxy 代理层。在集成如 ECharts、Three.js、Canvas API 或某些依赖直接属性访问/原型链的第三方库时，它常是解决“数据不可读”“方法调用失败”“实例校验不通过”等兼容性问题的首选方案。
什么时候必须用 toRaw？
以下情况直接使用响应式对象会出错，需先 toRaw：
- 第三方库内部执行
obj.constructor === Object或Object.prototype.toString.call(obj) === '[object Object]'校验——Proxy 对象不满足原生类型判断； - 库尝试遍历
Object.keys()或for...in——Proxy 若未显式拦截 ownKeys，可能返回空或不全； - 需要将响应式对象传给
JSON.stringify、structuredClone或服务端接口——Proxy 无法被序列化； - 调用依赖 this 指向或原始原型的方法（如某些类实例的
init()、render()）——Proxy 会改变 this 绑定或丢失原型链。
toRaw 的正确用法与常见误区
toRaw 接收一个响应式对象（或 ref），返回其原始目标对象；若传入非响应式值，则原样返回。它不是解包函数，也不递归处理嵌套响应式属性：
-
✅ 正确用法：
const raw = toRaw(proxyObj)；对 ref 需先取 .value：const raw = toRaw(myRef.value)； -
❌ 常见误区：对嵌套响应式字段（如
proxyObj.items）直接 toRaw(proxyObj.items) 才有效，不能只对顶层调用一次就认为全部“还原”； - ⚠️ 注意边界：toRaw 只对 Vue 创建的响应式对象有效（reactive、readonly、shallowReactive 等），对普通对象、数组或手动 new Proxy 的对象无作用，也不会抛错。
实战：ECharts 初始化失败的典型修复
ECharts 的 setOption 内部会深度校验配置对象结构，若传入 reactive 包裹的 option，可能因 Proxy 导致 key 判断异常或 getter 触发副作用：
错误写法：
const chartOption = reactive({ title: { text: '销量趋势' }, series: [{ type: 'line', data: [10, 20, 15] }] });<br>chartInstance.setOption(chartOption); // ❌ 可能报错或渲染异常修复写法：
const chartOption = reactive({ /* 同上 */ });<br>// 仅在传入 ECharts 时转为原始对象<br>chartInstance.setOption(toRaw(chartOption)); // ✅ 安全传递注意：后续若需响应式更新，仍要操作 chartOption 本身（而非 toRaw 返回值），因为 toRaw 返回的是只读快照，修改它不会触发视图更新。
替代方案对比：markRaw vs toRaw
两者用途不同，别混用：
-
markRaw：标记一个对象“永远不要转为响应式”，适用于初始化阶段，比如创建第三方类实例（
new Three.Scene()）后，避免被 reactive 意外代理； - toRaw：运行时“临时解包”，适用于已响应式、但当前调用场景要求原始对象的时刻；
- 二者可配合：先 markRaw 创建实例，再用 reactive 包裹其容器属性，必要时 toRaw 提取原始实例使用。
