其他

setResponseStatus

设置 HTTP 响应状态码（仅服务端可用）。

function setResponseStatus(
  event: H3Event,        // 请求事件
  statusCode: number,    // 状态码
  statusMessage?: string // 状态消息
): void

// server/api/created.ts
export default defineEventHandler((event) => {
  setResponseStatus(event, 201)
  return { created: true }
})

// 带状态消息
export default defineEventHandler((event) => {
  setResponseStatus(event, 429, 'Too Many Requests')
  return { error: '请求过于频繁' }
})

常用状态码

状态码	含义	典型场景
200	成功	GET 请求返回数据
201	已创建	POST 创建资源成功
204	无内容	DELETE 成功
301	永久重定向	URL 变更
302	临时重定向	临时跳转
400	请求错误	参数验证失败
401	未认证	缺少登录凭证
403	禁止访问	权限不足
404	未找到	资源不存在
429	请求过多	速率限制

TIP

在 API 路由中使用 throw createError({ statusCode }) 也可以设置状态码 setResponseStatus 更适合成功响应

---

setPageLayout

动态设置页面布局，通常在路由中间件中使用。

function setPageLayout(
  layout: string | false  // 布局名称，false 表示无布局
): void

// app/middleware/set-layout.ts
export default defineNuxtRouteMiddleware((to) => {
  const isMobile = useIsMobile()
  setPageLayout(isMobile.value ? 'mobile' : 'default')
})

// 根据路由前缀选择布局
export default defineNuxtRouteMiddleware((to) => {
  if (to.path.startsWith('/admin')) {
    setPageLayout('admin')
  } else if (to.path.startsWith('/embed')) {
    setPageLayout(false) // 无布局
  }
})

INFO

️ setPageLayout 必须在中间件中调用 在组件的 setup 中调用无效

---

updateAppConfig

运行时更新应用配置（App Config）。

function updateAppConfig(
  config: DeepPartial<AppConfig>  // 要合并的配置
): void

const appConfig = useAppConfig()

// 更新主题配置
updateAppConfig({
  theme: {
    primaryColor: '#ff0000',
    darkMode: true,
  },
})

// 运行时切换主题
function toggleDark() {
  updateAppConfig({
    theme: { darkMode: !appConfig.theme.darkMode },
  })
}

TIP

updateAppConfig 是浅合并（shallow merge） 不会深度合并嵌套对象

---

reloadNuxtApp

强制重新加载 Nuxt 应用（刷新页面）。

function reloadNuxtApp(options?: {
  path?: string    // 重新加载后导航到的路径
  force?: boolean  // 强制刷新（绕过缓存）
}): void

// 重新加载当前页面
reloadNuxtApp()

// 重新加载并跳转到新路径
reloadNuxtApp({ path: '/new-page' })

// 强制刷新（绕过浏览器缓存）
reloadNuxtApp({ force: true })

适用场景

场景	说明
切换语言后	重新加载以应用新的 i18n 配置
更新关键配置	Runtime Config 变更后需重新加载
登录状态异常	强制刷新清除可能的状态错误
版本更新	检测到新版本后强制用户刷新

INFO

️ reloadNuxtApp 会导致页面完全刷新 所有状态丢失。仅在必要时使用

---

onPrehydrate

在 Hydration 前执行代码（高级用途），用于处理 SSR 生成的 DOM。

function onPrehydrate(
  callback: () => void  // Hydration 前执行的函数
): void

// 在组件中使用
onPrehydrate(() => {
  // 这段代码会在 Hydration 前执行
  // 可以直接操作 SSR 生成的 DOM
  const el = document.querySelector('.server-rendered')
  if (el) el.classList.add('pre-hydrated')
})

INFO

️ 这是一个低级 API 通常不需要使用。仅在需要修改 SSR 生成的 DOM（如添加动画类名）时使用。代码在客户端 Hydration 之前立即执行