六维教程

Nuxt UI 入门与安装

Nuxt 自带的模板只有最朴素的元素，写一个按钮、表单、弹窗都要从零写样式。Nuxt UI 是 Nuxt 官方维护的 UI 组件库，把这些常用界面一次性备好，你直接拿来用就行。

本篇是 Nuxt UI 系列的第 1 篇，只讲「怎么接进来」。接好之后，按钮、表单、弹窗这些具体组件在后面的篇章逐个细讲。如果你已经看过 Nuxt4 网站配置 和 Nuxt4 目录结构，下面的配置会非常眼熟，它本质上就是加一个模块、引一个样式文件。

Nuxt UI 是什么

Nuxt UI 提供 100 多个开箱即用的组件，比如按钮 UButton、卡片 UCard、输入框 UInput、对话框 UModal 等，还内置了图标、暗色模式、表单校验等能力。

它和纯手写样式库最大的区别有三个。

  • 组件自动导入，页面里直接写 <UButton>，不用 import。
  • 基于 Tailwind CSS v4，工具类（如 flex、p-4）直接可用，不用单独学一套配置。
  • 自带一套设计体系，颜色、间距、圆角统一，写出来默认就协调。

一句话概括，Nuxt UI 等于「Tailwind 引擎 + 一堆打磨好的组件」。

版本与前提

本教程基于 Nuxt 4，对应的 Nuxt UI 是 v4 版本，需要注意两点。

  • Nuxt UI v4 要求 Nuxt 4.1 及以上，版本不够会安装报错，先升级 Nuxt。
  • 它自带 Tailwind CSS v4，采用「CSS 里配置」的方式（在 .css 文件里写 @import），不需要 tailwind.config.js，新手不用再单独学 Tailwind 安装。

如果你的 Nuxt 项目是用 npm create nuxt@latest 新建的默认项目，就可以直接往下走。

安装三步

整个过程就三步，装依赖、注册模块、建样式入口。

第一步 安装依赖

在项目根目录执行下面命令。

npm install @nuxt/ui tailwindcss

tailwindcss 是 Nuxt UI 的底层样式引擎，必须一起装。

第二步 注册模块

打开根目录的 nuxt.config.ts，在 modules 数组里加上 @nuxt/ui，并通过 css 指向我们的样式入口文件。

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/ui'
  ],
  css: [
    '~/assets/css/main.css'
  ]
})

modules 数组负责「启用哪个模块」，和 Nuxt4 网站配置 里讲的其他模块（如 @pinia/nuxt）是同一处配置。css 则是全局样式入口，Nuxt 启动时会自动加载它。

如果嫌手动改配置麻烦，Nuxt 也提供一键命令，会自动完成「装依赖 + 注册模块」两件事。

npx nuxi module add @nuxt/ui

第三步 建样式入口

在 app/assets/css/ 目录下新建 main.css，写入两行导入。

/* app/assets/css/main.css */
@import "tailwindcss";
@import "@nuxt/ui";

第一行加载 Tailwind，第二行加载 Nuxt UI 的样式与设计变量。注意 Nuxt 4 的静态资源都放在 app/ 目录下，所以这个文件在 app/assets/css/，不是根目录的 assets/。

到这里安装就完成了，启动项目看不出变化很正常，因为组件要主动使用才会显示。

根容器 UApp

组件全局自动导入，在任意 .vue 文件里直接写标签名即可。

先在 app/app.vue 用 <UApp> 把应用包起来。UApp 是 Nuxt UI 的根容器，弹窗、提示（toast）这类全局组件依赖它才能正常弹出，建议从一开始就加上。

<!-- app/app.vue -->
<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>

验证

执行启动命令。

npm run dev

打开 http://localhost:3000，页面能正常打开就说明接入成功（具体组件长什么样，从下一篇开始看）。如果启动报 Nuxt 版本不兼容，请先把 Nuxt 升级到 4.1 以上。

本系列后续

接入完成后，建议按下面顺序学习。

  • 按钮 UButton
  • 表单与输入
  • 卡片与容器
  • 弹窗与浮层
  • Toast 与通知
  • 数据表格 UTable
  • 下拉菜单与命令面板
  • 主题与暗色模式
  • 图标 Icon

常见问题

问题 解决方法
组件能写但不显示样式 检查 main.css 里两行 @import 是否齐全，以及 nuxt.config.ts 的 css 是否指向这个文件
页面报错找不到 UApp 等组件 确认 @nuxt/ui 已加进 modules 数组，并重启 npm run dev
写 class="p-4" 没有效果 Tailwind 没生效，多半是漏了 @import "tailwindcss"，或 tailwindcss 依赖没装
编辑器里 Tailwind 类名不提示 安装 VS Code 扩展 Tailwind CSS IntelliSense
安装时报 Nuxt 版本不兼容 Nuxt UI v4 要 Nuxt 4.1+，升级 Nuxt 到最新版再装

参考资料

本篇在编写时参考了以下资料。

下一篇
按钮 UButton