Nuxt UI v3 迁移指南：从 v2 平滑升级到最新版本

Nuxt UI v3 迁移指南：从 v2 平滑升级到最新版本

ui A UI Library for Modern Web Apps, powered by Vue & TailwindCSS. 项目地址: https://gitcode.com/gh_mirrors/ui4/ui

前言

Nuxt UI v3 是一次重大的架构重构，带来了显著的性能提升和开发者体验优化。作为技术专家，我将在本文中详细解析迁移过程中的关键点，帮助开发者顺利完成版本升级。

核心升级内容

Nuxt UI v3 主要包含以下重大变更：

1. Tailwind CSS v4：配置方式从 JavaScript 迁移到纯 CSS
2. Reka UI：取代 Headless UI 成为底层组件库
3. Tailwind Variants：全新的组件变体样式 API

迁移步骤详解

第一步：升级 Tailwind CSS

Tailwind CSS v4 采用了全新的配置方式：

1. 创建 main.css 文件并导入到配置中：

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

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

2. 运行升级工具自动处理大部分迁移工作：

npx @tailwindcss/upgrade

第二步：更新 Nuxt UI 依赖

根据项目类型选择正确的安装命令：

# 基础版
pnpm add @nuxt/ui

# Pro 版
pnpm add @nuxt/ui-pro

然后在 CSS 中导入：

@import "tailwindcss";
@import "@nuxt/ui";  // 或 @nuxt/ui-pro

第三步：应用结构调整

v3 要求使用 UApp 组件包裹应用：

<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>

Pro 版用户需要更新配置：

export default defineNuxtConfig({
  modules: ['@nuxt/ui-pro']  // 移除了 extends 配置
})

重大变更解析

设计系统重构

v3 引入了更规范的 7 种颜色别名：

| 颜色 | 默认值 | 说明 | |------|--------|------| | primary | green | 品牌主色 | | secondary | blue | 辅助色 | | success | green | 成功状态 | | info | blue | 信息状态 | | warning | yellow | 警告状态 | | error | red | 错误状态 | | neutral | slate | 中性色 |

主要变更点：

• gray 重命名为 neutral
• 移除了直接使用 Tailwind 颜色的能力
• 颜色配置移至 colors 对象内

主题系统升级

组件样式现在使用 Tailwind Variants API：

// 旧配置
button: {
  font: 'font-bold',
  default: {
    size: 'md'
  }
}

// 新配置
button: {
  slots: {
    base: 'font-medium'
  },
  defaultVariants: {
    size: 'md'
  }
}

组件重命名

多个组件采用了更符合 Reka UI 规范的名称：

| v2 组件 | v3 组件 | |---------|---------| | Divider | Separator | | Dropdown | DropdownMenu | | FormGroup | FormField | | Range | Slider | | Toggle | Switch |

API 重要变更

1. 选项属性统一：links 和 options 统一为 items
2. 点击事件标准化：click 字段改为 Vue 标准的 onClick
3. 全局组件简化：移除了单独的 Modals 等组件，统一由 UApp 管理
4. 可见性控制：使用 v-model:open 替代原有方式
5. 插槽结构调整：引入了 #header、#body、#footer 等标准插槽

组合式 API 变更

1. Toast 超时参数：timeout 改为 duration
2. 覆盖层管理：统一使用 useOverlay 替代原有的 useModal 等

// 新式用法
const overlay = useOverlay()
const modal = overlay.create(ModalComponent, {
  props: { count: value }
})

const result = await modal.result

迁移建议

1. 逐步迁移：建议按组件逐个迁移，而非一次性全部更改
2. 利用类型提示：v3 提供了完善的类型定义，可借助 IDE 提示快速定位需要修改的部分
3. 设计系统适配：提前规划好颜色系统的调整方案
4. 测试覆盖：确保迁移后对所有交互场景进行充分测试

总结

Nuxt UI v3 虽然带来了不少破坏性变更，但这些改进为未来的功能扩展奠定了更好的基础。通过本文的详细指导，开发者应该能够顺利完成从 v2 到 v3 的迁移工作。如果在迁移过程中遇到特殊问题，建议查阅具体组件的独立文档获取更详细的信息。

ui A UI Library for Modern Web Apps, powered by Vue & TailwindCSS. 项目地址: https://gitcode.com/gh_mirrors/ui4/ui