Nuxt 插件机制精讲

// plugins/my-plugin.ts
export default defineNuxtPlugin((nuxtApp) => {
  // nuxtApp.vueApp — Vue 应用实例
  // nuxtApp.hook() — 注册生命周期钩子
  // nuxtApp.provide() — 注入全局依赖
  console.log('插件执行了', import.meta.server ? '服务端' : '客户端')
})

// plugins/api.ts
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()
 
  const api = $fetch.create({
    baseURL: config.public.apiBase,
    onRequest({ options }) {
      const token = useCookie('auth-token')
      if (token.value) {
        options.headers.set('Authorization', `Bearer ${token.value}`)
      }
    },
    onResponseError({ response }) {
      if (response.status === 401) navigateTo('/login')
    },
  })
 
  return { provide: { api } }
})

// 任何组件中使用
const { $api } = useNuxtApp()
const videos = await $api('/videos')  // 自动带 Token 和 baseURL

// plugins/api.ts
export default defineNuxtPlugin((nuxtApp) => {
  const api = $fetch.create({ /* ... */ })
  return { provide: { api } }
})
 
// 在同一文件底部，或单独的 types/ 目录中
declare module '#app' {
  interface NuxtApp {
    $api: typeof $fetch
  }
}
 
declare module 'vue' {
  interface ComponentCustomProperties {
    $api: typeof $fetch
  }
}

// nuxt.config.ts
export default defineNuxtConfig({
  plugins: [
    '~/plugins/01.auth.ts',       // 手动指定的优先执行
    '~/plugins/02.api.ts',
  ],
})

// plugins/02.api.ts — 依赖 auth 插件先初始化
export default defineNuxtPlugin({
  name: 'api',
  dependsOn: ['auth'],  // 等 auth 插件执行完再执行
  setup(nuxtApp) {
    // 此时 $auth 已经可用
    const { $auth } = nuxtApp
    // ...
  },
})

// plugins/01.auth.ts
export default defineNuxtPlugin({
  name: 'auth',  // 被依赖的插件必须声明 name
  setup(nuxtApp) {
    return { provide: { auth: { /* ... */ } } }
  },
})

export default defineNuxtPlugin({
  name: 'analytics',
  parallel: true,  // 不阻塞其他插件
  setup(nuxtApp) {
    // 初始化分析 SDK（不需要等待结果）
  },
})

// plugins/auth.server.ts
export default defineNuxtPlugin(async (nuxtApp) => {
  const token = useCookie('auth-token')
 
  if (token.value) {
    // 服务端启动时验证 Token，获取用户信息
    try {
      const user = await $fetch('/api/auth/me', {
        headers: { Authorization: `Bearer ${token.value}` },
      })
      useState('user', () => user)
    } catch {
      token.value = null  // Token 过期，清除
    }
  }
})

// plugins/chat.client.ts — 不阻塞渲染
export default defineNuxtPlugin((nuxtApp) => {
  // 不用 async/await，不阻塞
  onNuxtReady(async () => {
    const { default: ChatWidget } = await import('~/lib/chat-widget')
    ChatWidget.init({ appId: 'xxx' })
  })
})

// plugins/vue-plugins.ts
import VueTippy from 'vue-tippy'
 
export default defineNuxtPlugin((nuxtApp) => {
  // 注册 Vue 插件
  nuxtApp.vueApp.use(VueTippy, {
    defaultProps: { placement: 'top', arrow: true },
  })
 
  // 注册全局组件
  nuxtApp.vueApp.component('GlobalLoader', defineAsyncComponent(
    () => import('~/components/GlobalLoader.vue')
  ))
 
  // 注册全局指令
  nuxtApp.vueApp.directive('focus', {
    mounted(el) { el.focus() },
  })
})

// plugins/lifecycle-logger.ts
export default defineNuxtPlugin((nuxtApp) => {
  // 页面导航开始
  nuxtApp.hook('page:start', () => {
    console.log('页面导航开始')
  })
 
  // 页面导航完成
  nuxtApp.hook('page:finish', () => {
    console.log('页面导航完成')
  })
 
  // Vue 错误捕获（全局 errorHandler）
  nuxtApp.hook('vue:error', (error, instance, info) => {
    console.error('Vue 错误:', error, info)
    // 上报到监控平台
  })
 
  // 应用挂载完成（仅客户端）
  nuxtApp.hook('app:mounted', () => {
    console.log('应用挂载完成')
  })
})

// plugins/loading-bar.client.ts
import NProgress from 'nprogress'
import 'nprogress/nprogress.css'
 
export default defineNuxtPlugin((nuxtApp) => {
  NProgress.configure({ showSpinner: false, minimum: 0.1 })
 
  nuxtApp.hook('page:start', () => {
    NProgress.start()
  })
 
  nuxtApp.hook('page:finish', () => {
    NProgress.done()
  })
 
  // 错误时也要停止进度条
  nuxtApp.hook('vue:error', () => {
    NProgress.done()
  })
})