模块简介

Nuxt 模块是扩展 Nuxt 功能的插件系统，类似于 Vue 的插件机制。通过模块可以快速集成第三方服务、添加全局组件和组合式函数。

什么是模块？

模块可以在 Nuxt 启动的不同阶段介入，实现各种功能扩展：

• 添加组件、组合式函数、插件 — 自动注册到项目中
• 修改构建配置 — 调整 Vite、Webpack 等构建工具配置
• 添加服务端功能 — 注册 API 路由、中间件、Nitro 插件
• 集成第三方服务 — 接入 TailwindCSS、i18n、CMS 等
• 修改 Nuxt 内部行为 — 通过钩子系统干预构建和渲染流程

模块的工作原理

nuxt.config.ts 中声明模块
       ↓
Nuxt 启动时按顺序执行模块
       ↓
模块通过 defineNuxtModule 定义
       ↓
模块内部可以：
├── 添加自动导入
├── 注册组件
├── 添加插件
├── 修改构建配置
├── 注册钩子回调
└── 扩展 TypeScript 类型

安装模块

# 安装模块依赖
npm install @pinia/nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',
  ],
})

TIP

某些模块可以通过 npx nuxi module add <name> 一键安装 会自动添加依赖和配置

模块执行顺序

模块按 modules 数组的顺序执行。某些模块可能有依赖顺序要求：

export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',          // 先安装 Pinia
    '@nuxtjs/i18n',         // i18n 可能依赖 Pinia
  ],
})

INFO

️ 如果模块 A 依赖模块 B 提供的功能 A 必须放在 B 之后

禁用模块

不需要卸载模块依赖，可以通过配置键禁用：

export default defineNuxtConfig({
  modules: [
    '@nuxt/image',
    '@pinia/nuxt',
  ],

  // 通过模块的配置键禁用
  image: false,      // 禁用 @nuxt/image
  pinia: false,      // 禁用 @pinia/nuxt
})

TIP

配置键通常就是模块名去掉 @nuxtjs/ 或 @nuxt/ 前缀 如 @nuxt/image → image

模块配置

每个模块有自己的配置键，可以在 nuxt.config.ts 中设置：

export default defineNuxtConfig({
  modules: [
    '@nuxtjs/tailwindcss',
    '@nuxt/image',
    '@pinia/nuxt',
  ],

  // 模块配置
  image: {
    quality: 80,
    formats: ['webp', 'avif'],
    domains: ['images.unsplash.com'],
  },

  tailwindcss: {
    cssPath: '~/app/assets/css/tailwind.css',
  },

  pinia: {
    storesDirs: ['./app/stores/**'],
  },
})

查找模块的配置键

// 方法1：查看模块文档
// 方法2：查看模块源码中的 configKey
// 方法3：模块名去除作用域和前缀
// @nuxt/image → image
// @pinia/nuxt → pinia
// @nuxtjs/i18n → i18n

Nuxt 模块生态

官方模块列表：https://nuxt.com/modules

类别	模块	说明
UI	@nuxt/ui	Nuxt 官方 UI 组件库
UI	@nuxtjs/tailwindcss	TailwindCSS 集成
状态管理	@pinia/nuxt	Pinia 状态管理
图片	@nuxt/image	图片优化组件
字体	@nuxt/fonts	字体自动优化
图标	@nuxt/icon	图标组件
内容	@nuxt/content	Markdown 内容管理
i18n	@nuxtjs/i18n	国际化
SEO	@nuxtjs/sitemap	站点地图
SEO	@nuxtjs/robots	Robots.txt 管理
认证	@sidebase/nuxt-auth	认证模块
数据库	nuxt-drizzle	Drizzle ORM 集成
颜色模式	@nuxtjs/color-mode	深色/浅色模式切换
Google	@nuxtjs/google-fonts	Google 字体加载
DevTools	@nuxt/devtools	开发者工具

模块 vs 插件 vs 中间件

特性	模块	插件	中间件
执行时机	构建时	应用启动时	路由导航时
能力范围	修改构建配置、注册功能	注入全局方法	守卫路由
来源	npm 包或本地	plugins/ 目录	middleware/ 目录
复杂度	高（可做任何事）	中	低

TIP

简单功能用插件 跨项目复用用模块，路由守卫用中间件