构建工具Plugin：构建与打包增强

一、构建工具Plugin的设计

构建工具Plugin是面向项目构建流程的智能化增强插件，其核心目标是优化构建配置、提升构建效率，并提供可视化的构建产物分析能力。与传统的构建配置文件不同，构建工具Plugin以插件化的方式深度集成到Webpack、Vite、esbuild、Gulp等主流构建工具中，在不侵入项目原有构建逻辑的前提下，提供诊断、优化和监控能力。

核心理念：构建工具Plugin不是替代现有构建工具，而是在现有构建流程之上提供"元能力"——即对构建本身进行检测、分析和优化的能力。

设计一个构建工具Plugin需要遵循以下几个关键原则：

非侵入性：插件不应修改项目核心构建逻辑，而应在现有流程的外围提供增强功能。钩子（Hook）机制是实现非侵入性的关键，通过监听构建工具的生命周期事件来获取信息和执行操作。
跨平台兼容：理想的构建工具Plugin应能够适配多种构建工具。通过抽象出一层统一的构建工具接口（BuildToolAdapter），底层对接不同构建工具的API，上层暴露统一的检测和操作能力。
可观测性：内置完善的埋点和上报机制，能够收集构建耗时、资源占用、产出物质量等指标数据，为性能优化提供量化依据。
渐进式增强：用户可按需启用功能模块，避免一次性引入过多性能开销。插件采用模块化架构，核心模块仅提供基础能力，高级功能通过扩展模块按需加载。

1.1 插件架构设计

构建工具Plugin的典型架构分为三层：

适配层（Adapter Layer）：负责与具体构建工具交互。每个构建工具都有专属的适配器，负责将构建工具的原生事件转换为统一的事件模型。例如Webpack的compiler.hooks.emit会映射为统一的BUILD_COMPLETE事件。
分析层（Analysis Layer）：核心业务逻辑所在，包括构建性能分析、产物分析、配置优化建议等。该层不依赖特定构建工具，通过适配层提供的数据进行计算和诊断。
展示层（Presentation Layer）：负责分析结果的可视化输出。可以是终端日志、HTML报告、JSON数据文件，或者集成到CI/CD系统的通知消息中。

// 统一的构建工具Plugin适配器接口示例
interface BuildToolAdapter {
  onBuildStart(callback: (context: BuildContext) => void): void;
  onBuildComplete(callback: (result: BuildResult) => void): void;
  onModuleResolve(callback: (module: ModuleInfo) => void): void;
  onEmit(callback: (assets: AssetMap) => void): void;
  getConfig(): ProjectConfig;
  getStats(): BuildStats;
}

1.2 与主流构建工具的对比

特性	Webpack Plugin	Vite Plugin	esbuild Plugin	Gulp Plugin
钩子系统	compiler/compilation 多层次hooks	Rollup插件模型 + Vite特有钩子	onResolve/onLoad 简洁模型	Node.js Stream 管道模型
性能开销	中等（JS运行时）	低（Go核心 + JS插件）	极低（Go原生）	低（基于Stream）
HMR支持	通过devServer内置	原生HMR（ESM热更新）	有限支持	需额外工具 (browser-sync)
插件生态	最丰富	快速增长	较精简	成熟稳定
适用场景	大型项目、复杂配置	现代前端、SSR框架	构建速度敏感、库开发	自动化工作流、静态资源处理

二、构建工具检测和配置优化

构建工具Plugin的首要任务是自动检测项目的构建工具栈，并基于最佳实践给出配置优化建议。这解决了开发者在项目初始化或技术栈迁移时面临的"不知道用哪个构建工具"以及"不知道该怎样配置"的痛点。

2.1 自动检测项目使用的构建工具

自动检测机制通过分析项目根目录下的配置文件来推断构建工具类型。检测优先级和判断逻辑如下：

检查 package.json：分析devDependencies和scripts字段。如果包含"webpack"依赖和"build"脚本，则判断为Webpack项目；包含"vite"则为Vite项目；包含"esbuild"则为esbuild项目；包含"gulp"则为Gulp项目。
检查配置文件存在性：检测webpack.config.js、vite.config.ts、esbuild.config.js、gulpfile.js等标准配置文件。
检查锁定文件：yarn.lock、pnpm-lock.yaml、package-lock.json中包含的构建工具依赖版本信息。
混合栈检测：某些项目可能同时使用多种工具（如Vite + esbuild），检测系统应能识别主构建工具和辅助工具。

// 构建工具自动检测核心逻辑
async function detectBuildTools(projectRoot: string): Promise<BuildToolInfo[]> {
  const pkg = await readJson(join(projectRoot, 'package.json'));
  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
  const detected: BuildToolInfo[] = [];

  if (deps.webpack) detected.push({
    name: 'webpack',
    version: deps.webpack,
    configFiles: ['webpack.config.js', 'webpack.config.ts'],
    confidence: deps.webpack ? 0.95 : 0.6
  });

  if (deps.vite) detected.push({
    name: 'vite',
    version: deps.vite,
    configFiles: ['vite.config.ts', 'vite.config.js'],
    confidence: 0.95
  });

  if (deps.esbuild) detected.push({ ... });

  return detected;
}

2.2 分析当前配置并给出优化建议

检测到构建工具后，Plugin会进一步分析项目当前的构建配置，从以下几个方面给出优化建议：

Loader/Babel配置优化：检查是否包含了不必要的loader规则、是否正确配置了exclude/include、是否需要开启thread-loader或esbuild-loader加速。例如，在Webpack中，当项目使用babel-loader处理node_modules时，会提示排除该目录以提升构建速度。
代码分割策略：分析是否开启了splitChunks，以及分割策略是否合理。对于单页应用，建议将node_modules中的大型依赖拆分为独立chunk；对于多入口项目，建议提取公共依赖。
Source Map配置：根据构建环境推荐不同的source-map策略。开发环境推荐eval-source-map以兼顾质量和速度；生产环境推荐source-map或hidden-source-map；不建议在开发环境使用nosources-source-map。
缓存配置：检查是否开启了持久化缓存（Webpack 5的cache配置、Vite的cacheDir），以及缓存策略是否合理。如果项目未配置缓存，会提示开启并给出配置示例。
多进程/多线程：检查CPU核心利用率，对于多核机器上的大型项目，推荐使用thread-loader（Webpack）或esbuild（Vite）开启并行构建。

最佳实践：在Webpack 5中，开启持久化缓存可以将二次构建速度提升5-10倍。配置方式为在webpack.config.js中添加 cache: { type: 'filesystem' }。Vite用户则无需额外配置，开发服务器启动即自带ESM缓存机制。

2.3 建议插件和Loader的最佳组合

基于项目类型和检测到的依赖，Plugin可以推荐最佳的工具组合方案：

项目类型	推荐构建工具	推荐插件/Loader组合
React SPA	Vite	@vitejs/plugin-react + @rollup/plugin-image + vite-plugin-svgr
Vue SPA	Vite	@vitejs/plugin-vue + unplugin-vue-components + unplugin-auto-import
大型Angular	Webpack (Angular CLI)	@angular-builders/custom-webpack + thread-loader + terser-webpack-plugin
Node.js库	esbuild	esbuild-plugin-paths + esbuild-plugin-external + esbuild-plugin-postcss
静态资源管线	Gulp	gulp-sass + gulp-autoprefixer + gulp-imagemin + gulp-babel

2.4 构建配置模板快速生成

当检测到项目缺少构建配置或需要迁移时，Plugin可以基于项目特征快速生成构建配置模板。生成逻辑包含以下步骤：

读取项目的package.json，分析项目依赖和入口文件。
识别项目框架（React、Vue、Angular、Svelte等）和使用的CSS预处理器。
根据项目规模和团队习惯，选择合理的代码分割和优化策略。
生成带有详细注释的配置文件，并标注可根据实际情况调整的参数。
支持交互式配置向导，让用户通过问答方式定制配置细节。

// 生成的Vite配置模板示例
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    react(),
    visualizer({ open: true, gzipSize: true })
  ],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          utils: ['lodash-es', 'dayjs']
        }
      }
    },
    target: 'es2020',
    minify: 'terser',
    cssCodeSplit: true,
    sourcemap: false
  },
  server: {
    hmr: { overlay: true }
  }
});

三、构建性能分析

构建性能分析是构建工具Plugin的核心价值之一。通过深入检测构建过程各阶段的时间消耗，帮助开发者找到性能瓶颈，从而有针对性地进行优化。这对于大型项目尤为重要——随着项目规模的增长，构建时间可能从几秒膨胀到几分钟甚至十几分钟。

3.1 构建耗时分布可视化

Plugin通过Hooking构建工具的生命周期事件，精确记录每个阶段的耗时，并按类别进行聚合分析：

Loader阶段耗时：记录每个Loader对每个模块的处理时间，按总耗时降序排列。对于显著慢的Loader（如babel-loader处理大型文件），会给出优化建议（如配置exclude、改用swc-loader等）。
Plugin阶段耗时：追踪每个Plugin Hook的执行时间。某些第三方Plugin可能因为实现低效导致构建变慢，通过耗时分布可以快速定位问题插件。
Resolve阶段耗时：分析模块解析过程中的文件查找时间。对于解析深度过大或symlink较多的项目，建议配置resolve.alias来缩短解析路径。
代码生成和压缩阶段：记录代码生成（Generate）和代码压缩（Minify）的时间消耗。这是大型项目中最容易成为瓶颈的阶段，建议使用esbuild作为压缩器替代terser。

分析数据显示：在典型的大型React项目中，babel-loader耗时占总构建时间的45-55%，模块解析（resolve）占15-20%，代码压缩占20-25%。切换到esbuild-loader和esbuild-minify后，总构建时间可减少60-70%。

// 构建耗时追踪的核心实现模式
class PerformanceAnalysisPlugin {
  apply(compiler) {
    const timings = new Map();

    compiler.hooks.compile.tap('PerformancePlugin', () => {
      timings.set('compile', Date.now());
    });

    compiler.hooks.afterCompile.tap('PerformancePlugin', () => {
      timings.set('afterCompile', Date.now());
    });

    compiler.hooks.done.tap('PerformancePlugin', (stats) => {
      const duration = stats.endTime - stats.startTime;
      const breakdown = this.calculatePhaseBreakdown(timings);
      this.report({ duration, breakdown });
    });
  }
}

3.2 HMR热更新时间监控

热模块替换（HMR）是现代前端构建工具的核心开发体验特性。HMR性能直接影响开发效率，构建工具Plugin通过以下方式进行监控和分析：

HMR更新耗时追踪：记录每次HMR更新的完整链路耗时，包括文件变更检测、模块编译、模块图更新、客户端热更新应用等各阶段的耗时。当HMR耗时超过300ms时，会给出预警提示。
HMR失败率统计：统计HMR更新失败的事件次数和原因分类。常见的HMR失败原因包括：CSS更新导致的页面刷新、未正确处理模块边界、WebSocket连接中断等。
模块更新链分析：当修改一个文件时，分析受影响的模块链长度。如果某个文件的修改导致大量模块连锁更新（如修改了全局样式文件或公共工具函数），建议进行模块拆分。
HMR性能优化建议：基于分析结果给出具体优化方案。例如：在Vite中建议开启optimizeDeps预构建；在Webpack中建议配置devServer.hot.only减少不必要的页面刷新。

注意：当项目中单个文件超过500KB时，HMR更新耗时可能超过1000ms。建议将大文件拆分为多个小模块，或者使用lazy loading策略。对于不可拆分的大型第三方库（如Monaco Editor），建议使用exclude将其排除出HMR范围。

3.3 缓存策略分析和建议

构建缓存是提升二次构建速度最有效的手段。Plugin会检查项目的缓存配置情况，并根据项目特征给出优化建议：

Webpack持久化缓存：检查cache.type配置，建议设置为'filesystem'而非默认的'memory'。同时检查cache.buildDependencies是否正确配置，以确保缓存会在配置文件变更时自动失效。
Loader级别缓存：检查babel-loader、eslint-loader等是否开启了缓存（cacheDirectory选项）。建议为所有耗时的Loader开启缓存，并确保缓存目录被正确清理。
缓存命中率统计：通过比较模块的timestamps和hash值，计算缓存的命中率和有效缓存比例。如果缓存命中率低于60%，需要检查缓存失效策略是否过于激进。
CI环境缓存策略：针对CI/CD环境，建议配置GitHub Actions或Jenkins的构建缓存策略，包括node_modules缓存、yarn/npm/pnpm缓存、Webpack/Vite缓存目录的持久化。

3.4 慢模块定位和优化

通过细粒度的模块级耗时追踪，Plugin可以精确定位构建过程中的"慢模块"：

模块编译耗时排行榜：按编译耗时从高到低列出所有模块。重点关注前10%的慢模块，通常它们占了总编译时间的80%以上（符合二八定律）。
慢模块原因分析：分析慢模块的共因——可能是因为文件过大、依赖链过长、复杂的Babel转换、或者TypeScript类型检查开销大。
自动化优化方案：针对不同类型的慢模块提供优化方案。对于包含大量TypeScript类型的文件，建议启用isolatedModules或transpileOnly；对于大型JSON/YAML文件，建议使用JSON imports或转为按需加载。

实战案例：某电商项目构建耗时从120秒降至35秒。优化方案包括：(1) 将babel-loader替换为esbuild-loader；(2) Webpack cache改为filesystem类型；(3) 开启thread-loader并行构建；(4) 将大型语言包文件（moment.js locale）从打包中排除。

四、构建产物分析

构建产物分析帮助开发者理解最终生成的Bundle文件的构成，发现体积优化机会，并确保Tree Shaking生效。这对于控制首屏加载时间、减少带宽消耗至关重要。

4.1 Bundle构成可视化分析

Plugin通过解析构建统计数据（Webpack的stats.json、Vite的rollup-plugin-visualizer输出），生成可视化的Bundle构成分析：

模块依赖图：展示所有模块之间的依赖关系，可交互式展开和折叠。帮助开发者理解模块之间的耦合程度，发现不必要的依赖。
Chunk组成明细：列出每个Chunk包含的模块列表及其体积占比。便于检查各个Chunk的构成是否合理，是否存在某个Chunk过大或分布不均的情况。
CDN和动态加载模块：标记通过CDN引用的模块和动态import的模块，验证懒加载策略是否按预期工作。
增量构建对比：记录每次构建的产物信息，支持版本间的增量对比。当某个模块体积显著增加时，自动发出通知。

推荐工具：webpack-bundle-analyzer和rollup-plugin-visualizer是业界主流的Bundle分析工具。它们以交互式Treemap图展示各模块的体积占比，包体积异常变大时一目了然。建议将其集成到CI流程中，并在体积超出阈值时阻止构建通过。

4.2 各模块体积占比

模块级别的体积分析是精确控制Bundle体积的基础。Plugin提供以下维度的分析数据：

原始体积 vs 压缩体积 vs gzip体积：展示每个模块的三个体积指标，帮助开发者判断模块本身的优化空间。例如，如果某个模块压缩率很低（原始体积和gzip体积差距小），说明代码已经高度优化，进一步压榨空间有限。
第三方依赖体积：单独统计node_modules中第三方库的总体积和按库分组的明细。大型库如lodash（全量引入约500KB）、moment.js（约231KB）、chart.js（约200KB）等应作为重点优化对象。
业务代码体积：统计src目录下业务代码的总体积和按目录/组件的分布。用于感知新增功能对Bundle体积的影响。
CSS和静态资源体积：统计经过CSS处理器处理后的样式体积、图片和字体等静态资源的体积。检查是否有未使用的CSS规则和未压缩的大型图片。

// Bundle体积分析数据结构
interface BundleAnalysisReport {
  totalSize: number;         // 原始总体积（字节）
  minifiedSize: number;      // 压缩后体积
  gzipSize: number;          // gzip后体积
  chunks: ChunkInfo[];       // Chunk明细
  modules: ModuleInfo[];     // 模块明细
  duplicates: DuplicateDep[];// 重复依赖
  unusedExports: string[];   // 未使用的导出
  sizeBudget: BudgetResult;  // 预算检查结果
}

interface ModuleInfo {
  path: string;
  size: number;
  renderedSize: number;      // 实际打包后体积
  gzipSize: number;
  isExternal: boolean;
  belongsTo: string;         // 所属Chunk
}

4.3 重复依赖检测

重复依赖是导致Bundle体积膨胀的常见原因，通常由依赖版本不兼容引起。Plugin通过以下机制检测和报告重复依赖：

版本冲突检测：分析node_modules中各依赖的版本，找出同一包名的不同版本。例如，项目中可能同时存在react@18.2.0和react@17.0.2（通过嵌套依赖引入），导致Bundle中包含两份React代码。
相似依赖识别：检测功能相似的库被同时引入，如moment.js和dayjs、lodash和ramda。建议统一使用其中一个以减小体积。
自动修复建议：对于已知的重复依赖问题，提供具体的修复方案。包括使用npm/yarn/pnpm的overrides或resolutions字段强制版本统一、或使用Webpack的resolve.alias配置来重定向模块解析。
pnpm严格模式：如果项目使用的是npm或yarn，建议迁移到pnpm以从根本上解决幽灵依赖和依赖重复问题。pnpm的node_modules结构确保了依赖的唯一性和正确性。

常见陷阱：当使用npm < 7或yarn < 2时，嵌套依赖可能导致同一个包被安装多个版本。例如，@mui/material可能依赖@emotion/react@11.x，而项目本身又直接依赖了@emotion/react@10.x，最终Bundle中会包含两个版本的@emotion/react，体积增加约30KB。

4.4 Tree Shaking有效性检查

Tree Shaking是现代化构建工具移除未使用代码的核心机制。然而，某些情况下Tree Shaking可能无法生效，导致大量无用代码被打入Bundle。Plugin通过以下检查确保Tree Shaking正常工作：

Side Effects标记检查：检查所有npm包是否在package.json中正确设置了sideEffects字段。如果一个库没有正确标注sideEffects，Webpack/Rollup出于安全考虑不会对其进行Tree Shaking。对于明确没有副作用的库，建议添加"sideEffects": false标记。
未使用导出检测：分析源代码中所有导入语句，找出那些被导入但从未被使用的导出项。例如，import { Button, Card, Table, unusedComponent } from 'library'中的unusedComponent就是未使用导出。
EOM（Export Obfuscation Mechanism）检测：检查第三方库的导出方式是否为ES Module（静态导出）还是CommonJS（动态导出）。只有ES Module格式才能被Tree Shaking正确处理。对于使用CommonJS导出的库，建议寻找对应的ESM版本（如lodash → lodash-es）。
Barrel文件分析：检测是否存在过度使用Barrel文件（集中导出的index.ts）导致Tree Shaking失效的情况。Barrel文件虽然方便，但可能导致构建工具无法准确追踪模块边界，建议在大型项目中谨慎使用。

// Tree Shaking有效性检查规则示例
const treeShakingRules = {
  sideEffects: {
    severity: 'error',
    check: (pkg: PackageJson) => {
      return pkg.sideEffects === undefined
        ? { pass: false, message: '缺少 sideEffects 字段声明' }
        : { pass: true };
    }
  },
  moduleFormat: {
    severity: 'warning',
    check: (pkg: PackageJson) => {
      const hasESM = !!pkg.module || !!pkg.exports;
      return hasESM
        ? { pass: true }
        : { pass: false, message: '未提供ES Module格式，Tree Shaking受限' };
    }
  }
};

五、构建错误诊断

构建错误是开发过程中最具挫败感的体验之一。构建工具Plugin通过智能化的错误诊断系统，帮助开发者快速定位错误原因并给出修复方案，大幅减少排错时间。

5.1 自动分析构建错误消息

传统构建工具输出的错误信息通常冗长且难以理解，Plugin通过自然语言处理技术对错误消息进行解析和增强：

错误分类和分级：将构建错误分为语法错误、模块解析错误、类型错误、资源加载错误、Plugin/配置错误等类别，并标注严重等级（critical/error/warning）。分类后的错误信息更加清晰，开发者可以快速判断问题优先级。
错误消息简化：将构建工具输出的多行堆栈信息简化为易读的一两句话。例如，Webpack的"Module not found: Error: Can't resolve 'lodash-es/debounce'"会被简化为"模块lodash-es/debounce未找到，请检查是否已安装该依赖包"。
关联错误聚合：将同一根源引发的多个错误聚合并报告一次。例如，当Babel配置文件语法错误时，所有尝试编译的文件都会报错，Plugin会识别出真正的根因是Babel配置错误，而非文件本身的问题。
错误频率统计：记录项目的历史错误数据，统计常见错误类型和频率。帮助团队了解构建健康度的变化趋势，并针对高频错误制定预防措施。

5.2 定位错误文件和代码位置

精确定位错误源文件是高效修复错误的前提。Plugin从构建错误信息中提取关键的定位信息：

源文件映射：使用Source Map将压缩/转译后的代码位置映射回原始源代码的精确行号和列号。对于TypeScript项目，错误会被映射到.ts源文件而非编译后的.js文件。
错误上下文展示：在定位到源文件后，展示错误代码周围的上下文（前后各5行代码），并用高亮标记错误位置。开发者无需离开终端就能理解错误的代码上下文。
依赖溯源：当错误由第三方依赖引起时，追踪依赖的来源路径。例如，当通过多个中间依赖间接引入的某个深层依赖报错时，Plugin会展示完整的依赖链路。

// 错误增强信息输出格式
┌─────────────────────────────────────────┐
│ 🔴 构建错误 (critical)                   │
├─────────────────────────────────────────┤
│ 描述: 模块解析失败                       │
│ 文件: src/components/Header.tsx:42:8     │
│ 上下文:                                  │
│   40 │ import React from 'react'         │
│   41 │ import { useState } from 'react'  │
│   42 │ import ⚡Button⚡ from './Button'  │
│   43 │ // Button组件                      │
│   44 │ const Header = () => { ... }      │
├─────────────────────────────────────────┤
│ 原因: 模块 './Button' 不存在              │
│ 建议: 检查文件路径是否正确                 │
│        文件是否已移动到其他目录             │
│        文件名大小写是否匹配                │
└─────────────────────────────────────────┘

5.3 提供常见错误的解决方案

基于对大量构建错误模式的分析，Plugin内置了常见错误的知识库和解决方案：

错误类型	典型错误消息	修复建议
模块解析失败	Module not found: Can't resolve 'X'	检查X是否已安装（npm install X）、路径是否正确、大小写是否匹配
语法错误	Unexpected token (line:col)	检查对应位置语法、可能需要安装对应的语法解析器（如@babel/plugin-syntax-xxx）
CSS解析错误	You may need an appropriate loader	检查CSS/Sass/PostCSS等对应的loader是否配置（如css-loader、sass-loader）
类型错误	Type 'X' is not assignable to type 'Y'	检查tsconfig.json的strict模式配置、检查第三方库的类型定义版本是否匹配
内存溢出	JavaScript heap out of memory	在Node启动参数中增加--max-old-space-size=4096、检查是否存在循环引用和大型源文件
Plugin冲突	Cannot read properties of undefined	检查Plugin的版本兼容性、调整Plugin的加载顺序、尝试逐个禁用Plugin排查
输出路径冲突	Conflict: Multiple assets emit different content	检查多个entry/chunk是否输出到同一文件名、检查copy-webpack-plugin的配置

知识库扩展：错误诊断知识库应设计为可扩展的，允许团队添加自定义的错误模式和解决方案。通过编写简单的规则文件，团队可以将项目特有的错误类型和维护经验沉淀下来，形成组织级的构建知识资产。

5.4 构建环境兼容性检查

环境兼容性问题是构建错误的隐形杀手，特别是在团队协作和CI/CD环境中。Plugin通过以下检查确保构建环境的一致性：

Node.js版本检查：检查当前Node.js版本是否满足构建工具的最低要求。Webpack 5需要Node.js >= 12.20.0，Vite 5需要Node.js >= 18.0.0。版本不匹配时，会给出升级或降级建议。
操作系统差异：检测跨平台构建时的潜在问题，如路径分隔符（Windows的反斜杠 vs Unix的正斜杠）、换行符（CRLF vs LF）、环境变量语法差异等。对于在Windows上开发但在Linux上部署的团队，建议在配置中使用path模块跨平台API。
包管理器一致性：检测项目是否混合使用了npm、yarn和pnpm。建议团队统一使用同一种包管理器，并添加preinstall脚本或在CI中锁定包管理器版本。
系统资源检查：检测可用内存、CPU核心数、磁盘空间等系统资源是否满足构建需求。当资源不足时给出调整建议，如增加Node.js内存上限、关闭其他占用资源的程序等。
依赖完整性验证：检查所有必需的依赖是否已安装、版本是否匹配package.json中的声明范围、lock文件是否与package.json一致。对于lock文件过期的问题，建议运行npm audit或yarn dedupe。

// 环境兼容性检查脚本核心逻辑
async function checkEnvironment(): Promise<EnvCheckResult[]> {
  const results: EnvCheckResult[] = [];
  const nodeVersion = process.versions.node;

  // Node.js版本检查
  if (semver.lt(nodeVersion, '18.0.0')) {
    results.push({
      type: 'node_version',
      severity: 'error',
      message: `当前Node.js版本 ${nodeVersion} 过低`,
      suggestion: 'Vite 5 需要 Node.js >= 18，建议使用 nvm 升级'
    });
  }

  // 内存检查
  const memGB = process.memoryUsage().heapTotal / 1024 / 1024 / 1024;
  if (memGB < 4) {
    results.push({
      type: 'memory',
      severity: 'warning',
      message: `可用内存不足 (${memGB.toFixed(1)}GB)`,
      suggestion: '大型项目建议分配至少4GB内存：NODE_OPTIONS="--max-old-space-size=4096"'
    });
  }

  return results;
}

构建环境兼容性检查应在项目初始化阶段或构建流程开始时自动执行，以便在问题发生前预警。建议将其集成到prebuild脚本中，确保每次构建都在健康的环境中执行。