buildProgress

在 Vite 构建过程中实时显示终端构建进度条，支持多种显示格式和自定义主题。

导入方式

// 子模块独立导入（推荐）
import { buildProgress } from '@meng-xi/vite-plugin/plugins/build-progress'
import type { BuildProgressOptions, ProgressFormat, ProgressTheme, BuildPhase } from '@meng-xi/vite-plugin/plugins/build-progress'

// barrel 导入
import { buildProgress } from '@meng-xi/vite-plugin'

快速开始

import { defineConfig } from 'vite'
import { buildProgress } from '@meng-xi/vite-plugin'

export default defineConfig({
	plugins: [buildProgress()]
})

配置选项

选项	类型	默认值	说明
width	number	30	进度条宽度（字符数）
format	ProgressFormat	'bar'	进度条显示格式
completeChar	string	'█'	已完成部分的填充字符
incompleteChar	string	'░'	未完成部分的填充字符
clearOnComplete	boolean	true	构建完成后是否清除进度条
showModuleName	boolean	true	是否显示当前处理模块名称
theme	ProgressTheme	-	自定义颜色主题
enabled	boolean	true	启用插件
verbose	boolean	true	显示详细日志
errorStrategy	'throw' | 'log' | 'ignore'	'throw'	错误处理策略

显示格式

格式	说明
bar	完整进度条模式，显示旋转动画 + 阶段标签 + 进度条 + 百分比 + 模块名
spinner	旋转动画模式，显示旋转动画 + 阶段标签 + 百分比
minimal	精简模式，仅显示阶段标签 + 百分比

颜色主题

自定义进度条各部分的颜色渲染函数。

interface ProgressTheme {
	completeColor: (text: string) => string // 已完成部分颜色
	incompleteColor: (text: string) => string // 未完成部分颜色
	percentageColor: (text: string) => string // 百分比数字颜色
	phaseColor: (text: string) => string // 阶段标签颜色
	moduleColor: (text: string) => string // 模块名称颜色
}

每个属性是一个接受纯文本字符串并返回带 ANSI 转义码着色字符串的函数。未提供的属性将使用默认主题。

构建阶段

插件根据以下阶段计算总体进度：

阶段	进度范围	说明
config	5%	读取配置阶段
resolve	10%	解析模块依赖阶段
transform	15%-85%	转换模块阶段
bundle	+10%	打包阶段（仅生产）
write	+5%	写入文件阶段
done	100%	构建完成

示例

精简格式

buildProgress({
	format: 'minimal'
})
// 输出: 转换模块 45%

自定义进度条外观

buildProgress({
	width: 40,
	completeChar: '■',
	incompleteChar: '□',
	clearOnComplete: false
})
// 输出: ⠋ 转换模块 ■■■■■■■■■□□□□□□□□□□□□□□□□□□□□□□ 45%

自定义颜色主题

buildProgress({
	theme: {
		completeColor: t => `\x1b[32m${t}\x1b[39m`, // 绿色
		incompleteColor: t => `\x1b[90m${t}\x1b[39m`, // 灰色
		percentageColor: t => `\x1b[1m${t}\x1b[22m`, // 粗体
		phaseColor: t => `\x1b[36m${t}\x1b[39m`, // 青色
		moduleColor: t => `\x1b[90m${t}\x1b[39m` // 灰色
	}
})

禁用模块名显示

buildProgress({
	showModuleName: false
})

注意事项

• 在非 TTY 终端环境下（如 CI/CD 流水线），自动降级为日志输出模式
• Windows 终端使用 ASCII 字符动画，其他平台使用 Unicode Braille 字符动画
• 插件通过 enabled 选项完全控制启用/禁用，禁用时零性能开销
• 开发模式下在服务器就绪后自动完成进度显示，生产模式下在 closeBundle 时完成