我最近接手了一个两三年没动过的 vue2 老版本项目技术栈还是 vue2.6 vue-cli 4.5 webpack 4 那一套。第一天拉代码、装依赖都很顺利等运行npm run serve那一刻噩梦来了终端输出停在某个百分比CPU 直接拉满笔记本风扇狂转进程既不报错也不退出只能强制关终端。这个“vue2 老项目启动过程中卡死”的问题我前后折腾了两个晚上踩了不少坑也总结出了一套可以照着用的排查路径。如果你手头也有一个年代久远的 vue 项目遇到类似问题这篇文章应该能帮你省掉大把时间。这篇文章我想按自己的排查经验来写不按文档顺序而是按“从现象到根因”的思路来展开——先教你判断卡死到底卡在哪一层再讲内存、版本、源码这三类最常见的“真凶”最后给你一份可以直接抄的完整排查清单。1. 先分清启动“卡死”的三种形态很多同学遇到启动卡死第一反应就是删 node_modules 重装运气好能解决运气不好白等半小时。我的经验是先观察再动手。“卡死”和“卡死”之间差别很大形态不同定位方向完全不同。1.1 形态一编译进度条停在某一步终端上能看到20% building modules、70% after emitting这样的进度信息但长时间不动。这种大多数是 webpack 编译环节出了问题要么是某个 loader 处理一个大文件时性能崩了要么是某个插件在 emit 阶段做了重活要么干脆就是内存不足导致 GC 一直在反复回收看起来像死了一样。这种形态比较好定位因为 webpack 的进度输出实际上给了你一个“坐标”。比如卡在30% building modules问题大概率在模块解析阶段卡在70% after emitting问题在输出文件写入或插件后处理阶段。记住这个坐标下文排查时直接用得上。1.2 形态二进程活着但 CPU 满载任务管理器里 node 进程还在CPU 占用 100% 或接近 100%内存也在不断上涨但终端就是不出新内容。这种情况十有八九是进入了死循环或者事件循环被持续的同步任务阻塞。我遇到过一次某老项目里有人写了一个工具函数在模块顶层对某个全局对象做了Object.defineProperty的拦截结果 webpack 的 watch 模式在监听文件变化时会反复触发这个模块重新执行然后它又去修改文件系统或者触发其它监听事件形成了“自我触发”的闭环。表面上看 CPU 100%实际上是在无限循环。1.3 形态三编译完成却无响应webpack 好像编译完了浏览器也能打开但页面白屏控制台也没有报错或者终端显示Compiled successfully但页面一直转圈。这种严格说不是“启动卡死”但很多人的直观感受就是“项目启动不了”。这种通常是你改了某些配置或升级了依赖后运行时挂掉了但开发服务器的错误被吞了。重点方向是检查浏览器控制台有没有资源加载失败、接口 404、或者某个 polyfill 在低版本浏览器上的兼容问题。先花五分钟判断清楚是哪种形态接下来的排查效率会高很多。我自己的习惯是看到进度条卡住先截图坐标看到 CPU 满载先等一分钟确认是不是真的不推进然后才决定要不要强制结束进程。2. 内存才是头号嫌疑人Node 进程的“锅”怎么背排查 vue2 老项目启动卡死我会先动内存方案。原因很简单老项目依赖多、体积大而 node 默认的内存上限往往不够用这是最容易被忽略但最常见的原因。2.1 为什么 Node 进程会内存爆掉Node 的 Javascript 堆内存默认上限大约在 1.7GB 左右64 位系统这个上限不是物理内存而是 V8 引擎给 JavaScript 对象分配的空间上限。webpack 在处理一个大型项目时要把所有模块都读进内存、构建模块依赖图、执行 loader 转换、生成 chunk每一步都在消耗堆内存。老项目尤其明显依赖特别多node_modules 动辄几百 MB入口文件引入了一堆组件、图表库、工具库编译过程中需要保存的中间状态非常多。一旦堆空间不够V8 就开始频繁触发垃圾回收GCGC 本身会占用大量 CPU而且会暂停主线程。表现就是终端进度条半天不动CPU 却接近 100%看起来像“卡死”实际上是在“挣扎”。2.2 三行命令先榨出内存空间我排查 vue2 卡死问题时第一个动作就是把内存上限调大。这里分平台说一下在package.json的启动脚本里直接加NODE_OPTIONS是最优解法{ scripts: { serve: cross-env NODE_OPTIONS--max-old-space-size4096 vue-cli-service serve, build: cross-env NODE_OPTIONS--max-old-space-size4096 vue-cli-service build } }如果没有装cross-env先装上npm install cross-env --save-dev临时验证的话也可以直接在命令行里设置# Windows PowerShell $env:NODE_OPTIONS--max-old-space-size4096 npm run serve # macOS / Linux export NODE_OPTIONS--max-old-space-size4096 npm run serve提示4096 是 4GB我一般先给 4GB。如果项目特别大可以考虑 8192但这需要你的机器物理内存不低于 16GB否则会从“内存不足”变成“系统整体卡死”。这个参数到底有没有生效其实可以在卡死时打开另一个终端用wmic process where namenode.exe get ProcessId,WorkingSetSizeWindows或者ps aux | grep nodemacOS/Linux看 node 进程的实际内存占用。如果已经顶到 3GB 以上还卡着那就不是单纯内存上限问题得结合后面的方案继续查。2.3 手动控制内存上限的正确姿势这里我要多说一句--max-old-space-size只能调高 V8 老生代空间但如果你的应用本身存在内存泄漏调高只是把“爆炸时间”推迟不能根治。我见过一个老项目每次启动内存都会稳定上涨 200MB跑 20 分钟后必卡死调高到 8GB 也只是勉强跑到编译完成。对于这种情况我还习惯搭配一个监控参数看看是不是 GC 太频繁cross-env NODE_OPTIONS--max-old-space-size4096 --trace-gc vue-cli-service serve--trace-gc会把垃圾回收的日志打印到终端如果看到大量Scavenge和MarkSweep交替出现说明内存确实在边界上反复横跳。虽然日志很吵但能让你确认方向没有错。另一个容易被忽视的点Windows 上如果开了实时杀毒软件或者系统自带的安全扫描node_modules 目录几十万个文件会被反复扫描磁盘 I/O 和 CPU 直接爆炸。我在某公司内网环境遇到过一模一样的情况终端卡在一半不动把项目目录加入杀毒软件的排除列表后速度直接翻倍。如果你在 Windows 上遇到卡死且内存方案无效务必检查这一步。3. 版本错位才是老项目的隐形杀手内存方案解决不了的卡死第二怀疑对象就是版本兼容性问题。老项目的“老”不仅体现在代码上更体现在它和现在开发环境的适配度上。3.1 node 版本引起的兼容性连锁反应vue2 老项目基本都是用 vue-cli 2.x/3.x/4.x 创建的这些脚手架对 node 版本有各自的兼容范围。先说核心结论vue-cli 2.x webpack 3建议 node 1012最高别超过 14vue-cli 3.x/4.x webpack 4建议 node 1214最高别超过 16如果还用着 node-sassnode 版本和 node-sass 版本的绑定关系会非常折磨人你装上 node 18 甚至 20 去跑一个 node-sass 老项目安装阶段可能就报错就算装上了启动时也可能因为内置的 OpenSSL 算法不兼容直接抛digital envelope routines::unsupported错误。这个问题网上讨论很多但现实中很多同学没意识到不是所有的“启动报错”都叫报错有些时候它表现为“启动到一半卡死”因为模块在加载过程中的某个兼容分支里出了问题异常被吞掉了。我的建议非常直接用 nvm 切换到 node 14 再跑一遍。如果 node 14 下启动正常那就是 node 版本太新的问题。# 安装 nvm 之后 nvm install 14.21.3 nvm use 14.21.3 node -v npm run serve3.2 node_modules 重装与依赖锁定很多人觉得“重装 node_modules”是万能药但方法不对反而浪费时间。不要直接删掉就npm install我推荐按这个顺序来先删除node_modules和package-lock.json或yarn.lock清空 npm 缓存npm cache clean --force重新npm install如果项目有锁文件尽量用原来对应的包管理器安装。比如原来是 yarn 管理的就优先用yarn install不要混用 npm 和 yarn不然很容易装出不一致的依赖树。有一个老项目的坑我必须单独提老项目的package.json里往往直接写死的版本号带^或~比如webpack: ^4.44.0。重新安装时 npm 会拉取 4.x 的最新版比如 4.47.0这个版本本身没问题但它和某些被锁在旧版本的插件搭配时就会有潜在不兼容。稳妥的做法是找一下项目里有没有package-lock.json有的话别删直接npm ci按照锁文件安装。3.3 vue-cli / webpack 各个版本的配置差异vue2 老项目的卡死问题还要看它是 vue-cli 2.x 还是 3.x/4.x因为配置文件位置完全不同排查入口也不一样。vue-cli 2.x 的项目是build/目录下有一堆 webpack 配置文件webpack.base.conf.js、webpack.dev.conf.js等如果你想调 webpack 配置要找build/webpack.dev.conf.js。你要是在项目根目录找vue.config.js那是找不到的因为 2.x 根本不读这个文件。vue-cli 3.x/4.x 的项目才有vue.config.js而且对 webpack 配置的修改是通过configureWebpack和chainWebpack两种方式来做的。如果你搞不清楚项目用的是哪个版本直接看根目录有没有vue.config.js有就是 3/4没有大概率是 2。另外package.json里vue-cli-service的版本号也能看出来——2.x 时代是没有vue-cli-service的那是vue-cli的 2.x 版本才有的东西。我说这个概念的原因在于你搜“vue2 项目启动卡死”时搜到的解决方案可能是针对 vue-cli 4 的但你的项目是 vue-cli 2照着改发现根本没有那个文件会白白浪费时间。4. 源码层面的卡点排查从 watch 模式到死循环如果内存没问题版本也对那就要回到源码和配置本身。这个阶段最考验排查功力也是经验价值最高的部分。4.1 文件监听机制与 watchOptions 调优dev 启动时 webpack 会启动文件监听在 Windows 上这个监听机制特别容易出问题。因为fs.watch在 Windows 上使用的是文件系统变更通知某些网络驱动器、虚拟机和 IDE 的自动保存行为会导致监听事件持续触发webpack 就会反复重新编译表现就是“一直在 building永远编译不完”。vue.config.js 里可以手动指定轮询模式强制 webpack 用固定间隔去检查文件变更避免事件风暴// vue.config.js (适用于 vue-cli 3/4) module.exports { devServer: { watchOptions: { poll: 1000, aggregateTimeout: 300, ignored: /node_modules/ } } }如果你是 vue-cli 2.x配置文件在build/webpack.dev.conf.js里找watchOptions字段改就行。注意poll: 1000表示每 1000ms 轮询一次不要设成 100 或 50那样会让 CPU 压力更大。ignored一定要把 node_modules 排除掉否则全量监听几万个依赖文件不卡死才怪。还有一个高阶操作如果你确认了是监听器问题可以直接关掉监听跑一次不带 watch 的编译# 临时验证vue-cli 4 npx vue-cli-service build --no-watch如果 build 能顺利完成而 serve 卡死说明问题大概率出在 watch 机制上这时候集中精力调 watchOptions。4.2 单文件过大与 loader 处理瓶颈老项目里经常出现“一个 .vue 文件几千行”的情况尤其是页面组件和巨型工具类文件。webpack 在解析这种文件时babel-loader、eslint-loader、vue-loader 会挨个处理每一个 loader 都要把文件内容转换一遍、生成 AST、再转换回来文件越大耗时越长。最典型的例子一个组件脚本里直接import了一个几十 MB 的 JSON 数据文件loader 会先把这个 JSON 解析成对象再做 tree-shaking 分析。整个过程不是卡死但会让编译时间从几分钟涨到十几分钟期间进度条也像是卡住了一样。如果卡在building modules阶段我建议用排除法定位在vue.config.js临时把 eslintLoader 关掉老项目 eslint 卡死太常见了// vue.config.js module.exports { lintOnSave: false }对 vue-cli 2.x是在webpack.base.conf.js里把eslint-loader从 rules 里注释掉。看一下是不是某个 node_modules 里的包被 loaders 处理了。默认 webpack 不会把 node_modules 交给 babel-loader但如果你配了transpileDependencies或某个 loader 的 include 路径写错可能把 node_modules 也包含进去那个处理量会非常恐怖。打开终端跑npx vue-cli-service serve --progress看看到底在编译什么模块webpack 4 的 progress 输出有时候会显示当前处理的模块名。4.3 干掉隐藏的“假死”死循环这个是我碰到的几个案例里最隐蔽的一类。特征非常相似CPU 100%、内存缓慢增长、终端无输出、强制 kill 也没生成错误堆栈。排查死循环常规手段已经不够用我推荐用 Node 的调试工具抓现场。在启动命令里加--inspectcross-env NODE_OPTIONS--max-old-space-size4096 --inspect9229 vue-cli-service serve然后打开 Chrome 的chrome://inspect页面attach 到对应进程切到 Profiler 面板抓一份 3 秒的 CPU profile然后导出 JSON去webpack.github.io/analyse或者用加载插件官方分析工具做 dump 分析。虽然这个过程比较繁琐但能直接告诉你 CPU 时间到底耗在哪个函数上。在真实老项目里我抓到过几次这种死循环根源分别是某个工具库的getter函数里对window对象做了遍历扩展每次执行都会触发另一个模块的更新一个组件在render里直接修改了响应式数据导致 Vue 的 watcher 无限循环一个自定义 webpack 插件在afterCompile钩子里写了文件而这个文件又在 watch 范围内每次编译完都会触发下一次编译第三种最坑因为它表现成“编译永远不结束”但又不报错CPU 一直满。排查这类问题没有捷径只能靠 CPU profile 定位所以我把这个方法放在这里你如果前面几步都试过了还没解决一定试试抓 profile别靠肉眼猜。5. 一次完整的实战排查演练前面讲了一堆原理你可能还是有点懵。我拿一个真实的案例从头到尾跑一遍排查流程你对照自己的项目走流程就行。5.1 第一步确认环境和复现路径某团队给我看的项目是这样的vue 2.6.14、vue-cli 4.5.15、webpack 4.46.0node 版本 16.14.2。现象是npm run serve启动终端卡在60% building modules十几分钟不动。我先做了三个动作看 node 版本16还在 vue-cli 4 的可接受范围内先不切换看内存占用连续观察 1 分钟node 进程内存稳定在 2.1GB 左右不再上涨看 CPU单核满载内存没涨到上限所以先排除了纯粹的内存不足。CPU 满载但内存稳定方向转向“某个耗时的同步操作”。5.2 第二步二分法定位卡死模块网络上的教程这时候会叫你装speed-measure-webpack-plugin但那个插件和 webpack 4 的某些配置有兼容问题。我这次没有一开始就用插件而是先改了一点配置把编译过程拆开看。我在vue.config.js里写了一个临时配置把eslint和vue-loader的编译优化项临时关掉// 临时排查用不是最终方案 module.exports { lintOnSave: false, productionSourceMap: false, configureWebpack: { performance: { hints: false } } }重新启动之后进度条从 60% 推进到了 80% 左右才停住。说明问题不在 eslint也不是最前面的模块解析阶段而是更靠后的操作。接着我把productionSourceMap: false还原成true默认配置又卡在了 60%。这一下基本锁定了是 source-map 生成阶段的问题。进一步查下去发现node_modules 里有一个图表库的 dist 文件是压缩混淆过的巨型 JSwebpack 在为这个文件生成 source map 时需要先把压缩代码反向映射耗时极长几乎等于卡死。5.3 第三步性能分析定位瓶颈当然不是每次都能靠开关配置这么幸运地二分定位。如果你试了几次开关都找不到精确位置我可以分享一下准确率最高的做法借助speed-measure-webpack-plugin在 webpack 4 项目里的正确打开方式。先安装npm install speed-measure-webpack-plugin --save-dev然后在vue.config.js里临时包一层const SpeedMeasurePlugin require(speed-measure-webpack-plugin); const smp new SpeedMeasurePlugin(); module.exports { configureWebpack: smp.wrap({ // ...原配置 }) };如果项目里本身有 chainWebpack 配置这个插件会和它冲突。我的办法是临时把 chainWebpack 里的配置注释掉专门跑一次性能分析拿到各 loader 和 plugin 的耗时表然后再恢复。耗时表会告诉你每个 loader 处理了多少文件、花了多少时间哪个环节是明显短板一目了然。5.4 第四步修复与验证定位到那个巨型图表库之后解决方案就简单了把这个库用externals配置让 webpack 不要打包它改成在public/index.html里用 CDN script 标签直接引入全局对象。// vue.config.js module.exports { configureWebpack: { externals: { the-huge-chart-lib: TheHugeChartLib } } }同时把源代码里对应的import注释修改掉改成直接用全局变量。这样 webpack 不再解析这个文件的 source map启动速度从“十几分钟卡死”变成“40 秒编译完成”。提示externals 方案只对“运行时挂载在 window 上的第三方库”有效。如果你遇到的卡点不是第三方库而是自己项目里的一个大文件那就考虑拆分组件、按需加载或者用babel-loader的exclude配置把它单独排除掉。整个排查过程最关键的不是某个具体命令而是“先确认方向、再二分定位、最后做验证”的思路。很多同学卡死后直接删 node_modules属于跳过诊断直接开方子能中一次是运气中了三次以上才算经验。6. 长期维护建议与避坑清单排查完当前的问题如果你还需要长期维护这个老项目我建议把下面几个方向纳入日程避免下次启动再次踩坑。6.1 实在不行就拆依赖与 DLL如果你的项目启动慢到严重影响开发而且每次都要靠调内存上限硬扛考虑做拆包。老项目最推荐的是webpack.DllPlugin方案把不常变动的第三方库vue、vue-router、axios、echarts 这类提前打包成一个个 DLL 文件开发启动时直接用打包好的文件不再重复编译几百个依赖。vue-cli 4 没有内置 DLL 支持需要自己写一个 webpack 配置文件来生成 DLL然后在vue.config.js里通过add-asset-html-webpack-plugin把 DLL 引入到模板中。整个配置写出来大约需要一百多行代码但对一个大项目来说启动时间能缩短 50% 以上。这里有一个非常容易踩的坑DLL 打包的库如果版本更新了一定要重新生成 DLL否则运行时和编译时会因为模块实例不一致出现各种诡异报错。我见过一个团队因为这个原因提示“XX is not defined”排查了半天最后发现是 DLL 没重新生成。6.2 给你的老项目做“体检”与其每次启动卡死时才救火不如平时就给项目建立一个“健康档案”。我会定期做这几件事npm audit看看依赖安全状况注意老项目升级要谨慎不要为了修安全直接大版本升级容易引入不兼容。检查package.json里是否存在多个版本的同一个依赖比如项目里有webpack4又有某个插件依赖webpack5这种不一致经常导致编译期卡死。看看babel.config.js里配置的preset-env的targets是否合理targets 太宽泛会导致 babel 为更多低版本浏览器做转译编译时间成倍增加。老项目如果只在内部办公网使用targets 可以大胆收紧。比如 babel 配置从presets: [ [vue/cli-plugin-babel/preset, { targets: defaults }] ]改成只针对 chrome 最新版presets: [ [vue/cli-plugin-babel/preset, { targets: chrome 90 }] ]效果就是编译产物体积更小、转译工作更少。这种调整无需改业务代码风险很低。6.3 最后一条常被忽略的经验如果你试了上面所有方法仍然卡死还有一个非常隐蔽的元凶项目根目录或某层级目录下存在循环符号链接。webpack 在解析模块路径时遇到 symlink 默认会resolve.symlinks true它会把符号链接解析到真实路径如果真实路径又指回项目目录就会陷入无限往复的解析循环。检查方法很简单在项目根目录执行# Windows / macOS / Linux 通用 find . -type l -name node_modules如果发现有 node_modules 的符号链接把它删掉重新安装一次干净的依赖。别问我为什么会出现这种符号链接——某些 CI 工具、容器同步工具、网盘同步软件都会干这种事。我个人在实际操作中的体会是遇到老项目启动卡死最忌讳的是“凭感觉乱试”。先花两分钟判断形态再按内存 → 版本 → 源码 → 依赖的顺序逐层排查80% 的问题都能在半小时内定位。剩下 20% 的疑难杂症老老实实抓一次 CPU profile用数据说话比自己瞎蒙靠谱得多。最后再分享一个小技巧每次排查前先把当前能正常启动的 node_modules 备份改名比如node_modules_bak而不是直接删除。这样如果新装依赖后问题更严重还能秒回滚。这个习惯救过我很多次也希望能在关键时刻拉你一把。