@meng-xi/vite-plugin v0.1.3：从构建盲区到全链路可见

版本：0.1.3 | 协议：MIT | 依赖：Vite ^5.0.0 || ^6.0.0 || ^7.0.0

写在前面

v0.1.3 的主题只有一个：让构建产物从"黑盒"变成"仪表盘"。

在此之前，你的 Vite 项目构建完成后，dist/ 目录里发生了什么——哪个 chunk 臃肿、哪个依赖膨胀、gzip 后实际传输多少——你一无所知。v0.1.3 带来的 bundleAnalyzer
插件，加上两个新工具模块和工具层增强，让你对构建产物拥有完全的量化能力。

如果你是老用户，升级只需一行；如果你是新读者，这篇文章会带你走完一个完整场景：从发现问题、量化问题、解决问题到自动化防控。

一、升级：一行改动，零风险

1.1 Breaking Changes

无。v0.1.3 完全向后兼容 v0.1.2。

1.2 升级方式

{
"devDependencies": {
"@meng-xi/vite-plugin": "^0.1.3"
}
}

1.3 新增能力速览

二、场景：一个真实项目的构建优化之旅

想象你是某个中型 Vite 项目的前端负责人。项目有 30+ 页面、50+ 依赖，构建后 dist/ 目录 5MB+。你隐约知道产物偏大，但缺乏数据支撑。以下是你从"盲区"到"全链路可见"的完整过程。

第一步：看见问题 — bundleAnalyzer 基础用法

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

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

零配置启动。构建完成后，你立刻得到：

✅ [@meng-xi/vite-plugin:bundle-analyzer] 产物分析完成: 12 个 chunk, 总体积: 1.19MB (gzip: 384.21KB), 分析耗时: 156ms
入口: 2 | 代码块: 7 | 资源: 3
体积 Top 5 模块:
1. 234.57KB (node_modules) node_modules/lodash/lodash.js
2. 156.23KB (source) src/components/Dashboard.vue
3. 89.45KB (node_modules) node_modules/axios/index.js
4. 67.89KB (source) src/utils/api.ts
5. 45.12KB (source) src/views/Home.vue

关键发现：lodash 占了 234KB，而你可能只用了其中 3 个函数。

第二步：深入分析 — HTML 可视化报告

bundleAnalyzer({
outputFormat: 'both',
defaultChartType: 'treemap',
openAnalyzer: true
})

构建完成后自动打开浏览器，你看到三种视图：

第三步：设定防线 — 阈值告警

bundleAnalyzer({
sizeThreshold: 100
})

构建后自动检查：超过 100KB 的 chunk 🟡 普通告警，超过 200KB 的 🔴 严重告警。

⚠️ [@meng-xi/vite-plugin:bundle-analyzer] 发现 3 个体积告警:
🟡 chunk "vendor" 超过阈值: 156.3KB > 100KB
🔴 chunk "app" 严重超过阈值: 312.5KB > 100KB (2x)
🟡 chunk "utils" 超过阈值: 128.7KB > 100KB

从"感觉大"到"知道大多少"，这是量化的第一步。

第四步：追踪变化 — 构建对比

你把 lodash 换成了 lodash-es，想确认体积是否真的减小了：

bundleAnalyzer({
compareWith: 'bundle-analysis-prev.json'
})

插件自动加载上次报告，逐模块对比：

ℹ️ [@meng-xi/vite-plugin:bundle-analyzer] 构建对比: 3 个增大, 2 个减小, 1 个新增, 0 个移除

从"改了"到"改了多少"，这是量化的第二步。

第五步：压缩传输 — bundleAnalyzer + compressAssets 联合

bundleAnalyzer 帮你发现体积问题，compressAssets 帮你解决传输问题。两者天然互补：

import { defineConfig } from 'vite'
import { bundleAnalyzer, compressAssets, buildProgress, generateVersion } from '@meng-xi/vite-plugin'

export default defineConfig({
plugins: [
buildProgress({ format: 'bar' }),
generateVersion({ format: 'datetime', outputType: 'both' }),

bundleAnalyzer({
outputFormat: 'both',
sizeThreshold: 200,
topModules: 30,
gzipSize: true,
compareWith: 'bundle-analysis-prev.json',
defaultChartType: 'treemap'
}),

compressAssets({
algorithm: 'both',
threshold: 1024,
reportOutput: 'compress-report.json',
parallelLimit: 10
})
]
})

第六步：自动化防控 — CI/CD 集成

将体积检测写入 CI 流水线，每次 PR 自动检查：

// vite.config.ts — CI 环境
bundleAnalyzer({
outputFormat: 'json',
sizeThreshold: 100,
gzipSize: true,
compareWith: 'bundle-analysis-prev.json'
})

# CI 脚本
npm run build

node -e "
const report = require('./dist/bundle-analysis.json');
if (report.warnings.length > 0) {
console.error('体积告警:', report.warnings.map(w => w.message).join('; '));
process.exit(1);
}
"

从"事后发现"到"事前拦截"，这是量化的终极形态。

三、bundleAnalyzer 工作原理

理解插件做了什么，才能用好它。

Vite 构建完成 (writeBundle, order: 'post')
↓
扫描 dist/ 目录，收集文件信息
↓
分析每个 chunk 的模块组成
↓
计算原始大小 + gzip 压缩大小（level: 9）
↓
生成 Top N 大模块排行
↓
按扩展名统计文件类型分布
↓
检查体积阈值，生成告警
↓
可选：与上次构建报告对比
↓
生成 JSON 报告和/或 HTML 可视化报告
可选：自动打开浏览器
输出分析摘要日志

三种报告格式各有侧重：

四、十大插件：从 0.0.6 到 0.1.3 的完整拼图

v0.1.3 补齐了构建产物分析这块拼图。十个插件，覆盖前端工程化的完整链路：

五、通用工具层：从重复实现到单一来源

5.1 问题：v0.1.2 的隐性债务

compressAssets 和 bundleAnalyzer 都需要 gzip 计算、目录扫描、文件大小格式化、扩展名提取、JSON 报告写入——各自实现了一遍。这不是代码量的问题，而是一致性风险：同一逻辑两份实现，修一个忘修另一个。

5.2 解法：v0.1.3 的工具层提取

v0.1.2 v0.1.3
┌──────────────────────────┐ ┌──────────────────────────────────┐
│ 9 个内置插件 │ │ 10 个内置插件 │
│ + bundleAnalyzer（新增） │ ──→ │ + bundleAnalyzer │
│ 各自实现压缩/扫描/格式化 │ │ 复用 @common 工具层 │
├──────────────────────────┤ ├──────────────────────────────────┤
│ 框架层 │ │ 框架层 │
│ BasePlugin · Validator │ │ BasePlugin · Validator · Logger │
├──────────────────────────┤ ├──────────────────────────────────┤
│ 工具层（6 个模块） │ │ 工具层（8 个模块） │
│ fs · format · html │ │ + compress（新增） │
│ object · script │ │ + path（新增） │
│ validation │ │ fs · format · html · object │
│ │ │ script · validation │
└──────────────────────────┘ └──────────────────────────────────┘

5.3 新增模块详解

@common/compress — 压缩算法

import { calculateGzipSize } from '@meng-xi/vite-plugin/common/compress'

const buffer = Buffer.from('some content to compress')
const gzipSize = await calculateGzipSize(buffer)

const stringData = 'another long string…'
const size = await calculateGzipSize(stringData)

为什么用 level: 9？ 分析场景追求的是估算网络传输的最小体积，而非压缩速度。用最高压缩级别，得到的是最保守（最小）的传输体积估算。

@common/path — 路径处理

import { isNodeModule } from '@meng-xi/vite-plugin/common/path'

isNodeModule('node_modules/lodash/index.js') // true
isNodeModule('src/utils/helper.ts') // false
isNodeModule('\\0some-virtual-module') // true — Rollup 内部虚拟模块
isNodeModule('virtual:import-meta-env') // true — 虚拟模块前缀

检测规则：

5.4 增强模块详解

@common/format — 新增三个函数

import { escapeHtmlAttr, formatFileSize, getExtension } from '@meng-xi/vite-plugin/common/format'

escapeHtmlAttr('hello "world"') // 'hello "world"'
escapeHtmlAttr('<script>') // '&lt;script&gt;'

formatFileSize(512) // '512B'
formatFileSize(1536) // '1.5KB'
formatFileSize(2461726) // '2.35MB'

getExtension('dist/app.js') // '.js'
getExtension('dist/style.CSS') // '.css'

formatFileSize 转换规则：

@common/fs — 新增两个函数和两个类型

import { scanDirectory, writeJsonReport } from '@meng-xi/vite-plugin/common/fs'
import type { ScannedFile, ScanDirectoryOptions } from '@meng-xi/vite-plugin/common/fs'

const jsFiles = await scanDirectory('dist', { includeExtensions: ['.js'] })

const allFiles = await scanDirectory('dist', {
excludePatterns: ['node_modules', '.map'],
filter: (filePath, ext, size) => size > 1024
})

await writeJsonReport('dist/report.json', { timestamp: Date.now(), stats: [] })
await writeJsonReport('dist/report.json', data, 4)

scanDirectory 过滤优先级：

1. excludePatterns — 排除的路径模式（支持通配符前缀和子串匹配）
2. includeExtensions — 包含的扩展名（列表非空时生效）
3. filter — 自定义过滤函数（最终过滤）

5.5 工具层完整矩阵

六、自定义插件：站在工具层的肩膀上

v0.1.3 的工具层不仅服务内置插件。你写自定义插件时，直接导入即可，不用重新实现目录扫描、gzip 计算、文件大小格式化这些通用逻辑。

示例：自定义产物统计插件

import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin/factory'
import { scanDirectory, writeJsonReport } from '@meng-xi/vite-plugin/common/fs'
import { calculateGzipSize } from '@meng-xi/vite-plugin/common/compress'
import { formatFileSize, getExtension } from '@meng-xi/vite-plugin/common/format'
import { isNodeModule } from '@meng-xi/vite-plugin/common/path'
import type { Plugin } from 'vite'

interface AssetStatsOptions {
outputFile?: string
excludePatterns?: string[]
}

class AssetStatsPlugin extends BasePlugin<AssetStatsOptions> {
protected getPluginName() {
return 'asset-stats'
}

protected getDefaultOptions() {
return { outputFile: 'asset-stats.json', excludePatterns: [] }
}

protected addPluginHooks(plugin: Plugin): void {
plugin.writeBundle = {
order: 'post',
handler: async () => {
const outDir = this.viteConfig?.build.outDir
if (!outDir) return

const files = await scanDirectory(outDir, {
excludePatterns: this.options.excludePatterns
})

const stats = []
for (const file of files) {
const gzipSize = await calculateGzipSize(file.filePath)
stats.push({
path: file.filePath,
extension: getExtension(file.filePath),
size: formatFileSize(file.size),
gzipSize: formatFileSize(gzipSize),
isNodeModule: isNodeModule(file.filePath)
})
}

await writeJsonReport(this.options.outputFile!, { stats })
this.logger.success(`产物统计完成: ${files.length} 个文件`)
}
}
}
}

export const assetStats = createPluginFactory(AssetStatsPlugin)

你自动获得的能力：

七、实战配置：三种场景，三份配置

7.1 生产环境：分析 + 压缩 + 进度

import { defineConfig } from 'vite'
import { bundleAnalyzer, compressAssets, buildProgress, generateVersion } from '@meng-xi/vite-plugin'

export default defineConfig({
plugins: [
buildProgress({ format: 'bar' }),
generateVersion({ format: 'datetime', outputType: 'both' }),

bundleAnalyzer({
outputFormat: 'both',
outputFile: 'bundle-analysis',
sizeThreshold: 200,
topModules: 30,
gzipSize: true,
compareWith: 'bundle-analysis-prev.json',
defaultChartType: 'treemap'
}),

compressAssets({
algorithm: 'both',
threshold: 1024,
reportOutput: 'compress-report.json',
parallelLimit: 10
})
]
})

7.2 CI/CD：体积回归检测

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

export default defineConfig({
plugins: [
bundleAnalyzer({
outputFormat: 'json',
sizeThreshold: 100,
gzipSize: true,
compareWith: 'bundle-analysis-prev.json'
})
]
})

CI 脚本：

npm run build

node -e "
const report = require('./dist/bundle-analysis.json');
if (report.warnings.length > 0) {
console.error('体积告警:', report.warnings.map(w => w.message).join('; '));
process.exit(1);
}
"

7.3 uni-app：条件启用

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { bundleAnalyzer, compressAssets } from './uni_modules/vite-plugin/js_sdk/index.mjs'

export default defineConfig({
plugins: [
uni(),

bundleAnalyzer({
outputFormat: 'json',
sizeThreshold: 100,
gzipSize: true,
enabled: process.env.UNI_PLATFORM === 'h5' && process.env.VITE_USER_NODE_ENV === 'production'
}),

compressAssets({
algorithm: 'both',
threshold: 1024,
reportOutput: 'compress-report.json',
enabled: process.env.UNI_PLATFORM === 'h5' && process.env.VITE_USER_NODE_ENV === 'production'
})
]
})

八、通用工具模块速查

8.1 导入方式

// 全量导入
import { calculateGzipSize, isNodeModule, formatFileSize, scanDirectory } from '@meng-xi/vite-plugin/common'

// 按模块导入
import { calculateGzipSize } from '@meng-xi/vite-plugin/common/compress'
import { isNodeModule } from '@meng-xi/vite-plugin/common/path'
import { escapeHtmlAttr, formatFileSize, getExtension } from '@meng-xi/vite-plugin/common/format'
import { scanDirectory, writeJsonReport } from '@meng-xi/vite-plugin/common/fs'

8.2 完整子路径导出映射

九、详细 API 文档

9.1 通用配置（BasePluginOptions）

所有插件均继承自 BasePluginOptions，拥有以下通用配置：

9.2 bundleAnalyzer — 构建产物体积分析

在 Vite 构建（writeBundle）完成后自动扫描输出目录，分析构建产物的体积分布。

导出类型：BundleAnalyzerOptions、BundleAnalysisResult、BundleOutputFormat、ChunkStats、ModuleStats、FileTypeDistribution、SizeWarning、ComparisonDiff

BundleAnalysisResult：

ChunkStats：

ModuleStats：

FileTypeDistribution：

SizeWarning：

ComparisonDiff：

9.3 compressAssets — 构建产物压缩

导出类型：CompressAssetsOptions、CompressAlgorithm、CompressStats、CompressSummary

9.4 buildProgress — 构建进度条

导出类型：BuildProgressOptions、ProgressFormat、BuildPhase、ProgressTheme

9.5 copyFile — 文件复制

导出类型：CopyFileOptions

9.6 faviconManager — 图标管理

导出类型：FaviconManagerOptions

9.7 generateRouter — 路由配置生成

导出类型：GenerateRouterOptions、RouteConfig、RouteMeta、UniAppPagesJson、UniAppPageConfig、UniAppTabBarConfig、OutputFormat、NameStrategy

9.8 generateVersion — 版本号生成

导出类型：GenerateVersionOptions

9.9 htmlInject — HTML 内容注入

导出类型：HtmlInjectOptions、HtmlInjectRule、InjectPosition、InjectCondition、SecurityConfig、SelectorMatch

9.10 loadingManager — Loading 状态管理

导出类型：LoadingManagerOptions

9.11 versionUpdateChecker — 版本更新检测

导出类型：VersionUpdateCheckerOptions

十、路线图

短期

• bundleAnalyzer 支持 Webpack 兼容模式
• 构建产物趋势图（多版本体积变化折线图）
• 插件配置预设（web-app、uni-app、ssr）

中期

• 插件间事件总线
• 可视化配置生成器
• 社区插件市场

长期

成为 Vite 插件开发的标准框架——定义最佳实践，让社区以统一方式构建、分享和组合插件。

本文基于 @meng-xi/vite-plugin@0.1.3 版本撰写，所有代码示例均来自实际源码。