ViteBuild 构建工具

ViteBuild 是一个用于构建 Vue 组件库的工具，支持根据环境（Node.js 或浏览器）自动选择打包格式，并支持全局配置和单个组件配置。

功能特性

• ✅ 支持环境检测（Node.js / 浏览器）
• ✅ 支持全局配置和单个组件配置
• ✅ 支持多种打包格式（ES、CJS、UMD、IIFE）
• ✅ 根据环境自动选择打包格式
• ✅ 工具函数模块化，易于维护

使用方法

基础使用

import { runBuildCliAndExit } from '@moluoxixi/utils/ViteBuild'

runBuildCliAndExit(
  {
    libNamespace: 'moluoxixi',
    aliasComponentPath: '@moluoxixi/components',
    packDir: resolve(__dirname, '../'),
    // ... 其他配置
  },
  { uploadType: 'Vue3', command: 'build-publish' },
)

配置打包格式

全局配置

import { runBuildCliAndExit } from '@moluoxixi/utils/ViteBuild'
import type { GlobalFormatConfig } from '@moluoxixi/utils/ViteBuild'

const formatConfig: GlobalFormatConfig = {
  // 指定环境（可选，默认为 false，即浏览器环境）
  // 方式1：全局指定 isNodeEnv
  // isNodeEnv: true, // 或 false，或不指定（默认 false）

  // Node 环境下的打包格式配置（可选，默认值为 { cjs: true }）
  // 配置会与默认值合并，未指定的格式保持默认值
  nodeFormats: {
    // cjs: true 是默认值，无需显式指定
    // 如需添加其他格式，可在此配置，例如：
    // es: true,   // 在默认 CJS 基础上添加 ES 模块
  },

  // 浏览器环境下的打包格式配置（可选，默认值为 { es: true }）
  // 配置会与默认值合并，未指定的格式保持默认值
  browserFormats: {
    // es: true 是默认值，无需显式指定
    umd: true,   // 在默认 ES 基础上添加 UMD 模块
  },

  // 单个组件的格式配置覆盖（可选）
  // 组件配置会与对应环境的默认值和全局配置合并
  componentFormats: {
    // 针对特定组件的配置
    'CardReader': {
      // 浏览器环境默认有 es: true，这里添加 cjs: true
      cjs: true,  // 在默认 ES 基础上添加 CJS 格式
    },
    'AIAgent': {
      // 浏览器环境默认有 es: true，这里添加 umd 和 iife
      umd: true,
      iife: true, // 在默认 ES 基础上添加 IIFE 格式
    },
    // 方式2：为特定组件指定 Node 环境（优先级高于全局 isNodeEnv）
    'ViteBuild': {
      isNodeEnv: true, // 指定为 Node 环境
      // nodeFormats 默认为 { cjs: true }，如需覆盖可在此配置
    },
  },
}

runBuildCliAndExit(
  {
    libNamespace: 'moluoxixi',
    aliasComponentPath: '@moluoxixi/components',
    packDir: resolve(__dirname, '../'),
    formatConfig, // 传入格式配置
    // ... 其他配置
  },
  { uploadType: 'Vue3', command: 'build-publish' },
)

默认行为

如果不提供 formatConfig，系统会使用以下默认配置：

• Node 环境：只打包 CJS 格式
• 浏览器环境：打包 ES 和 UMD 格式

工具函数分类

所有工具函数已按功能分类到 _utils 目录：

• _utils/cli.ts - CLI 相关函数
• _utils/version.ts - 版本管理函数
• _utils/deps.ts - 依赖分析函数
• _utils/config.ts - 配置相关函数
• _utils/env.ts - 环境检测函数
• _utils/component.ts - 组件相关工具函数
• _utils/viteConfig.ts - Vite 配置相关函数

所有类型定义在 _types 目录：

• _types/index.ts - 所有类型定义

配置说明

GlobalFormatConfig

全局格式配置接口：

interface GlobalFormatConfig {
  /** 是否为 Node 环境（可选，默认为 false，即浏览器环境） */
  isNodeEnv?: boolean
  /** Node 环境下的打包格式配置 */
  nodeFormats?: ComponentFormatConfig
  /** 浏览器环境下的打包格式配置 */
  browserFormats?: ComponentFormatConfig
  /** 单个组件的格式配置覆盖（组件名 -> 格式配置） */
  componentFormats?: Record<string, ComponentFormatConfig>
}

ComponentFormatConfig

组件格式配置接口（可在 componentFormats 中使用）：

interface ComponentFormatConfig {
  /** 是否为 Node 环境（可选，用于在 componentFormats 中指定单个组件的环境，优先级高于全局 isNodeEnv） */
  isNodeEnv?: boolean
  /** 是否打包 ES 模块格式 */
  es?: boolean
  /** 是否打包 CJS 模块格式 */
  cjs?: boolean
  /** 是否打包 UMD 模块格式 */
  umd?: boolean
  /** 是否打包 IIFE 模块格式 */
  iife?: boolean
}

ComponentFormatConfig

组件格式配置接口：

interface ComponentFormatConfig {
  /** 是否打包 ES 模块格式 */
  es?: boolean
  /** 是否打包 CJS 模块格式 */
  cjs?: boolean
  /** 是否打包 UMD 模块格式 */
  umd?: boolean
  /** 是否打包 IIFE 模块格式 */
  iife?: boolean
}

示例

示例 1：使用默认配置（浏览器环境，ES 格式）

// 不提供 formatConfig，使用默认值（浏览器环境，ES 格式）
runBuildCliAndExit(
  {
    // ... 其他配置
    // 不提供 formatConfig
  },
  { uploadType: 'Vue3', command: 'build-publish' },
)

示例 2：Node 环境只打 CJS（使用默认值）

const formatConfig: GlobalFormatConfig = {
  isNodeEnv: true,
  // nodeFormats 默认为 { cjs: true }，无需配置
}

示例 2.1：指定特定组件使用 Node 环境

const formatConfig: GlobalFormatConfig = {
  // 默认浏览器环境，通过 componentFormats 为特定组件指定 Node 环境
  componentFormats: {
    'ViteBuild': {
      isNodeEnv: true, // 指定为 Node 环境
      // nodeFormats 默认为 { cjs: true }，如需覆盖可在此配置
    },
    'ViteConfig': {
      isNodeEnv: true, // 指定为 Node 环境
    },
    'EslintConfig': {
      isNodeEnv: true, // 指定为 Node 环境
    },
  },
  // 这些组件会使用 nodeFormats 配置（默认 { cjs: true }）
  // 其他组件使用 browserFormats 配置（默认 { es: true }）
}

示例 3：浏览器环境打 ES 和 UMD（在默认值基础上添加）

const formatConfig: GlobalFormatConfig = {
  // isNodeEnv 默认为 false（浏览器环境），可省略
  browserFormats: {
    // es: true 是默认值，无需显式指定
    umd: true, // 在默认 ES 基础上添加 UMD
  },
}

示例 4：Node 环境打 CJS 和 ES（在默认值基础上添加）

const formatConfig: GlobalFormatConfig = {
  isNodeEnv: true,
  nodeFormats: {
    // cjs: true 是默认值，无需显式指定
    es: true, // 在默认 CJS 基础上添加 ES
  },
}

示例 5：特定组件特殊配置（合并默认值和全局配置）

const formatConfig: GlobalFormatConfig = {
  isNodeEnv: false,
  browserFormats: {
    umd: true, // 全局：ES（默认）+ UMD
  },
  componentFormats: {
    // 这个组件在浏览器环境打 ES（默认）+ UMD（全局）+ CJS（组件特有）
    'ViteConfig': {
      cjs: true, // 在默认 ES 和全局 UMD 基础上添加 CJS
    },
  },
}

默认值说明

• Node 环境默认格式：{ cjs: true } - 只打包 CJS 格式
• 浏览器环境默认格式：{ es: true } - 只打包 ES 格式

配置合并规则

1. 默认值 → 全局配置 → 组件配置（后面的配置会合并覆盖前面的配置）
2. 如果某个格式在配置中未指定，则使用默认值或上一级配置的值
3. 配置是合并而非替换，例如：
   • 默认值：{ cjs: true }
   • 全局配置：{ es: true }
   • 最终结果：{ cjs: true, es: true }（合并）

注意事项

1. formatConfig 和 isNodeEnv 都是可选的：
   • 如果不提供 formatConfig，默认使用浏览器环境，打包 ES 格式
   • 如果提供 formatConfig 但不指定 isNodeEnv，默认为 false（浏览器环境）
2. nodeFormats 和 browserFormats 有默认值，只需配置需要添加或覆盖的格式
3. 组件特定配置会与全局配置和默认值合并
4. package.json 的 exports 字段会根据实际打包的格式自动生成