插件类

defineNuxtPlugin

定义 Nuxt 插件，用于注册全局功能、注入依赖等。

function defineNuxtPlugin(
  plugin: (nuxtApp: NuxtApp) => void | {
    provide?: Record<string, any>  // 注入全局方法/对象
  },
  options?: {
    enforce?: 'pre' | 'post' | 'default' // 执行顺序
    parallel?: boolean     // 是否并行执行
    order?: number         // 排序权重
  }
): NuxtPlugin

基本用法

// plugins/my-plugin.ts
export default defineNuxtPlugin((nuxtApp) => {
  // 在应用初始化时执行
  console.log('Nuxt App 启动', nuxtApp.vueApp)
})

提供（provide）全局方法

// plugins/format.ts
export default defineNuxtPlugin(() => {
  return {
    provide: {
      format: {
        date: (d: string) => new Date(d).toLocaleDateString('zh-CN'),
        currency: (n: number) => `¥${n.toFixed(2)}`,
      },
    },
  }
})

// 在组件中使用
const { $format } = useNuxtApp()
console.log($format.date('2024-01-01'))   // "2024/1/1"
console.log($format.currency(99.9))       // "¥99.90"

注入 Vue 全局属性

// plugins/i18n.ts
export default defineNuxtPlugin((nuxtApp) => {
  const i18n = reactive({
    locale: 'zh-CN',
    t(key: string) {
      return translations[this.locale]?.[key] ?? key
    },
  })

  nuxtApp.vueApp.provide('i18n', i18n)
})

执行顺序控制

// plugins/01-init.ts — 最先执行
export default defineNuxtPlugin(() => {
  // 初始化逻辑
}, { enforce: 'pre' })

// plugins/99-cleanup.ts — 最后执行
export default defineNuxtPlugin(() => {
  // 清理逻辑
}, { enforce: 'post' })

// 并行执行（不阻塞其他插件）
export default defineNuxtPlugin(() => {
  // 非关键逻辑
}, { parallel: true })

TIP

插件按文件名字母顺序自动执行 enforce: 'pre' 确保在最前执行，enforce: 'post' 确保在最后执行

访问 NuxtApp

export default defineNuxtPlugin((nuxtApp) => {
  // Vue 实例
  nuxtApp.vueApp

  // 路由实例
  nuxtApp.$router

  // Payload 数据
  nuxtApp.payload

  // 注册钩子
  nuxtApp.hook('page:finish', () => {
    console.log('页面加载完成')
  })
})

onNuxtReady

Nuxt 应用完全就绪后执行回调（客户端仅执行一次）。

function onNuxtReady(
  callback: (nuxtApp: NuxtApp) => void
): void

onNuxtReady((nuxtApp) => {
  console.log('Nuxt 应用已就绪')
  // 可以安全地访问 DOM、路由等
})

// 实际应用：就绪后启动分析工具
onNuxtReady(() => {
  if (import.meta.client) {
    initAnalytics()
  }
})

INFO

️ onNuxtReady 在服务端也会触发 如果只需客户端执行，请使用 import.meta.client 守卫