Nuxt 4 模块系统怎么用？官方与社区模块安装配置指南

本节目标：理解 Nuxt 模块是什么，学会在项目中添加官方/社区模块，并大致明白模块在构建时是如何工作的。

38-1

Nuxt 把路由、SSR、数据获取这些核心能力做好了，但「接 Google 分析」「用 Tailwind 写样式」「优化图片」这类需求千差万别。如果每个都写进框架，Nuxt 会臃肿到没法用。

所以 Nuxt 提供了模块系统（modules）：把扩展能力做成独立 npm 包，需要时用一行配置装进来。模块既能配置构建工具、添加 CSS 库，也能自动注册组件、组合式函数、插件，甚至帮你接入第三方服务。

Note

模块只在「构建时」运行（启动 nuxt dev 或 nuxt build 时），运行一次，用来改造你的应用。这一点和运行时才加载的插件不同。Nuxt 2 里用过 buildModules，在 Nuxt 3/4 已废弃，统一用 modules。

38-2

根据维护方和命名，模块大致分四类：

官方模块：名字带 @nuxt/ 前缀（如 @nuxt/content、@nuxt/image、@nuxt/fonts），由 Nuxt 核心团队维护。
社区模块：名字带 @nuxtjs/ 前缀（如 @nuxtjs/tailwindcss、@nuxtjs/google-fonts），由社区成员维护、经过验证。
第三方模块：常带 nuxt- 前缀，任何人都能发布，是尝试新想法的最佳起点。
私有模块：只给自己公司用的，命名随意，比如 @my-company/nuxt-auth。

整个 Nuxt 模块生态每月 npm 下载量超过 3500 万次，覆盖面非常广。

38-3

绝大多数模块的安装分两步：先装包，再登记。

npm i -D @nuxtjs/tailwindcss

export default defineNuxtConfig({
  modules: [
    '@nuxtjs/tailwindcss',
  ],
})

modules 数组里可以放多种形式：

export default defineNuxtConfig({
  modules: [
    '@nuxtjs/example',          // 用包名（最常见）
    './modules/example',        // 加载本地模块
    ['./modules/example', { token: '123' }], // 带选项的模块
  ],
})

Tip

模块往往自带自动导入：装了 @nuxtjs/i18n，它的 useI18n 就能免导入使用；装了 @nuxt/image，<NuxtImg> 组件直接可用。具体看每个模块的文档。

38-4

源码层面，一个模块就是一个异步函数，运行在 Nuxt 构建阶段。它能做的事情很多：

注册 Vue 组件、组合式函数、插件；
修改 Webpack/Vite 配置、添加加载器；
注入 CSS、预设、运行时配置；
调用 Nitro 钩子，扩展服务端能力。

也就是说，模块能「重写模板、改配置、加文件」，把你原本要在多个项目里重复写的集成代码，封装成一个可复用的包。

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup(options, nuxt) {
    // 这里定义模块要做的所有事
  },
})

Warning

不要盲目装太多模块。每个模块都会增加构建复杂度和启动开销。装之前先确认它确实被维护、与你的 Nuxt 版本兼容。可以在官方模块列表 nuxt.com/modules 上检索。

38-5

当然可以，而且门槛不高。Nuxt 提供了 @nuxt/kit 工具包，帮你用声明式的方式写模块。社区鼓励把通用集成发布成模块，甚至可以申请加入 nuxt-modules 组织，把社区模块升级到 @nuxtjs/ 命名空间。

对初学者来说，先学会「挑模块、用模块」就够了；等你对 Nuxt 内部机制（钩子、构建流程）更熟了，再考虑自己造轮子。

38-6

@nuxt/content：把 Markdown、YAML 等文件变成可查询的内容源，做文档站、博客很省事。
@nuxt/image：图片优化，自动转 WebP/AVIF、按尺寸裁剪、懒加载。
@nuxt/fonts：自动优化字体，自托管并减少布局抖动。
@nuxt/scripts：更安全地加载第三方脚本（分析、地图、社交组件）。

Note

这些模块会在第 47 章「模块生态速览」里展开讲，告诉你各自适合什么场景、怎么落地。

38-7

Nuxt 3 与 Nuxt 4 的模块机制一致：modules 字段登记、构建时运行。差异仅在目录约定——本地模块路径在 Nuxt 4 下通常指向 app/ 或 server/ 内部。模块 API 本身无需改动迁移。

38-8

想自己写一个模块，门槛比想象低。一个模块就是调用 defineNuxtModule 并导出，核心逻辑写在 setup 里：

import { defineNuxtModule, addComponent } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  defaults: {},
  setup(options, nuxt) {
    addComponent({
      name: 'MyButton',
      filePath: '~~/components/MyButton.vue',
    })
  },
})

meta.name 是模块标识，setup 里能用 @nuxt/kit 提供的 addComponent、addImports、addPluginTemplate 等 API 往项目里「塞」东西。本地模块在 nuxt.config 里用相对路径登记：modules: ['./modules/my-module']。

Tip

写模块前先想清楚：你只是想在多个项目复用一段集成代码，才值得做成模块。如果只是本项目的一个小逻辑，组合式函数或插件就够了，别为了「像官方」硬造模块。
模块和插件的区别值得再强调一次：插件是运行时初始化，模块是构建时改造。模块能往项目里加文件、改配置、注册组件和组合式函数，这些事插件做不到。反过来，模块不适合放「每次请求都要跑的逻辑」，那该交给插件或 Nitro 服务端钩子。理解这条边界，就不会纠结「这段集成代码到底该写成模块还是插件」。

Note

社区里很多官方模块其实也是用 @nuxt/kit 的同一套 API 写出来的。学会了模块原理，你就能读懂它们的源码，遇到文档没写清楚的行为，直接翻源码比到处搜快。

38-9

模块是 Nuxt 的「可插拔扩展包」，构建时运行，用 modules 字段登记。官方用 @nuxt/、社区用 @nuxtjs/，挑模块看兼容性、别贪多。下一章我们看一种更轻量的复用方式：层（Layers）。

38-7 模块的开发与发布

当你发现一组配置和插件在多个项目里重复使用时，可以考虑把它们封装成一个 Nuxt 模块。模块可以发布到 npm，让其他开发者一行命令就能集成你的功能。

Nuxt 模块的核心是一个函数，接收 nuxt 实例和模块选项作为参数。在这个函数里，你可以修改 Nuxt 配置、注册插件、添加服务端路由、注入组合式函数等。Nuxt Kit 提供了一系列工具函数，简化模块开发的常见操作。

发布模块时，遵循社区的命名约定：包名以 nuxt- 开头（如 nuxt-my-feature）。在 README 里清楚说明支持的 Nuxt 版本、配置选项和使用示例。一个好的模块应该有完整的 TypeScript 类型定义，让使用者获得良好的类型提示体验。

38-8 模块与 Nuxt DevTools 的集成

Nuxt DevTools 是一个强大的开发调试工具，很多 Nuxt 模块都和它做了集成。当你在项目里安装一个支持 DevTools 的模块后，它会在 DevTools 面板里添加自己的标签页，提供可视化的配置界面和运行时数据展示。

比如 @nuxt/content 模块在 DevTools 里提供了内容浏览界面，@pinia/nuxt 提供了状态查看器。这种集成让开发调试更加直观，不需要在代码里加 console.log 就能看到模块的内部状态。

如果你正在开发自己的 Nuxt 模块，也值得考虑和 DevTools 集成。Nuxt 提供了专门的 API 来注册 DevTools 自定义面板。虽然这不是必须的，但它能显著提升使用者的开发体验。

模块系统 modules

38-1

38-2

38-3

38-4

38-5

38-6

38-7

38-8

38-9

38-7 模块的开发与发布

38-8 模块与 Nuxt DevTools 的集成