---
title: "模块配置"
description: "配置组件前缀、主题颜色、字体、API 端点、认证策略、响应解析规则和 Toast 提示行为。"
seo_title: "Module Configuration"
seo_description: "Configure the component prefix, theme (colors, fonts, radiuses, neutral colors), and the API system (endpoints, auth, response parsing, toast) of the Movk Nuxt module."
canonical_url: "https://nuxt.mhaibaraai.cn/docs/getting-started/configuration"
---
# 模块配置

> 配置组件前缀、主题颜色、字体、API 端点、认证策略、响应解析规则和 Toast 提示行为。

## 介绍

Movk Nuxt 使用 `movk` 作为配置键，在 `nuxt.config.ts` 中进行配置：

## `Prefix`

- **类型**: `string`
- **默认值**: `'M'`

组件前缀，用于避免与其他组件库的命名冲突。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    prefix: 'My' // 组件变为 MyAutoForm, MyDatePicker 等
  }
})
```

## `Theme`

主题模块统一管理颜色、圆角、图标集与字体。前三者向 `ThemePicker` 组件、`useTheme` composable 提供可选项，字体则在构建期注入。所有字段都在 `movk.theme` 下配置。

> \[\!NOTE\]
> See: /docs/getting-started/theme
> 
> 主题系统的运行时能力（动态切换、CSS 导出）见主题文档；交互式调参见 
> 
> ThemePicker
> 
>  组件。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    theme: {
      enabled: true
    }
  }
})
```

**enabled** (`boolean`): 是否启用主题模块（appConfig 默认值、theme plugin、ThemePicker 组件注册）。默认 true。关闭后 ThemePicker 不再注册。

**colors** (`string[]`): 组件可用的颜色别名列表，透传给 @nuxt/ui 的 theme.colors。默认 \['primary', 'secondary', 'success', 'info', 'warning', 'error'\]。

**defaultVariants** (`object`): 组件默认变体，透传给 @nuxt/ui 的 theme.defaultVariants。

**prefix** (`string`): Tailwind CSS 工具类前缀，透传给 @nuxt/ui 的 theme.prefix。例如 'tw'。

**font** (`string | ThemeFontOption`): 全局字体。内置字体给名字即可（'Alibaba PuHuiTi'、'OPPO Sans'），模块在构建期注入样式表、preconnect 与带中文回退栈的 --font-sans；自托管字体用 { name, href } 形式补上入口 CSS 地址。缺省时不注入 --font-sans，字体由项目 CSS 的 @theme 决定。字体名称，须与样式表中 @font-face 声明的 font-family 逐字一致。字体入口 CSS 的地址。例如 '/fonts/my-font.css'。内置字体可省略。既非内置、又没提供该字段的字体不会产生任何请求。

**radius** (`number`): 默认圆角（单位 rem）。缺省时不注入 --ui-radius，沿用 @nuxt/ui 的默认值或项目 CSS 的声明。例如 0.5。

**radiuses** (`number[]`): ThemePicker 圆角可选项（单位 rem）。默认 \[0, 0.125, 0.25, 0.375, 0.5\]。

**neutralColors** (`string[]`): ThemePicker neutral 颜色可选项。

### 自定义字体

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    theme: {
      // 内置字体给名字即可
      font: 'Alibaba PuHuiTi'
      // 自托管字体补上入口 CSS 地址
      // font: { name: 'My Font', href: '/fonts/my-font.css' }
    }
  }
})
```

## `Icon`

控制模块自有图标是否进入 `@nuxt/icon` 的构建期图标包。

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    icon: {
      clientBundle: true
    }
  }
})
```

**clientBundle** (`boolean`): 是否把 movk 组件与内置图标集用到的图标注入构建期图标包。默认 true。关闭后这些图标改为运行时按需请求。

> \[\!NOTE\]
> See: /docs/getting-started/theme
> 
> 图标集切换与 
> 
> @iconify-json/\*
> 
>  的安装说明见主题文档 · 图标集。

## API

API 系统提供完整的请求封装和认证管理，通过 `api` 选项配置。

> \[\!NOTE\]
> See: /docs/api
> 
> API 系统的完整使用方法请参考 API 文档。

### 基础配置

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      // 是否启用 API 功能
      enabled: true,
      // 默认使用的端点名称
      defaultEndpoint: 'default',
      // 是否启用调试模式
      debug: false
    }
  }
})
```

**enabled** (`boolean`): 是否启用 API 功能。默认 true。

**defaultEndpoint** (`string`): 默认使用的端点名称。默认 'default'。

**debug** (`boolean`): 是否启用调试模式，开启后会在控制台输出请求日志。默认 false。

### `endpoints`

支持配置多个 API 端点，每个端点可以有独立的配置：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      endpoints: {
        // 默认端点
        default: {
          baseURL: '/api'
        },
        // 管理端点
        admin: {
          baseURL: '/admin-api',
          auth: {
            tokenType: 'Bearer'
          }
        },
        // 第三方 API
        external: {
          baseURL: 'https://api.example.com',
          // 仅服务端注入
          headers: {
            'X-Secret-Key': process.env.EXTERNAL_SECRET_KEY
          },
          // 两端均注入
          publicHeaders: {
            'X-Api-Version': '2'
          }
        }
      }
    }
  }
})
```

#### 端点选项

**baseURL** (`string`) *required*: 端点的基础 URL。

**alias** (`string`): 端点别名。

**headers** (`Record<string, string>`): 该端点的默认请求头 仅服务端使用，不会暴露给客户端。

**publicHeaders** (`Record<string, string>`): 该端点的公开请求头，会进入 public runtimeConfig，服务端与客户端均注入。同名键由 headers 覆盖。仅用于非机密固定头。

**auth** (`Partial<ApiAuthConfig>`): 该端点的认证配置，会与全局配置合并。

**toast** (`Partial<ApiToastConfig>`): 该端点的 Toast 配置，会与全局配置合并。

**response** (`Partial<ApiResponseConfig>`): 该端点的响应配置，会与全局配置合并。

### `auth`

配置自动认证行为，与 `nuxt-auth-utils` 集成：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      auth: {
        // 启用认证
        enabled: true,
        // Token 来源
        tokenSource: 'session',
        // Session 中 token 的路径
        sessionTokenPath: 'user.accessToken',
        // Token 类型
        tokenType: 'Bearer',
        // 请求头名称
        headerName: 'Authorization',
        // 401 未授权处理配置
        unauthorized: {
          // 401 时跳转登录页
          redirect: true,
          loginPath: '/login',
          // 401 时清除 session
          clearSession: true
        }
      }
    }
  }
})
```

浏览器直连第三方 API 时，把凭据放进 `runtimeConfig.public` 并指向它：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      llmApiKey: ''
    }
  },
  movk: {
    api: {
      auth: {
        enabled: true,
        tokenSource: 'public-runtime-config',
        tokenPath: 'llmApiKey',
        tokenType: 'Bearer',
        unauthorized: {
          redirect: false
        }
      }
    }
  }
})
```

```bash [.env]
NUXT_PUBLIC_LLM_API_KEY=your-api-key
```

> \[\!WARNING\]
> 
> public-runtime-config
> 
>  与 
> 
> publicHeaders
> 
>  的取值都会随页面下发到浏览器，任何访问者都能读取。仅在凭据本身设计为公开、或作用域已收窄到可接受时使用；账户级密钥请走服务端代理。

#### 认证选项

**enabled** (`boolean`): 是否启用认证。默认 false。

**tokenSource** (`'session' | 'public-runtime-config'`): Token 来源。'session' 从 nuxt-auth-utils 的 session 中获取；'public-runtime-config' 从 runtimeConfig.public 中获取，用于凭据本就需要在浏览器暴露的场景。默认 'session'。

**sessionTokenPath** (`string`): Session 中 token 的路径。例如 'token' 对应 session.token，'user.token' 对应 session.user.token。默认 'token'。

**tokenPath** (`string`): runtimeConfig.public 中 token 的路径，支持点号嵌套。仅当 tokenSource 为 'public-runtime-config' 时生效。默认 'apiToken'。

**tokenType** (`'Bearer' | 'Basic' | 'Custom'`): Token 类型。默认 'Bearer'。

**customTokenType** (`string`): 自定义 Token 类型值，当 tokenType 为 'Custom' 时使用。

**headerName** (`string`): 请求头名称。默认 'Authorization'。

**unauthorized** (`ApiUnauthorizedConfig`): 401 未授权处理配置。401 错误时是否自动跳转登录页。默认 true。登录页路径。默认 '/login'。401 错误时是否自动清除 session。默认 true。

### `response`

配置 API 响应的解析规则，包括业务状态码判断、数据解包字段和消息提取：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      response: {
        // 成功状态码列表
        successCodes: [200, 0],
        // 状态码字段名
        codeKey: 'code',
        // 消息字段名
        messageKey: 'message',
        // 数据字段名
        dataKey: 'data'
      }
    }
  }
})
```

#### 响应配置选项

**successCodes** (`(number | string)[]`): 成功状态码列表，响应中的 code 值在此列表中视为成功。默认 \[200, 0\]。

**codeKey** (`string`): 响应中状态码的字段名。默认 'code'。

**messageKey** (`string`): 响应中消息的字段名。默认 'message'。

**dataKey** (`string`): 响应中数据的字段名。默认 'data'。

### `toast`

配置全局 Toast 提示行为：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      toast: {
        // 全局启用提示
        enabled: true,
        // 成功提示配置
        success: {
          show: true,
          color: 'success',
          duration: 3000
        },
        // 错误提示配置
        error: {
          show: true,
          color: 'error',
          duration: 3000
        }
      }
    }
  }
})
```

#### Toast 选项

**enabled** (`boolean`): 是否全局启用提示。默认 true。

**success** (`Partial<Toast> & { show?: boolean }`): 成功提示配置。show: false 关闭成功提示。

**error** (`Partial<Toast> & { show?: boolean }`): 错误提示配置。show: false 关闭错误提示。

> \[\!NOTE\]
> 
> enabled
> 
>  与 
> 
> show
> 
>  均为全局开关，请求级传 
> 
> toast: { success: { show: true } }
> 
>  可单次覆盖开启；优先级为请求级 
> 
> show
> 
>  \> 全局 
> 
> success.show
> 
>  / 
> 
> error.show
> 
>  \> 全局 
> 
> enabled
> 
> 。

## 配置优先级

配置按以下优先级合并（后者覆盖前者）：

1. **模块内置默认值** \- `api-defaults.ts` 中定义的默认配置
2. **全局配置** \- `movk.api.auth`、`movk.api.toast`、`movk.api.response`
3. **端点配置** \- `movk.api.endpoints[name].auth` 等
4. **请求级配置** \- `useApiFetch` 的 `toast` 选项等

```ts
// 示例：请求级配置覆盖全局配置
const { data } = await useApiFetch('/users', {
  toast: {
    successMessage: '获取成功', // 覆盖全局配置
    error: false // 禁用错误提示
  }
})
```

请求头按以下顺序叠加（后者覆盖前者）：

1. **端点 `publicHeaders`** \- 服务端与客户端均注入
2. **端点 `headers`** \- 仅服务端注入，覆盖同名 `publicHeaders`
3. **请求级 `headers`** \- 调用 `$api` 或 `useApiFetch` 时传入
4. **auth 注入** \- `onRequest` 拦截器按 `headerName` 写入，优先级最高

## 环境变量

对于敏感配置（如 API 密钥），建议使用环境变量：

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      endpoints: {
        external: {
          baseURL: process.env.EXTERNAL_API_URL,
          headers: {
            'X-API-Key': process.env.EXTERNAL_API_KEY
          }
        }
      }
    }
  }
})
```

```bash [.env]
EXTERNAL_API_URL=https://api.example.com
EXTERNAL_API_KEY=your-api-key
```

> \[\!WARNING\]
> 
> 不要将敏感信息（如 API 密钥、密码）直接写在配置文件中，始终使用环境变量。


## Sitemap

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