笙亿网络策划

Nuxt 3 如何优化 useFetch 数据预取避免水合延迟？

约 6 分钟读完 6 阅
文章导读
Nuxt 3 的 useFetch 在服务端预取数据本应减少客户端请求，但如果数据没有正确传递到客户端，浏览器会多一次请求，导致水合（Hydration）过程变慢。判断方法很简单：打开浏览器开发者工具的 Network 面板，查看页面初始 HTML 中是否包含 payload JSON 对象。如果未发现，则 useFetch 可能在服务端未执行或 pick、transform 等参数使用不当导致数
📋 目录
  1. Ⅰ 先确定问题：水合延迟是否由预取数据缺失引起
  2. Ⅱ 核心操作：让 useFetch 在服务端运行并缓存结果
  3. Ⅲ 谨慎使用 lazy 选项和 default 函数
  4. Ⅳ 精简 payload，避免 HTML 体积膨胀
  5. Ⅴ 验证优化效果：关注水合时间与请求次数
A A

先确定问题：水合延迟是否由预取数据缺失引起

Nuxt 3 的 useFetch 在服务端预取数据本应减少客户端请求，但如果数据没有正确传递到客户端，浏览器会多一次请求，导致水合（Hydration）过程变慢。判断方法很简单：打开浏览器开发者工具的 Network 面板，查看页面初始 HTML 中是否包含 payload JSON 对象。如果未发现，则 useFetch 可能在服务端未执行或 pick、transform 等参数使用不当导致数据丢失。

如果页面在客户端水合时出现明显闪烁或未渲染内容，可能是因为服务端预取数据未正确传递到客户端。检查方法是打开浏览器开发者工具的 Network 面板，查看页面初始 HTML 中是否包含 payload JSON 对象。若未发现，则 useFetch 可能在服务端未执行或 `pick`、`transform` 等参数使用不当导致数据丢失。

为避免水合延迟，应确保 useFetch 在服务端运行并缓存结果。可在 `useFetch` 中添加 `server: true`（默认即为 true），并利用 `key` 参数使数据在客户端复用相同缓存。同时配合 `useHead` 或 `

另外可以观察水合时的网络瀑布：若页面加载后紧接着出现与页面路径同名的 fetch 请求，说明服务端预取的数据没有被客户端复用。这种情况下优化方向很明确——确保服务端预取的数据能完整传递到 window.__NUXT__ 中。

核心操作：让 useFetch 在服务端运行并缓存结果

为避免水合延迟，应确保 useFetch 在服务端运行并缓存结果。可在 useFetch 中添加 server: true（默认即为 true），并利用 key 参数使数据在客户端复用相同缓存。同时配合 useHead 或 <script> 标签预加载数据。

具体来说，默认情况下 useFetch({ server: true }) 会在服务端执行请求，并将结果序列化到 HTML 的 __NUXT__ 中。客户端水合时直接从该对象读取，不再发起网络请求。但有一个常见遗漏：如果同一个请求在多个组件中使用，必须保证它们的 key 一致，否则客户端会认为没有缓存而重新请求。建议在 useFetch 中显式指定唯一的 key，例如 key: 'user-profile'，或者让 key 自动基于 URL 和配置生成（Nuxt 默认行为）。

Nuxt 3 如何优化 useFetch 数据预取避免水合延迟？

验证方式：查看初始 HTML 中是否存在 <script>window.__NUXT__={...}</script> 并包含请求数据。也可以在控制台执行 window.__NUXT__ 确认数据完整性。

谨慎使用 lazy 选项和 default 函数

过度使用 useFetch 的 lazy 选项（{ lazy: true }）会导致服务端不执行请求，完全依赖客户端获取数据，可能增加水合延迟。只有在数据对首屏不重要（如下方折叠内容）时才考虑启用。另外，使用 default 函数设置默认值时，应确保返回结构与实际数据一致，避免水合时出现类型不匹配。

如果启用 lazy，服务端会跳过请求，直接返回初始值（由 default 定义）。水合后客户端再触发 fetch，这个过程会延迟数据的呈现时间。一个稳妥的做法是：对首屏关键数据始终使用 { lazy: false }（默认），对可延迟加载的内容才开 lazy。同时，default 函数中返回的默认结构必须与真实数据兼容，例如有一个数组字段就返回空数组 []，否则 Vue 的响应式代理可能因类型突变导致更新异常。

精简 payload，避免 HTML 体积膨胀

一个常见错误是未使用 pick 或 transform 精简响应数据，导致 payload 过大，增加 HTML 体积和解析时间。建议在 useFetch 的 transform 中只保留必要字段，或使用 pick 指定返回属性。另一个坑是动态 key 未包含在 URL 中，导致客户端无法匹配缓存，从而重复发起请求。

Nuxt 3 如何优化 useFetch 数据预取避免水合延迟？

例如：

const { data } = await useFetch('/api/user', {
  pick: ['id', 'name', 'avatar']
})

或者使用 transform 进行更精细的加工：

const { data } = await useFetch('/api/user', {
  transform: (user) => ({
    id: user.id,
    displayName: `${user.firstName} ${user.lastName}`
  })
})

这样 HTML 中只包含需要的字段，减少字节数。注意动态 key 必须能够根据请求参数唯一标识，例如 key: 'user-' + id，否则客户端缓存键匹配不上会重新请求。

验证优化效果：关注水合时间与请求次数

验证优化效果的方法：在页面加载时，打开浏览器 DevTools 的 Performance 面板，记录水合过程（Hydration）的时间。同时检查 Network 中是否在客户端出现与 Page 加载路径相同的 fetch 请求。若没有或请求是缓存命中，则说明服务端预取数据已被正确利用。也可在控制台执行 window.__NUXT__ 查看数据是否完整。

如果水合时间明显缩短，且 Network 中没有重复请求，优化就生效了。反之则回头检查 key 是否一致、server 是否被意外设为 false，以及 pick 是否删除了必要字段导致数据不完整。注意 Performance 面板中 Hydration 的标记可能被异步组件分散，需要结合自定义标记或前端性能 API（如 performance.mark）更精确地测量。