数据类

callOnce

确保函数只执行一次（跨 SSR 和客户端 Hydration 都不会重复执行）。

function callOnce(
  key: string,                    // 唯一标识
  fn: () => Promise<void> | void, // 要执行的函数
  options?: { mode: 'render' | 'navigation' } // 执行模式
): Promise<void>

// 只执行一次（即使 SSR 和客户端都调用）
await callOnce('init-data', async () => {
  await initApp()
})

// 仅在首次渲染时执行
await callOnce('setup', async () => {
  await loadConfig()
}, { mode: 'render' })

// 仅在导航时执行
await callOnce('track', async () => {
  await trackPageView()
}, { mode: 'navigation' })

TIP

mode 默认为 'render' 表示只在首次渲染时执行。'navigation' 模式在每次导航时检查是否已执行

clearNuxtData

清除 useFetch/useAsyncData 的缓存数据。

function clearNuxtData(
  keys: string | string[] | undefined // 要清除的 key
): void

clearNuxtData('/api/users')        // 清除指定 key
clearNuxtData(['users', 'posts'])   // 清除多个
clearNuxtData()                      // 清除所有

v4.4+ 会将数据重置为初始值而非 undefined。

INFO

️ 清除数据后 依赖该数据的组件会重新触发请求（如果使用了 immediate: true）

refreshNuxtData

刷新 useFetch/useAsyncData 的数据（重新发起请求）。

function refreshNuxtData(
  keys: string | string[] | undefined // 要刷新的 key
): Promise<void>

await refreshNuxtData('/api/users')        // 刷新指定 key
await refreshNuxtData(['users', 'posts'])    // 刷新多个
await refreshNuxtData()                      // 刷新所有

实际应用：手动刷新数据

const { data } = await useFetch('/api/posts')

async function handleUpdate() {
  await updatePost(newPost)
  await refreshNuxtData('/api/posts') // 更新后刷新列表
}

refreshCookie

从浏览器刷新 Cookie 值（将浏览器最新的 Cookie 同步到 Vue 响应式系统）。

function refreshCookie(
  keys: string | string[] // Cookie 名称
): void

refreshCookie('auth-token')
refreshCookie(['auth-token', 'session-id'])

使用场景

当外部代码（如第三方库）修改了 document.cookie，Nuxt 的响应式 Cookie 不会自动感知，需要手动刷新：

const token = useCookie('auth-token')

// 第三方 SDK 修改了 cookie
thirdPartyAuth.setToken(newToken)

// 手动同步
refreshCookie('auth-token')
console.log(token.value) // 现在是最新的值

TIP

refreshCookie 仅在客户端有效 服务端总是读取最新的 Cookie 值