Nuxt4 插件

插件（plugin）用来在应用启动时做一些全局初始化，或者把第三方库、自己写的功能「注入」到全站，让任意组件都能直接调用。本篇讲清楚插件怎么写、怎么注册、怎么注入。

插件放在哪

Nuxt 约定插件放在 app/plugins/ 目录下，文件名以 .ts 或 .js 结尾。放在这里的文件会在应用初始化时自动执行，无需手动 import。

写一个插件

用 defineNuxtPlugin 定义插件，它接收一个回调函数。

// app/plugins/hello.ts
export default defineNuxtPlugin(() => {
  console.log('应用启动啦')
})

这样应用一启动就会打印这句日志。这只是最小例子，更复杂的初始化（比如接入全局库）也写在这里。

注入全局能力

插件最常用的场景是把一个函数或对象注入到全站，组件里用 useNuxtApp() 取到。用 provide 来注入。

// app/plugins/api.ts
export default defineNuxtPlugin((nuxtApp) => {
  const $api = {
    get: (url: string) => fetch(url).then(r => r.json())
  }
  // 把 $api 注入到全站，组件里就能用 useNuxtApp().$api
  nuxtApp.provide('api', $api)
})

在组件里使用。

<script setup>
const { $api } = useNuxtApp()

async function load() {
  const data = await $api.get('/api/list')
  console.log(data)
}
</script>

注意注入的 key 要以 $ 开头（如 $api），这是 Nuxt 的约定，方便和组件自身变量区分。

只在客户端运行

有些库依赖浏览器 API（如 window），在服务端渲染时会报错。用 mode: 'client' 让插件只在客户端加载。

// app/plugins/chart.client.ts
export default defineNuxtPlugin(() => {
  // 这里写依赖浏览器的代码
})

把文件名加上 .client 后缀，效果等同 mode: 'client'，Nuxt 会自动识别。对应的还有 .server 后缀，只在服务端运行。

插件执行顺序

多个插件可以用文件名里的数字前缀控制顺序，比如 01.first.ts 会比 02.second.ts 先执行。大多数情况不需要关心，遇到依赖顺序时再调整。

插件是接入第三方库、做全局初始化的标准入口。需要全站共享的能力，优先用插件注入，而不是在每个组件里重复 import。