---
title: "Vue / Vite"
description: "在纯 Vue + Vite 项目中使用 Movk 的独立组件、主题与 Composables，无需 Nuxt。"
canonical_url: "https://nuxt.mhaibaraai.cn/docs/getting-started/vue"
---
# Vue / Vite

> 在纯 Vue + Vite 项目中使用 Movk 的独立组件、主题与 Composables，无需 Nuxt。

> [!NOTE]
> See: /docs/getting-started/installation
> 
> 使用 
> 
> Nuxt
> 
> ？请看 Nuxt 模式的安装说明。

`@movk/nuxt` 不仅是 Nuxt 模块，还提供 Vite 插件（`@movk/nuxt/vite`）与 Vue 插件（`@movk/nuxt/vue-plugin`），让独立 UI 组件、AutoForm / DataTable、主题与非服务端 Composables 在纯 Vue + Vite 项目中直接可用。

> [!WARNING]
> 
> Vue / Vite 模式
> 
> 不包含 API 集成域
> 
> （
> 
> useApiFetch
> 
>  / 
> 
> useLazyApiFetch
> 
>  / 
> 
> useClientApiFetch
> 
> 、上传下载、
> 
> $api
> 
>  插件、鉴权与错误 toast 等），它们依赖 Nuxt 服务端运行时，仅在 Nuxt 模式下可用。

## 安装

### 安装依赖

```bash [pnpm]
pnpm add @movk/nuxt @nuxt/ui zod tailwindcss
```

```bash [npm]
npm install @movk/nuxt @nuxt/ui zod tailwindcss
```

```bash [yarn]
yarn add @movk/nuxt @nuxt/ui zod tailwindcss
```

vue-router 默认启用（`ui.router` 选项控制）。若使用默认值，请同时安装 `vue-router`：

```bash [pnpm]
pnpm add vue-router
```

```bash [npm]
npm install vue-router
```

### 添加 Vite 插件

在 `vite.config.ts` 注册 `movk()` 插件：

```ts [vite.config.ts (Vite)]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import movk from '@movk/nuxt/vite'

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

```ts [vite.config.ts (Inertia)]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import movk from '@movk/nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    movk({
      ui: {
        router: 'inertia'
      }
    })
  ]
})
```

> [!TIP]
> 
> `movk()` 内部注册了 `unplugin-auto-import` 与 `unplugin-vue-components`，会生成 `auto-imports.d.ts` 与 `components.d.ts`。建议将它们加入 `.gitignore` 并在 `tsconfig` 中 include。
> 
> ```json [tsconfig.app.json]
> {
>   "include": ["src/**/*.ts", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
> }
> ```
> 
> ```bash [.gitignore]
> auto-imports.d.ts
> components.d.ts
> ```

> [!TIP]
> 
> 若使用 TypeScript，可在 `tsconfig` 中为主题虚拟模块添加别名，以在 `vite.config.ts` 获得补全：
> 
> ```json [tsconfig.node.json]
> {
>   "compilerOptions": {
>     "paths": {
>       "#build/movk-ui": ["./node_modules/.movk-ui/movk-ui"],
>       "#build/ui": ["./node_modules/.nuxt-ui/ui"]
>     }
>   }
> }
> ```

### 注册 Vue 插件

在入口注册 `@movk/nuxt/vue-plugin`（内部已链入 `@nuxt/ui/vue-plugin`）：

```ts [src/main.ts]
import './assets/css/main.css'
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import movk from '@movk/nuxt/vue-plugin'
import App from './App.vue'

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

createApp(App)
  .use(router)
  .use(movk)
  .mount('#app')
```

### 引入样式

```css [src/assets/css/main.css]
@import "tailwindcss";
@import "@movk/nuxt";
```

### 用 `<UApp>` 包裹根组件

`<UApp>` 提供 Toast、Tooltip 与命令式 overlay 的全局上下文，`useMessageBox` 依赖它：

```vue [src/App.vue]
<template>
  <UApp>
    <RouterView />
  </UApp>
</template>
```

> [!NOTE]
> 
> 根容器建议加 
> 
> class="isolate"
> 
> （
> 
> index.html
> 
>  的 
> 
> #app
> 
> ），确保样式作用域与 overlay 层叠正确。

## 与 UnoCSS / 已有全局样式共存

在已有项目中接入时，常见的问题是 Nuxt UI 组件的背景、内边距、圆角等样式不生效。原因在于级联层：Tailwind 的工具类位于 `@layer utilities`，而**任何未分层的样式都会压过 @layer 内的样式，与选择器优先级无关**。UnoCSS 默认输出的 preflight（reset）以及项目自带的全局 reset 都属于未分层样式。

> [!TIP]
> 
> 在浏览器 DevTools 的「样式」面板中，没有标注「级联层」的规则就是未分层样式。dev 模式下检测到 UnoCSS 输出未分层的 reset 时，
> 
> movk()
> 
>  会在终端给出警告。

### 关闭 UnoCSS 的 reset

`@import "tailwindcss"` 已在 `@layer base` 中提供等价的 reset，直接关闭 UnoCSS 的 reset 即可：

```ts [uno.config.ts]
import { defineConfig, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4({
      preflights: { reset: false }
    })
  ]
})
```

> [!WARNING]
> 
> presetWind4
> 
>  的开关是 
> 
> preflights.reset
> 
> ，写成顶层的 
> 
> reset: false
> 
>  不会生效。

### 把 UnoCSS 的 preflight 归入 base 层

如果需要保留 UnoCSS 的 preflight，可以用 `outputToCssLayers` 把它放进 Tailwind 的 `base` 层，工具类则保持未分层：

```ts [uno.config.ts]
export default defineConfig({
  outputToCssLayers: {
    cssLayerName: layer => layer === 'preflights' ? 'base' : null
  }
})
```

> [!NOTE]
> 
> 不建议把 UnoCSS 的工具类也放进 layer：项目里如果还有 Element Plus 等未分层的组件库样式，分层后的工具类会输给它们，原本用工具类覆盖组件库样式的写法会失效。

### 把已有的全局 reset 放进 base 层

项目自带的 reset 用 `@layer base` 包裹后，就不会覆盖 Nuxt UI 的工具类：

```css [src/styles/reset.css]
@layer base {
  *,
  ::before,
  ::after {
    margin: 0;
    padding: 0;
  }
}
```

## 选项

在 `vite.config.ts` 的 `movk()` 中传入选项进行配置。

### `prefix` 组件前缀

组件名前缀。

- 默认：`M`

```ts [vite.config.ts]
movk({
  prefix: 'M'
})
```

### `site` 站点信息

站点名称，影响主题持久化的 localStorage key 前缀（`<name>-ui-*`）。

```ts [vite.config.ts]
movk({
  site: { name: 'my-app' }
})
```

### `theme` 主题

`theme.colors`（颜色别名）、`theme.defaultVariants`（默认变体）、`theme.prefix`（与 Tailwind 前缀一致）、`theme.font`（字体）等，对齐 Nuxt 模式 `movk.theme`。`font` 与 Nuxt 模式行为一致：构建期把字体样式表的 `<link>` 注入 `index.html`（`vite dev`/`vite build` 均生效），并写入 `--font-sans`，详见 [主题系统 · 字体](https://nuxt.mhaibaraai.cn/docs/getting-started/theme#%E5%AD%97%E4%BD%93)。

```ts [vite.config.ts]
movk({
  theme: {
    defaultVariants: {
      color: 'neutral',
      size: 'sm'
    }
  }
})
```

### `icon` 图标

`icon.clientBundle` 控制 movk 组件与内置图标集用到的图标是否进入构建期图标包，对齐 Nuxt 模式 `movk.icon`。图标数据需要项目安装对应的 `@iconify-json/*` 包，未安装的图标集会被自动跳过（不会导致构建失败），详见 [主题系统 · 图标集](https://nuxt.mhaibaraai.cn/docs/getting-started/theme#%E5%9B%BE%E6%A0%87%E9%9B%86)。

```ts [vite.config.ts]
movk({
  icon: { clientBundle: false }
})
```

### `ui`

`ui` 是 `@nuxt/ui` unplugin 配置（`Partial<NuxtUIOptions>`）的透传口，承载 `router`、`colorMode`、`autoImport`、`components`、`dts`、`icon`、`ui` 主题等。movk 会把自身 composables 与组件解析自动注入 `ui.autoImport` / `ui.components` / `ui.icon.clientBundle.icons`，无需手动配置即可使用。

> [!NOTE]
> See: https://ui.nuxt.com/docs/getting-started/installation/vue#options
> 
> 查看 Nuxt UI 模块文档 了解 
> 
> ui
> 
>  选项的完整配置与功能。


## Sitemap

See the full [sitemap](https://nuxt.mhaibaraai.cn/sitemap.md) for all pages.