nuxt-插件Plugins

一、什么是 Nuxt Plugins

Plugins 是 Nuxt 应用的“启动前拦截器”，让你在应用完全启动前，注入全局功能、初始化第三方库、配置运行环境，plugins 目录里的代码会“自动”在应用启动时执行，不需要手动调用，我们可以在插件中做如下事情：

注册全局组件
注入全局方法和变量
初始化第三方库
添加自定义逻辑

二、Plugins 的基本结构

1. 创建插件文件

插件文件需要放在 plugins/ 目录下，命名没有强制要求，但建议见名知意：

plugins/├── axios.js          # axios 配置├── vuetify.js        # UI 框架├── dayjs.js          # 日期库├── global-components.js  # 全局组件注册└── api.js            # API 注入

2. 插件基本格式

// plugins/my-plugin.jsexport default defineNuxtPlugin((nuxtApp) => {  // nuxtApp 包含很多有用的方法和属性  // 在这里执行你的插件逻辑  return {    provide: {      // 这里返回的内容会被注入到全局    }  }})

三、Plugins 的核心功能详解

1. 依赖注入（provide/inject）

// plugins/api.jsexport default defineNuxtPlugin(() => {  const api = {    async fetchData() {      // API 调用逻辑      return { data: 'some data' }    },    baseURL: 'https://api.example.com'  }  return {    provide: {      api  // 现在可以在组件中使用 $api    }  }})

在组件中使用：

<scriptsetup>const { $api } = useNuxtApp()// 或者直接使用const data = await $api.fetchData()</script>

2. 全局组件注册

// plugins/global-components.jsimport MyButton from '~/components/MyButton.vue'import MyModal from '~/components/MyModal.vue'export default defineNuxtPlugin((nuxtApp) => {  nuxtApp.vueApp.component('MyButton', MyButton)  nuxtApp.vueApp.component('MyModal', MyModal)  // 或者自动注册一个目录下的所有组件  // const components = import.meta.glob('~/components/global/*.vue')  // for (const [path, component] of Object.entries(components)) {  //   const name = path.split('/').pop().replace('.vue', '')  //   nuxtApp.vueApp.component(name, defineAsyncComponent(component))  // }})

3. 第三方库初始化

// plugins/dayjs.jsimport dayjs from 'dayjs'import relativeTime from 'dayjs/plugin/relativeTime'import 'dayjs/locale/zh-cn'export default defineNuxtPlugin(() => {  dayjs.extend(relativeTime)  dayjs.locale('zh-cn')  return {    provide: {      dayjs    }  }})

4. 使用 nuxtApp 的高级功能

// plugins/analytics.jsexport default defineNuxtPlugin((nuxtApp) => {  // 1. 监听路由变化  nuxtApp.hook('page:start', () => {    console.log('页面开始加载')  })  nuxtApp.hook('page:finish', () => {    console.log('页面加载完成')  })  // 2. 应用级别的钩子  nuxtApp.hook('app:created', () => {    console.log('应用已创建')  })  // 3. 错误处理  nuxtApp.hook('vue:error', (error) => {    console.error('Vue 错误:', error)  })})

5. 客户端或服务端专用插件

通过文件名后缀控制执行环境：

// plugins/gtag.client.js  - 仅在客户端运行export default defineNuxtPlugin(() => {  // Google Analytics 初始化  // 只在浏览器环境执行})// plugins/server-auth.server.js  - 仅在服务端运行export default defineNuxtPlugin(() => {  // 服务端认证逻辑})// plugins/universal.js  - 两端都运行（默认）export default defineNuxtPlugin(() => {  // 在客户端和服务端都执行})

四、配置和注册

1. nuxt.config.ts 配置

// nuxt.config.tsexport default defineNuxtConfig({  plugins: [    '~/plugins/global-components.js',    { src: '~/plugins/analytics.js', mode: 'client' }, // 仅客户端    { src: '~/plugins/server-init.js', mode: 'server' }, // 仅服务端  ]})

注意：plugins/ 目录下的插件默认自动注册，nuxt.config.ts 中的配置用于改变默认行为。

2. 插件执行顺序

// nuxt.config.tsexport default defineNuxtConfig({  plugins: [    '~/plugins/01-first.js',      // 按字母/数字顺序    '~/plugins/02-second.js',     // 第二个执行    {       src: '~/plugins/third.js',      order: 10                   // 数字越小越先执行    }  ]})