企业官网建设流程全解析

如果你手头有一个几年没动过的vue2老版本项目，今天突然要跑起来改需求，那大概率会遇到我下面要说的场景：npm install跑了半小时还在转圈，npm run serve卡在Compiling...后面再也不动弹，任务管理器里 node 进程占满 CPU，页面打开要么白屏要么转菊花。这种 vue2 老版本项目启动过程中卡死的问题，我处理过不下十个，今天把排查思路和解决办法一次性讲清楚。

这篇文章适合谁？三种人：一是接手了公司遗留后台管理系统的前端，二是想把自己大学毕设老项目重新跑起来的同学，三是运维或全栈想临时处理前端构建问题的朋友。我会从现象分类、环境兼容、构建配置、依赖冲突四个层面拆解，最后附一个高频问题速查表，看完基本都能自己修好。

1. 先弄明白：你的“卡死”到底卡在哪里

很多人一上来就疯狂百度“vue2 项目启动卡死怎么办”，然后乱改一顿配置，结果越改越乱。我的建议永远是先定位，再动手。所谓“卡死”其实可以分成三个完全不同的阶段，每个阶段的病根和方法都不一样，混在一起处理只会事倍功半。

1.1 三个阶段，三种病根

第一个阶段是依赖安装卡死。也就是npm install装到一半再也不动了，或者装了好几个小时还在reify阶段打转。这种情况八成是网络问题、镜像源问题，或者是 npm 版本太新导致的依赖冲突解析问题，跟项目代码本身没什么关系。

第二个阶段是启动编译卡死。命令已经执行到vue-cli-service serve，终端停留在某个百分比或者某条 loader 日志上，CPU 狂飙但就是不出结果。这种情况通常跟 Node 版本不兼容、node-sass 这类原生模块编译不过、webpack 配置不合理、内存溢出有关。

第三个阶段是运行阶段假死。项目编译成功了、浏览器也能打开，但页面转圈、点击没反应、内存持续上涨，最后浏览器卡到无响应。这种就属于运行时问题，常见于 vue2 生命周期里的死循环、定时器没有清理、keep-alive 页面缓存过度膨胀，或者某些第三方插件在浏览器新版本策略下频报错误。

大部分人说“项目启动卡死”，其实说的是第二和第三种。但如果不区分清楚，你很可能会在一个根本不是问题的地方浪费大量时间。

1.2 最快定位卡点的三个命令

我处理这类问题的标准动作有三个。

第一，打开任务管理器（Windows）或活动监视器（macOS），看 node 进程的 CPU 和内存占用。如果 node 的 CPU 长时间稳定在 99% 到 100%，说明是编译或打包阶段的逻辑死循环，或者某个 loader 在处理超大文件时陷入了计算瓶颈。如果 CPU 不高，但内存占用一直涨，那更可能是内存溢出或者加载依赖时发生了死锁等待。如果 CPU 和内存都不高，但 npm 就是不动，那基本可以断定为网络或远程仓库连接问题。

第二，看终端最后几行日志。webpack4 时代，编译过程会打印 loader 名称、模块路径、百分比进度。卡住的那一行往往就是问题所在。比如卡在node-sass相关的日志，优先怀疑 node 版本；卡在sass-loader处理某个.scss文件，可能文件太大或引入了动态@import；卡在babel-loader处理node_modules路径，大概率该排除的没有排除。

第三，做一个 5 分钟最小化验证。先跑npm install并确认安装阶段正常，再跑npm run serve。如果安装阶段就停了，直接看下一章的解决办法；如果安装正常、启动卡死，就往下看编译优化部分。这一步能帮你锁定问题边界，避免在错误的楼层里打转。

2. 环境兼容性排查：九成卡死源于Node与依赖版本错配

这一节我要重点讲，因为我自己踩过的坑、帮别人排掉的坑，十有八九都出在环境版本上。vue2 老项目通常诞生在 2018 到 2020 年之间，那个时代的 Node、npm、webpack 和现在的版本差异巨大，新环境跑老项目，光兼容性问题就能拦住你半天。

2.1 Node版本与node-sass的血泪账

老项目中有一类依赖极其特殊，就是node-sass。它不是纯 JavaScript 包，而是带有原生 C++ 模块的包，安装或者编译时需要调用node-gyp去下载预编译二进制或者现场编译。问题来了：不同版本的 node-sass 只支持特定范围的 Node 版本，超出范围就会在构建时卡住，甚至直接报错。

常见的对应关系我整理了一张表：

如果你拿现代的 Node 18 或 Node 20 去跑一个依赖 node-sass@4.14 的 vue2 老项目，在npm install阶段就可能触发 node-gyp 源码编译，然后卡在一个地方一整晚都不动，就算运气好装上了，npm run serve编译到 scss 文件也会瞬间崩掉或卡死。

解决办法有两个。第一个是直接用nvm（Node Version Manager）切换到一个匹配的 Node 版本，这也是我不换行的首选方案。比如老项目绝大多数用 vue-cli 3 或 webpack4，我一般直接切到 Node 12.22.12，几乎能覆盖市面上大部分 vue2 老项目。

第二个办法是把 node-sass 换成纯 JS 实现的sass（也就是 dart-sass），这样就可以在新 Node 下正常跑。但替换有几个坑，后面实操部分会详细说，最大的坑是/deep/选择器在 dart-sass 中不再支持，得改成::v-deep。

2.2 依赖安装阶段卡死的处理步骤

如果你现在遇到的是npm install卡住，别急着删 node_modules，先按下面的顺序排查。

第一步，检查镜像源。老项目的开发者可能在不同的网络环境下工作，.npmrc里也许残留了一个懒人专用镜像或者公司内部源。执行npm config get registry看看当前源是什么。如果显示的不是公共源，建议直接切到淘宝镜像源，命令是npm config set registry https://registry.npmmirror.com。

第二步，处理 lock 文件冲突。很多老项目同时存在package-lock.json和yarn.lock，或者 lock 文件是老版本 npm 生成的，新版本 npm 解析时会陷入极其耗时的依赖树构建。最省事的做法是删除node_modules和package-lock.json，然后重新npm install。注意，前提是你能接受依赖版本被重新解析，如果项目里锁定了某些特殊版本，可能装出来的依赖和之前不完全一致，但老项目整体风险不大。

第三步，留意 npm 7 以上的 peerDependencies 严格校验。vue2 老项目依赖关系通常很乱，比如某个插件依赖了低版本的 vue-router，但你项目里装的是新版本，npm 7 会直接报 ERESOLVE 错误并终止安装，表现就是命令卡在某个阶段反复重试。解决办法是在安装命令上加一个参数：npm install --legacy-peer-deps。这个参数能跳过 peerDependencies 的自动冲突检测，对老项目来说是救命的。

第四步，检查postinstall脚本。有的老项目在 package.json 里配置了postinstall: node scripts/build.js或者类似的钩子，如果这个脚本里有网络请求或者复杂操作，安装到这一步也会长时间卡住。可以把钩子先注释掉，装完依赖再单独跑。

这套流程走下来，依赖安装阶段的卡死基本都能解决。如果还是卡，大概率是网络或者 npm 缓存坏了，清一下缓存再试：npm cache clean --force。

3. 启动编译阶段：内存、Loader与构建缓存的调优

依赖装好了，npm run serve也执行了，但终端卡在编译阶段，CPU 拉满，风扇呼呼转。这个阶段的问题一般不是“项目坏了”，而是老项目的构建工程能力跟不上现在的机器和 Node 环境。

3.1 编译内存溢出的排查与解决

vue2 老项目普遍依赖 webpack4，而 webpack4 模式下 Node 默认的堆内存上限大约是 1.5GB 到 2GB。老项目往往没有对依赖做细粒度的按需引入，以至于一开始打包就要解析几千个模块，内存很容易飙到上限，然后报出一个很吓人的错误：

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

有些情况下不会直接报错，而是表现为卡死、页面和终端都没响应，其实本质上就是内存不够了，GC 一直在疯狂回收但收不干净。

解决方法很简单：在启动命令里提高 Node 的堆内存上限。比如原先的启动命令是vue-cli-service serve，可以改成：

{ "scripts": { "serve": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vue-cli-service serve", "build": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vue-cli-service build" } }

注意 Windows 下直接设置环境变量可能不生效，所以要配合cross-env这个包来保证跨平台可用。先执行npm install cross-env --save-dev，然后加上面这段配置就行。

如果你不想改 package.json，也可以用临时环境变量启动。Windows 的命令行下执行set NODE_OPTIONS=--max-old-space-size=4096 && npm run serve，macOS 或 Linux 下执行NODE_OPTIONS=--max-old-space-size=4096 npm run serve。这个参数的意思是把 Node 的堆内存上限提高到 4GB，一般够用了。

3.2 提升编译速度与稳定性的配置方案

内存解决之后，如果编译还是特别慢，或者偶尔卡在某个 loader 不出结果，那就要从 webpack 配置层面调优。vue2 老项目大多用的是vue.config.js（vue-cli 3/4）来自定义配置，我通常会在里面加这几项：

const HardSourceWebpackPlugin = require('hard-source-webpack-plugin'); module.exports = { transpileDependencies: false, configureWebpack: { devtool: 'source-map', plugins: [new HardSourceWebpackPlugin()], performance: { hints: false } }, chainWebpack: config => { config.module .rule('js') .test(/\.js$/) .exclude.add(/node_modules/) .end(); }, parallel: true, cache: true };

这里有几个关键点。第一，parallel: true可以让 thread-loader 参与多进程编译，老项目模块多的时候提升明显。第二，HardSourceWebpackPlugin是 webpack4 环境下的构建缓存插件，第一次编译慢点，第二次开始会快很多，这种“先慢后快”的表现非常正常。第三，exclude.add(/node_modules/)可以避免 babel-loader 转译 node_modules 里的老旧代码，这个也是很多项目启动卡死的隐患之一。

还要提醒一个容易误判的点：老项目编译慢，和编译卡死是两件事。如果终端还在持续输出进度、CPU 有波动、日志逐渐增加，那就只是慢，耐心等即可。真正卡死是五分钟、十分钟都没有任何新输出，这时候才需要按上面的思路调。我自己在处理一个包含大量第三方图表库的老项目时，第一次编译跑了 7 分钟，看起来像死了，实际上是在硬啃 echarts 和 xlsx 这种大库，加上缓存之后第二次编译就降到 50 秒了。

3.3 启动后浏览器白屏或持续加载的排查

有时候编译完全正常，终端已经提示App running at Local: http://localhost:8080，但浏览器打开就是白屏或者一直转圈。这种“假启动卡死”也很让人头疼。我的排查套路是分三步。

先按 F12 打开开发者工具，切到 Network 面板，看主文档和接口的请求状态。如果接口一直在 pending，这跟前端构建没关系，是后台服务或者跨域代理出了问题，vue-cli 的 devServer 里配置代理的尤其常见。可以检查vue.config.js里的devServer.proxy配置对不对，或者干脆先用本地 mock 数据验证。

再看 Console 面板，有没有大量报错。常见的有Uncaught SyntaxError、TypeError: Cannot read properties of undefined，这类报错说明项目里某些第三方插件在运行时执行到了不兼容的代码段。排查方法是用“注释法”：临时把 main.js 里挂载的插件逐个注释，注释哪一个后页面恢复，问题就出在谁身上。

最后看内存趋势。如果页面打开后内存持续上涨且不回落，大概率是死循环或者大量的定时器没有清理。尤其是老系统里普遍存在的keep-alive页面缓存机制，如果组件里写了setInterval却只放在beforeDestroy里清理，而keep-alive组件切换时根本不触发beforeDestroy，定时器就会越积越多，最后卡到浏览器崩溃。这个问题的根源就是 vue2 生命周期钩子的使用时机不对，下面专门开一节来展开。

4. 依赖冲突与特殊场景：vue-ueditor-warp、txt预览与浏览器策略

除了环境和构建问题，vue2 老项目启动或运行卡死还有一类高频诱因，就是依赖冲突和浏览器新策略。这些问题和热门搜索词里的vue2 安装vue-ueditor-warp版本冲突、vue2 permissions policy violation unload息息相关。

4.1 老项目安装vue-ueditor-warp的版本冲突

老后台管理系统里插入富文本编辑器是刚需，很多人当年选择了vue-ueditor-wrap。这个插件本身是为 vue2 设计的，问题爆发点在 npm 版本升级之后。新版 npm（7 及以上）会严格校验依赖的 peerDependencies，而vue-ueditor-wrap@2的 peerDependencies 里写了 vue ^2.x，同时它内部的子依赖可能又依赖了旧版 vue，这就导致在安装阶段报 ERESOLVE 错误，表现就是npm install一直卡在某个地方重试、看起来像“项目启动卡死”。

解决办法是安装时用兼容老版本依赖树的命令：

npm install vue-ueditor-wrap@2 --legacy-peer-deps

注意 vue2 项目一定要用@2，vue-ueditor-wrap@3是 vue3 专用，装错了同样会在运行时报一堆莫名其妙的错误。

装好之后还有一个额外坑：vue-ueditor-wrap 默认需要知道你放 UEditor 静态资源的路径，老项目如果没有正确配置ueditorPath，编译能过，但浏览器打开富文本编辑区域会一直加载空白。这个不算卡死，但表现很像卡死。正确姿势是下载一份 UEditor 静态资源放到项目的public目录下，然后在组件里这样配置：

<vue-ueditor-wrap v-model="content" :config="editorConfig" /> data() { return { editorConfig: { UEDITOR_HOME_URL: '/UEditor/', serverUrl: '/api/ueditor' } }; }

4.2 txt在线预览功能与Permissions-Policy策略

近两年经常有人遇到这样一个具体报错：控制台提示permissions policy violation: unload is not allowed in this document.。这个报错在老项目里特别常见，因为有相当多后台系统都做过“在线预览 txt 文件”之类的功能，做法通常是开一个 iframe 或者新窗口，然后在原页面的onunload或beforeunload里做一些清场操作。

问题出在 Chrome 103 之后对unload事件做了权限策略限制，默认禁止跨文档的 unload 监听，所以如果你的代码里还有window.addEventListener('unload', handler)这种写法，浏览器就会在页面关闭或跳转时卡住，有的场景下甚至表现为页面一直白屏、关不掉、假死。

处理思路有几个。最推荐的是代码层面直接改，把beforeunload和unload里的操作迁移到pagehide事件里：

window.addEventListener('pagehide', () => { // 清理逻辑 });

pagehide事件在移动端和桌面端兼容性都很好，而且不受 Permissions-Policy 限制。如果这个页面是老系统里嵌的 iframe，且 iframe 的 unload 被顶层页面策略拦截，那就需要从响应头设置 Permissions-Policy。开发环境下可以在vue.config.js的 devServer 里加：

module.exports = { devServer: { headers: { 'Permissions-Policy': 'unload=()' } } };

生产环境如果用的是 Nginx，可以在对应 server 块里加一行：

add_header Permissions-Policy "unload=()";

这里要注意，Permisison-Policy 的赋值语法在新版浏览器里是unload=()这种带括号的形式，老资料里写的unload 'none'已经过时了。加完之后刷新页面，那个 violation 报错就会消失，页面假死的概率也会直线下降。

4.3 生命周期陷阱导致的运行时假死

vue2 的生命周期本身不算复杂，但老项目里混乱的使用方式，却经常导致极其隐蔽的假死。我举个例子，某个列表页在created里写了一个循环轮询接口，setInterval(() => this.fetchList(), 3000)，然后在beforeDestroy里clearInterval。看起来没问题，但如果页面被keep-alive包裹，组件切换时根本不会走beforeDestroy，定时器就一直挂在后台，每三秒打一次接口，几个页面来回切换之后，浏览器资源就被耗干了，表现为整个系统越来越卡，最后完全无响应。

修复思路是组件内同时监听生命周期钩子，或者使用activated和deactivated来处理：

activated() { this.timer = setInterval(() => this.fetchList(), 3000); }, deactivated() { clearInterval(this.timer); this.timer = null; }, beforeDestroy() { clearInterval(this.timer); this.timer = null; }

另一个常见的运行时假死场景是watch里写递归逻辑。比如监听一个对象，又在 handler 里修改这个对象的某个字段，而deep: true会把这种修改再次触发监听，造成无限循环。这种死循环最可怕的地方在于根本不会报错，只会让 CPU 直接拉满，页面主线程阻塞到任何点击都没反应。排查方法也很笨但有效：把 watch 里的代码临时注释掉，页面恢复，那就是 watch 的问题；再用控制台console.log打印触发频率，看到日志在疯狂刷屏，基本就能确认死循环位置了。

老项目里还有一种和生命周期相关的坑：在mounted里注册了全局事件监听，比如window.addEventListener('resize', handler)，但组件销毁时没有removeEventListener，重复进入退出页面会导致监听器数量爆炸。这种问题很难一次复现，但累积到一定程度，页面也会慢慢卡死。建议在项目稳定后做一次全局排查，凡是在mounted里有 addEventListener 的地方，必须和beforeDestroy里的 removeEventListener 成对出现。如果担心遗漏，也可以用 Vue 官方推荐的$once配合$on('hook:beforeDestroy')来做绑定，老项目里这样处理更集中。

5. 常见问题快速排查表与我的实操心得

前面四章是完整的排查逻辑，到了这一章我直接给出结论，方便你遇到问题的时候不用重新梳理，拿起来就能用。

5.1 高频问题速查表

这张表覆盖了我过去几年处理 vue2 老项目启动卡死问题的大部分场景。你可以把这张表截图或者复制到自己的笔记里，下次再遇到类似问题，先对照查一遍，大概率比网上零散的文章更省时间。

5.2 几个值得长期保留的实操习惯

最后分享几条实操习惯，是我在多次处理老项目之后沉淀下来的。

第一，在项目根目录放一个.nvmrc文件，内容就是一行 Node 版本号，比如12.22.12。这样后续任何人接手项目，只要看这个文件就知道该用哪个 Node 环境，能避免非常多的兼容性问题。

第二，老项目升级依赖要“一次只动一条”。不要觉得 nm 项目就一次性把 vue、webpack、sass-loader 全部升到最新版，这样一旦出问题，你根本不知道该回滚谁。正确做法是记住当前状态，改一个依赖就启动一次，确认没坏再改下一个。

第三，如果你决定把 node-sass 替换成 sass，记得把代码里的/deep/选择器全局替换成::v-deep，否则编译会直接报错。字体文件和图标库的路径问题也要注意，node-sass 和 dart-sass 对@import的解析严格程度不一样，你可能会遇到某些原来能跑的 scss 文件在新编译器下报错。

第四，如果项目里带了 vue-ueditor-wrap、txt 在线预览这类老插件，建议把它们独立成懒加载组件，不要一进主界面就全部加载。这样既能降低项目启动时的编译压力，也能减少运行时卡死概率。

我在实际处理这类 vue2 老项目的时候，最深的体会是：不要急着“做大升级”，先“止血”再“治理”。这个卡死问题表面上是环境不兼容、依赖冲突、浏览器策略这些技术点，但底层逻辑其实是老代码和新环境之间的系统性问题。先把项目用最保守的方式重新跑起来，再去考虑替换依赖、升级 Vue3 或者重构，风险会小得多。老项目就像一辆老车，机油滤芯老老实实换，别一上来就改引擎，反而能跑得更稳。