shilimingY/vite-plugin-resource-waste

README

vite-plugin-resource-waste

基于 Vite/Rollup Module Graph 的前端资源浪费分析插件

为什么需要它？

很多团队只关注「包体积多少 KB」，却忽略了更隐蔽的浪费：

import _ from 'lodash' 只用了 debounce，tree-shake 失效，整包进 bundle；
活动页下线了，组件文件还在 src/pages/legacy/ 里；
字体/图片产物没有 content hash，回访用户每次重复下载；
同一依赖两个版本，重复打包 + 缓存失效；

vite-plugin-resource-waste 在 vite build 时自动分析这些问题，把「浪费」量化为 传输体积（KB）+ 解析耗时（ms），并给出可执行的修复建议。

本插件分析的是 构建冗余、导入模式、未使用 import、不可达代码、缓存策略、重复依赖 等多维浪费。

特点与优势

对比维度	传统 Bundle 分析器	vite-plugin-resource-waste
分析视角	产物有多大	浪费了多少、为什么浪费
问题类型	体积分布图	低效 import、不可达页面、cache 风险、重复依赖
输出形式	Treemap 可视化	JSON + HTML 报告 + 终端摘要 + 修复建议
工程集成	人工解读	CI 构建阈值拦截（`failOnThreshold`）
分析深度	产物层	源码 + Module Graph + 构建产物交叉分析

核心优势

多维浪费模型：不只看 JS 体积，还覆盖缓存失效、重复依赖等非 bundle 浪费；
零业务侵入：作为 Vite 插件接入，无需修改业务代码；
可执行建议：每条 issue 附带 severity、开销估算、修复 suggestion；
Dev + Build 双模式：开发时轻量预警，构建时完整报告；
TypeScript 友好：完整类型导出，配置项有 IDE 提示；

功能一览

检测能力

类别	检测内容	典型场景
import-pattern	lodash/moment/antd 全量导入、barrel 文件	tree-shake 失效，体积虚高
dead-import	已 import 但未使用的本地模块（含页面/组件）	路由注释了但 import 未删、组件引入未使用
unreachable-component	不在 module graph 中的页面/组件	遗留代码、已下线活动页
static-unused-js	过多 export、独立 async chunk 风险	工具库 export 膨胀、误 prefetch
cache-miss	产物文件名缺少 content hash	字体/图片回访重复下载
duplicate-dependency	同一 npm 包多版本共存	重复打包、缓存 key 失效

报告输出

构建完成后，在 dist/resource-waste/（可配置）生成：

文件	说明
`report.json`	机器可读，供 CI 脚本、自动化工具或内部平台读取
`report.html`	可视化报告，可直接浏览器打开

终端同时输出摘要与 Top 5 问题。

安装

npm install vite-plugin-resource-waste -D
# pnpm add vite-plugin-resource-waste -D
# yarn add vite-plugin-resource-waste -D

快速开始

// vite.config.ts
import { defineConfig } from 'vite'
import { resourceWaste } from 'vite-plugin-resource-waste'

export default defineConfig({
  plugins: [
    resourceWaste(),
  ],
})

执行构建：

npm run build

查看报告：

dist/resource-waste/report.html   # 可视化报告
dist/resource-waste/report.json     # JSON 数据

使用示例

基础用法（推荐默认值）

import { defineConfig } from 'vite'
import { resourceWaste } from 'vite-plugin-resource-waste'

export default defineConfig({
  plugins: [
    resourceWaste({
      htmlReport: true,       // 生成 HTML 报告
      wasteThresholdKb: 300,  // 浪费超过 300KB 时在终端提示
    }),
  ],
})

CI 构建阈值拦截：浪费超标则构建失败

当项目在 GitHub Actions、GitLab CI 等平台自动构建时，可配置浪费超标直接失败，阻止合并不达标的代码：

resourceWaste({
  wasteThresholdKb: 200,
  failOnThreshold: true,  // 超过阈值则构建失败，CI 流水线中断
  silent: false,
})

按需开启/关闭检测项

resourceWaste({
  scanImportPatterns: true,   // 扫描 lodash 全量导入等
  scanUnusedImports: true,    // 扫描未使用的本地静态 import
  scanUnreachable: true,      // 扫描不可达页面/组件
  scanCacheStrategy: true,    // 扫描产物 cache 策略
  scanDuplicateDeps: true,    // 扫描重复依赖版本
})

Monorepo / 自定义扫描范围

resourceWaste({
  root: 'packages/app/src',
  include: ['**/*.tsx'],
  exclude: [
    '**/*.spec.*',
    '**/__tests__/**',
    '**/stories/**',
  ],
  reportDir: 'resource-waste', // 相对 outDir
})

静默模式（仅写报告，不输出终端日志）

resourceWaste({
  silent: true,
  htmlReport: true,
})

配置项

选项	类型	默认值	说明
`root`	`string`	`'src'`	源码根目录
`reportDir`	`string`	`'resource-waste'`	报告输出目录（相对 `outDir`）
`wasteThresholdKb`	`number`	`300`	预估浪费阈值（KB），用于终端提示与 CI 拦截
`failOnThreshold`	`boolean`	`false`	超过阈值是否中断构建
`htmlReport`	`boolean`	`true`	是否生成 HTML 可视化报告
`scanImportPatterns`	`boolean`	`true`	是否扫描低效 import 模式
`scanUnusedImports`	`boolean`	`true`	是否扫描未使用的本地静态 import
`scanUnreachable`	`boolean`	`true`	是否扫描不可达源文件/组件
`scanCacheStrategy`	`boolean`	`true`	是否分析产物缓存策略
`scanDuplicateDeps`	`boolean`	`true`	是否检测重复依赖版本
`include`	`string[]`	`[]`	额外 glob 包含模式
`exclude`	`string[]`	测试文件等	排除扫描的路径
`silent`	`boolean`	`false`	静默模式，不输出终端摘要

报告示例

终端输出

[vite-plugin-resource-waste] Resource waste analysis complete

  Issues       : 6
  Waste (est.) : 142.5 KB transfer / 64.1 ms parse
  Threshold    : 300 KB

  Top issues:
    [HIGH] 全量/低效导入: lodash (src/main.ts)
    [HIGH] 产物文件名缺少 content hash (assets/fonts/main.woff2)
    [MEDIUM] 不可达源文件 (src/pages/legacy/Double11.ts)
    [MEDIUM] Barrel 文件可能导致 tree-shake 失效 (src/pages/index.ts)

JSON 报告结构（节选）

report.json 可被 CI 脚本读取，例如在 PR 评论中自动贴出浪费摘要，或接入内部质量看板：

{
  "summary": {
    "totalIssues": 6,
    "totalWasteTransferKb": 142.5,
    "totalParseMsEstimate": 64.1,
    "bySeverity": { "high": 2, "medium": 3, "low": 1 }
  },
  "issues": [
    {
      "category": "import-pattern",
      "severity": "high",
      "title": "全量/低效导入: lodash",
      "file": "src/main.ts",
      "suggestion": "改为 import debounce from 'lodash-es/debounce' 或按需导入",
      "cost": {
        "transferKb": 24,
        "parseMsEstimate": 10.8
      }
    }
  ]
}

开发模式

vite dev 启动后，插件会做轻量静态分析（无 bundle 数据），发现问题时在终端提示：

[vite-plugin-resource-waste] Dev mode: found 3 potential resource waste issue(s).
Run "vite build" for full report.

Dev 报告写入：node_modules/.cache/resource-waste/dev-report.json

工作原理（简述）

vite build
  ├── buildStart      → glob 扫描 src 源文件
  ├── moduleParsed    → 构建 Module Graph（import 依赖关系）
  ├── generateBundle  → 收集 Rollup 产物（chunk + asset）
  └── closeBundle     → 运行分析器 → 生成报告

分析器并行执行：

import-pattern-analyzer — 正则 + 启发式检测低效导入
unreachable-analyzer — 对比源文件与 module graph 可达集
cache-analyzer — 检查产物文件名是否含 content hash
duplicate-deps-analyzer — 统计 bundle 中 npm 包版本
unused-export 启发式 — export 过多且引用者极少

常见问题

Q: 和 rollup-plugin-visualizer 有什么区别？

visualizer 回答「bundle 长什么样」；本插件回答「哪些资源白花了、浪费多少、怎么修」。

Q: 报告里的 KB/ms 是精确值吗？

传输体积对已知模式（如 lodash 全量导入）有参考估算；解析耗时基于经验公式（~0.45ms/KB）。建议作为优先级排序依据，而非绝对性能指标。

Q: 生产环境会有性能影响吗？

不会。所有分析在构建期完成，不注入任何运行时代码到产物中。

如果这个插件对你有帮助，欢迎给个 ⭐ Star 哦~

GitHub • Issues