模块配置

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

介绍

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

Prefix

  • 类型: string
  • 默认值: 'M'

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

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

Theme

主题模块统一管理颜色、圆角、字体与图标集，并向 ThemePicker 组件、useTheme composable 提供可选项。所有字段都在 movk.theme 下配置。

主题系统的运行时能力（动态切换、CSS 导出）见主题文档；交互式调参见 ThemePicker 组件。
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'。
fonts
ThemeFontConfig[]
ThemePicker 字体可选项；提供时完整替换内置列表。每项为 { name, href? }，href 缺省时运行时回退到 Google Fonts。
radiuses
number[]
ThemePicker 圆角可选项（单位 rem）。默认 [0, 0.125, 0.25, 0.375, 0.5]。
neutralColors
string[]
ThemePicker neutral 颜色可选项。

自定义字体可选项

nuxt.config.ts
export default defineNuxtConfig({
  movk: {
    theme: {
      fonts: [
        { name: 'Alibaba PuHuiTi', href: 'https://cdn.mhaibaraai.cn/fonts/alibaba-puhuiti.css' },
        { name: 'Inter' } // 无 href，回退到 Google Fonts
      ]
    }
  }
})

API

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

API 系统的完整使用方法请参考 API 文档。

基础配置

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 端点，每个端点可以有独立的配置：

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-API-Key': 'your-api-key'
          }
        }
      }
    }
  }
})

端点选项

baseURL
string required
端点的基础 URL。
alias
string
端点别名。
headers
Record<string, string>
该端点的默认请求头 仅服务端使用，不会暴露给客户端。
auth
Partial<ApiAuthConfig>
该端点的认证配置，会与全局配置合并。
toast
Partial<ApiToastConfig>
该端点的 Toast 配置，会与全局配置合并。
response
Partial<ApiResponseConfig>
该端点的响应配置，会与全局配置合并。

auth

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

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
        }
      }
    }
  }
})

认证选项

enabled
boolean
是否启用认证。默认 false。
tokenSource
'session'
Token 来源，从 nuxt-auth-utils 的 session 中获取。默认 'session'。
sessionTokenPath
string
Session 中 token 的路径。例如 'token' 对应 session.token，'user.token' 对应 session.user.token。默认 'token'。
tokenType
'Bearer' | 'Basic' | 'Custom'
Token 类型。默认 'Bearer'。
customTokenType
string
自定义 Token 类型值，当 tokenType 为 'Custom' 时使用。
headerName
string
请求头名称。默认 'Authorization'。
unauthorized
ApiUnauthorizedConfig
401 未授权处理配置。

response

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

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 提示行为：

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 }
成功提示配置。
error
Partial<Toast> & { show?: boolean }
错误提示配置。

配置优先级

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

  1. 模块内置默认值 - api-defaults.ts 中定义的默认配置
  2. 全局配置 - movk.api.auth、movk.api.toast、movk.api.response
  3. 端点配置 - movk.api.endpoints[name].auth 等
  4. 请求级配置 - useApiFetch 的 toast 选项等
// 示例：请求级配置覆盖全局配置
const { data } = await useApiFetch('/users', {
  toast: {
    successMessage: '获取成功', // 覆盖全局配置
    error: false // 禁用错误提示
  }
})

环境变量

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

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
          }
        }
      }
    }
  }
})
.env
EXTERNAL_API_URL=https://api.example.com
EXTERNAL_API_KEY=your-api-key
不要将敏感信息（如 API 密钥、密码）直接写在配置文件中，始终使用环境变量。

安装

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

Vue / Vite

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

Copyright © 2025 - 2026 YiXuan - MIT License