配置类

函数	用途	客户端	服务端
useRuntimeConfig	获取运行时配置	✅ 仅 public	✅ 全部
useRuntimeHook	注册运行时钩子	✅	✅

useRuntimeConfig

获取运行时配置，区分公共配置和私有配置。

const config = useRuntimeConfig()

// 公共配置（客户端 + 服务端都可用）
config.public.apiBase
config.public.appName

// 私有配置（仅服务端可用）
config.apiSecret
config.dbUrl

公共 vs 私有配置

• config.public.*：客户端和服务端都可用，暴露给浏览器
• config.*（非 public）：仅服务端可用，不会发送到客户端

INFO

️ 永远不要把密钥放在 public 下 否则会暴露给浏览器

在服务端 API 中使用

// server/api/data.ts
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event)  // 建议传 event

  return {
    data: fetchData(config.apiSecret),
  }
})

在服务端建议传 event

这样 Nitro 可以在请求上下文中获取配置，避免多租户场景下的配置冲突。

配置定义

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 私有配置（仅服务端）
    apiSecret: '',
    dbUrl: '',

    // 公共配置（客户端 + 服务端）
    public: {
      apiBase: '',
      appName: 'My App',
    },
  },
})

环境变量映射

NUXT_API_SECRET      → config.apiSecret
NUXT_PUBLIC_API_BASE → config.public.apiBase
NUXT_PUBLIC_APP_NAME → config.public.appName

环境变量命名规则

• 私有配置：NUXT_ + 大写键名
• 公共配置：NUXT_PUBLIC_ + 大写键名

useRuntimeHook

注册运行时钩子，用于在特定事件发生时执行逻辑。

const hook = useRuntimeHook()

hook('page:view', (page) => {
  console.log('页面浏览:', page.path)
})

useRuntimeHook vs nuxtApp.hook

• useRuntimeHook：在组件中使用，自动清理（组件卸载时移除钩子）
• nuxtApp.hook：在插件中使用，全局注册