---
title: "安装"
description: "在 Nuxt 4 项目中安装和配置 Movk Nuxt 模块。"
seo_title: "Installation"
seo_description: "Install and register the Movk Nuxt module in a Nuxt 4 project with pnpm, npm or yarn, including the required @nuxt/ui and zod peer dependencies."
canonical_url: "https://nuxt.mhaibaraai.cn/docs/getting-started/installation"
---
# 安装

> 在 Nuxt 4 项目中安装和配置 Movk Nuxt 模块。

> \[\!NOTE\]
> See: /docs/getting-started/vue
> 
> 在 
> 
> Vue + Vite
> 
> （非 Nuxt）项目中使用？请看 Vue / Vite 模式说明。

## 环境要求

> \[\!NOTE\]
> 
> - **Node.js** \- `^20.19.0 || >=22.12.0`
> - **Nuxt** \- `>=4.4.2`（需要 Nuxt 4）
> - **包管理器** \- pnpm / npm / yarn

## 添加到 Nuxt 项目

### 安装所需依赖

> \[\!WARNING\]
> 
> Movk Nuxt
> 
>  依赖 
> 
> @nuxt/ui
> 
>  和 
> 
> zod
> 
> ，请确保已安装。

> \[\!WARNING\]
> 
> 如果你使用的是 pnpm ：
> 
> - 请确保你在 `.npmrc` 文件中设置 `shamefully-hoist=true`
> - 或者在项目的根目录中安装 `tailwindcss`

```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
```

### 模块配置

在 `nuxt.config.ts` 中注册模块：

```diff [nuxt.config.ts]
export default defineNuxtConfig({
+  modules: ['@movk/nuxt']
})
```

### 引入样式

在项目的 CSS 入口中引入模块样式，并在 `nuxt.config.ts` 的 `css` 中注册该文件：

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

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

> \[\!NOTE\]
> 
> @movk/nuxt
> 
>  内部已引入 
> 
> @nuxt/ui
> 
> ，无需再单独 
> 
> @import "@nuxt/ui"
> 
> 。整个项目应只有这一个 Tailwind 入口：多写一处 
> 
> @import "tailwindcss"
> 
>  会形成第二个 Tailwind 上下文，其默认主题变量会覆盖模块注入的 
> 
> --font-sans
> 
>  等值。

### 安装图标集

组件图标取自 Iconify 的 `lucide` 图标集。装上对应的 `@iconify-json` 包，模块会在构建期把组件用到的图标内联进产物；不装则改为运行时向 Iconify API 按需请求，内网或离线环境会拿不到图标。

```bash [pnpm]
pnpm add -D @iconify-json/lucide
```

```bash [npm]
npm install -D @iconify-json/lucide
```

```bash [yarn]
yarn add -D @iconify-json/lucide
```

模块只负责自己组件用到的图标，项目自己写的图标名需开启扫描才会一并入包：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  icon: {
    clientBundle: {
      scan: { globInclude: ['**/*.{vue,jsx,tsx,ts,md,mdc,mdx,yml,yaml}'] }
    }
  }
})
```

> \[\!NOTE\]
> 
> @nuxt/icon
> 
>  默认的 
> 
> globInclude
> 
>  不含 
> 
> .ts
> 
> ，写在 composable、常量文件里的图标名会漏扫，故此处显式补上 
> 
> ts
> 
> 。

## 可选配置

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@movk/nuxt'],
  movk: {
    // 组件前缀 (默认: 'M')
    prefix: 'M'
  }
})
```

## TypeScript 支持

Movk Nuxt 提供完整的 TypeScript 类型定义，安装后自动注入到项目中。

```ts
import type { z } from 'zod'

const { afz } = useAutoForm()

const schema = afz.object({
  email: afz.email(), // ✅ 完整的类型提示
  age: afz.number()
})

// 从 schema 推断数据类型
type FormData = z.output<typeof schema>
```

## Zod v4 集成

Movk Nuxt 使用 **Zod v4**，它引入了一些重要的 API 变更：

```ts [✅ 正确用法 (Zod v4)]
import { z } from 'zod'

// 使用专用验证函数
const emailSchema = z.email()
const urlSchema = z.url()
const uuidSchema = z.uuid()
const datetimeSchema = z.iso.datetime()
```

```ts [❌ 已废弃 (Zod v3)]
import { z } from 'zod'

// 不要使用旧的字符串验证方法
const emailSchema = z.string().email()
const urlSchema = z.string().url()
const uuidSchema = z.string().uuid()
```

> \[\!TIP\]
> See: https://zod.dev/api
> 
> 查看 Zod 官方文档了解更多 v4 变更


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.