模块配置

配置组件前缀、API 端点、认证策略、响应解析规则和 Toast 提示行为

介绍

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

`prefix`

类型: string
默认值: 'M'

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

nuxt.config.ts

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

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

{ show, color, icon?, duration }

成功提示配置。

error

{ show, color, icon?, duration }

错误提示配置。

配置优先级

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

模块内置默认值 - api-defaults.ts 中定义的默认配置
全局配置 - movk.api.auth、movk.api.toast、movk.api.response
端点配置 - movk.api.endpoints[name].auth 等
请求级配置 - 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 模块

MCP Server

在 AI 助手中通过 Model Context Protocol 使用 Movk Nuxt。