---
title: "Vue / Vite"
description: "在纯 Vue + Vite 项目中使用 Movk 的独立组件、主题与 Composables，无需 Nuxt。"
seo_title: "Vue / Vite"
seo_description: "Use Movk standalone components, theming and composables in a plain Vue + Vite app via @movk/nuxt/vite and @movk/nuxt/vue-plugin, without 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 层叠正确。

## 选项

在 `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`，详见 [主题系统 · 字体](/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/*` 包，未安装的图标集会被自动跳过（不会导致构建失败），详见 [主题系统 · 图标集](/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](/sitemap.md) for all pages.