安装

了解如何将 Nuxt UI 安装并配置到你的 Vue 应用程序中，它兼容普通 Vite 和 Inertia。

设置

添加到 Vue 项目

安装 Nuxt UI 包

pnpm add @nuxt/ui tailwindcss

yarn add @nuxt/ui tailwindcss

npm install @nuxt/ui tailwindcss

bun add @nuxt/ui tailwindcss

在你的 `vite.config.ts` 中添加 Nuxt UI Vite 插件

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui()
  ]
})

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
import laravel from 'laravel-vite-plugin'

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/js/app.ts'],
      refresh: true
    }),
    vue({
      template: {
        transformAssetUrls: {
          base: null,
          includeAbsolute: false
        }
      }
    }),
    ui({
      router: 'inertia'
    })
  ]
})

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
import adonisjs from '@adonisjs/vite/client'
import inertia from '@adonisjs/inertia/client'

export default defineConfig({
  plugins: [
    adonisjs({
      entrypoints: ['inertia/app/app.ts'],
      reload: ['resources/views/**/*.edge']
    }),
    inertia(),
    vue(),
    ui({
      router: 'inertia'
    })
  ]
})

Nuxt UI 会注册 unplugin-auto-import 和 unplugin-vue-components，它们将生成 auto-imports.d.ts 和 components.d.ts 类型声明文件。你可能需要将其添加到 gitignore 中，并加入到 tsconfig 中。

tsconfig.app.json

{
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
}

.gitignore

# Auto-generated type declarations
auto-imports.d.ts
components.d.ts

在内部，Nuxt UI 依赖自定义别名来解析主题类型。如果你正在使用 TypeScript，则应在 tsconfig 中添加别名，以在 vite.config.ts 中启用自动补全。

tsconfig.node.json

{
  "compilerOptions": {
    "paths": {
      "#build/ui": [
        "./node_modules/.nuxt-ui/ui"
      ]
    }
  }
}

tsconfig.app.json

{
  "compilerOptions": {
    "paths": {
      "#build/ui/*": [
        "./node_modules/.nuxt-ui/ui/*"
      ]
    }
  }
}

使用 Nuxt UI Vue 插件

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)

app.mount('#app')

import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

在 CSS 中导入 Tailwind CSS 和 Nuxt UI

@import "tailwindcss";
@import "@nuxt/ui";

@import "tailwindcss";
@import "@nuxt/ui";

@import "tailwindcss";
@import "@nuxt/ui";

在入口文件中导入该 CSS 文件。

import './assets/css/main.css'

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)

app.mount('#app')

import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

建议为 VSCode 安装 Tailwind CSS IntelliSense 扩展，并添加以下设置

.vscode/settings.json

{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "tailwindCSS.classAttributes": ["class", "ui"],
  "tailwindCSS.classFunctions": ["defineAppConfig"]
}

用 App 组件包裹您的应用程序

<template>
  <UApp>
    <RouterView />
  </UApp>
</template>

<template>
  <UApp>
    <!-- Your content goes here -->
  </UApp>
</template>

<template>
  <UApp>
    <!-- Your content goes here -->
  </UApp>
</template>

App 组件用于设置全局配置，对于 Toast、Tooltip 和 程序化覆盖层 (programmatic overlays) 是必需的。

将 `isolate` 类添加到你的根容器中

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Nuxt UI</title>
  </head>
  <body>
    <div id="app" class="isolate"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead
    @vite('resources/js/app.ts')
  </head>
  <body>
    <div class="isolate">
        @inertia
    </div>
  </body>
</html>

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead()
    @vite(['inertia/app/app.ts', `inertia/pages/${page.component}.vue`])
  </head>
  <body>
    @inertia({ class: 'isolate' })
  </body>
</html>

这可确保样式被限定在你的应用范围内，并防止覆盖层和堆叠上下文出现问题。

使用 Vue 模板

通过点击 GitHub 上的 Use this template 按钮或使用 CLI，从我们的官方模板开始。

npm create nuxt@latest -- --no-modules -t ui-vue

npm create nuxt@latest -- --no-modules -t ui-vue/dashboard

npm create nuxt@latest -- --no-modules -t ui-vue/chat

启动器

一个用于开始使用 Nuxt UI 的最小模板。

Dashboard

一个带有多列布局的仪表板模板，用于构建复杂的管理界面。

聊天

一个 AI 聊天机器人模板，用于构建您自己的聊天机器人，由 Vercel AI SDK 驱动。

Starter Adonis

一个适用于 AdonisJS 且使用 Inertia.js 的最小化 Nuxt UI 模板。

Starter Laravel

一个适用于 Laravel 且使用 Inertia.js 的最小化 Nuxt UI 模板。

选项

你可以通过在 vite.config.ts 中提供选项来自定义 Nuxt UI。

`prefix`

使用 prefix 选项更改组件的前缀。

默认值：U

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      prefix: 'Nuxt'
    })
  ]
})

`ui`

使用 ui 选项为 Nuxt UI 提供配置。

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        colors: {
          primary: 'green',
          neutral: 'slate'
        }
      }
    })
  ]
})

`colorMode`

使用 colorMode 选项启用或禁用来自 @vueuse/core 的颜色模式集成。

默认值：true

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      colorMode: false
    })
  ]
})

`theme.colors`

使用 theme.colors 选项定义用于生成组件主题的动态颜色别名。

默认值：['primary', 'secondary', 'success', 'info', 'warning', 'error']

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        colors: ['primary', 'error']
      }
    })
  ]
})

在主题部分了解更多关于颜色定制和主题的信息。

`theme.transitions`

使用 theme.transitions 选项启用或禁用组件上的过渡。

默认值：true

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        transitions: false
      }
    })
  ]
})

此选项会在具有悬停或激活状态的组件上添加 transition-colors 类。

`theme.defaultVariants`

使用 theme.defaultVariants 选项来覆盖组件默认的 color 和 size 变体。

默认值：{ color: 'primary', size: 'md' }

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        defaultVariants: {
          color: 'neutral',
          size: 'sm'
        }
      }
    })
  ]
})

`theme.prefix` 4.2+

使用 theme.prefix 选项来配置与你的 Tailwind CSS 导入中设置的相同前缀。这可确保 Nuxt UI 组件使用正确的前缀工具类和 CSS 变量。

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        prefix: 'tw'
      }
    })
  ]
})

@import "tailwindcss" prefix(tw);
@import "@nuxt/ui";

这将自动为 Nuxt UI 组件主题中的所有 Tailwind 工具类和 CSS 变量添加前缀。

<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>

<!-- With prefix: tw -->
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>

在 Tailwind CSS 文档中了解更多关于使用前缀的信息。

`prose`

使用 prose 选项以启用 Nuxt UI Prose 组件及其主题。

默认值：false

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      prose: true
    })
  ]
})

`autoImport`

使用 autoImport 选项可禁用组合式函数 (composable) 的自动导入，或自定义 unplugin-auto-import 选项。

默认值：{}

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      autoImport: false
    })
  ]
})

当禁用时，你仍然可以从 @nuxt/ui/composables 显式导入组合式函数。

`components`

使用 components 选项可禁用组件的自动导入，或自定义 unplugin-vue-components 选项。

默认值：{}

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      components: false
    })
  ]
})

当禁用时，你仍然可以显式导入组件，例如 import Button from '@nuxt/ui/components/Button.vue' 或 import ProseCode from '@nuxt/ui/components/prose/Code.vue'。

`router` 4.3+

使用 router 选项配置路由集成。这对于不使用 vue-router 的应用程序（如 Electron 应用、多页应用 (MPA) 或像 Inertia.js 或 Hybridly 这样的框架）非常有用。

默认值：true

值	描述
`true`	使用 `vue-router` 进行导航，配合 `RouterLink` 组件。
`false`	禁用路由集成，链接呈现为普通的 `<a>` 标签。
`'inertia'`	使用 Inertia.js 进行导航，配合其 `Link` 组件。

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      router: false
    })
  ]
})

你可以通过在 Vite 配置中设置 router: false 并安装 Vue 插件时传入函数，从而为像 Hybridly 这样的框架提供自定义导航逻辑。

src/main.ts

import ui from '@nuxt/ui/vue-plugin'
import { router } from 'hybridly'

app.use(ui, {
  router: (event, { href, external }) => {
    if (external) {
      return
    }

    event.preventDefault()

    router.navigate({ url: href })
  }
})

当设置为 false 或 'inertia' 时，不需要 vue-router 作为依赖项。

`scanPackages` 4.3+

使用 scanPackages 选项来指定应该使用 Nuxt UI 扫描组件的其他 npm 包。这在你拥有一个内部使用 Nuxt UI 组件的共享组件库时非常有用。

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      scanPackages: ['@my-org/ui-components']
    })
  ]
})

默认情况下，仅扫描 @nuxt/ui。当你的外部包包含使用 Nuxt UI 的 Vue 组件时，请使用此选项。

持续发布

Nuxt UI 使用 pkg.pr.new 进行持续预览发布，使开发者能够立即访问最新功能和错误修复，而无需等待正式发布。

所有提交到 v4 分支的提交和 PR 都会自动创建预览版本。通过将你的包版本替换为特定的提交哈希或 PR 编号来使用它们。

package.json

{
  "dependencies": {
-   "@nuxt/ui": "^4.0.0",
+   "@nuxt/ui": "https://pkg.pr.new/@nuxt/ui@4c96909",
  }
}

pkg.pr.new 将自动在 PR 上评论安装 URL，方便测试更改。