用 jeecg-boot 做交付开发的朋友应该都有同感：后端启动很简单，真正让人血压上升的往往是前端npm run build。我前后用 jeecg 做过好几个管理系统，Windows 上构建、Linux 服务器上构建、CI 里构建，环境换一次，坑就换一批。标题里“使用 jeecg 前端 run build 的坑”这几个字，基本上就是每一个被生产环境 deadline 追着跑的人，在终端里反复敲npm run build时的心声。
这篇文章会把我在 jeecg 前端构建过程中真正踩过的坑、排查过的报错、最后验证可行的方案按顺序整理出来。适合正在做 jeecg 项目交付的开发者、要独立完成前后端部署的全栈新人，以及被“本地能跑但一 build 就挂”折磨得想骂人的人。我不会讲太多框架源码层面的东西，重点是可复现的排查路径和能直接抄的配置。
先说清楚一个前提：jeecg 前端分两大代际。老一代是 vue2 + vue-cli + webpack4，新一代是 vue3 + vite + ant-design-vue4。两者运行run build时遇到的坑，名字看着像，原因和解决方案完全不通用。所以你打开终端之前，先搞清楚自己手里是哪一代项目。
1. 摸清你的 jeecg 前端属于哪个时代，坑才能对症
1.1 从 package.json 一眼分辨 vue2 还是 vue3
拿到项目的第一件事，不要急着npm install，先打开package.json看 scripts 和 dependencies。vue2 老项目的脚本一般长这样：
"scripts": { "serve": "vue-cli-service serve", "build": "vue-cli-service build", "build:prod": "vue-cli-service build --mode production" }依赖里大概率有vue@2.x、ant-design-vue@2.x、node-sass，构建底层是 vue-cli 和 webpack4。vue3 新项目的脚本一般是：
"scripts": { "dev": "vite", "build": "vite build", "build:pro": "vite build --mode production" }依赖里有vue@3.x、ant-design-vue@4.x、vite。这个区分决定你后面排查的方向。vue2 项目八成会撞上 node-sass、webpack4 和 node 17+ 的 OpenSSL 问题；vue3 项目更多是 vite 版本、Node 版本、pnpm 配置问题。
1.2 Node 版本不匹配会报哪些错
jeecg 这类低代码平台对 Node 版本非常敏感，因为依赖树太大，构建工具和底层库都要匹配。
vue2 老项目，建议 Node 12 到 16 之间，不要用 17 以上。如果你在 Node 17+ 上跑老项目，大概率会见到这个经典报错：
Error: error:0308010C:digital envelope routines::unsupported这是 webpack4 内置的加密算法和 OpenSSL3 不兼容导致的。临时方案是设置环境变量NODE_OPTIONS=--openssl-legacy-provider，但更推荐直接用 nvm 切回 Node 16。作为长期维护的项目，我不会靠环境变量硬撑，因为团队成员、CI 环境很难全部统一记住这个变量，节点一换又炸。
vue3 新版 jeecg，官网一般要求 Node 18 或 20。如果你的 Node 版本低于 16，vite build 会在启动阶段直接提示版本不支持，甚至什么都不输出就退出。新版项目不要再使用 14，vite 4/5 在 Node 14 下容易出现Cannot find module 'undici'之类莫名其妙的依赖缺失问题，追起来很费时间。
1.3 锁定包管理器，别和 lock 文件过不去
jeecg 官方文档里 vue3 版本经常推荐pnpm install，vue2 老项目一般用 npm。但很多交付项目是从同事手里接过来的，别人用什么装的，你最好跟着用什么。
我之前接手一个项目，代码里有package-lock.json，结果前一个人习惯用 yarn，把yarn.lock也提交上去了。我npm install之后构建失败，报错指向某个组件版本不对。排查到最后发现，是我本地生成的 node_modules 和项目既有 lock 文件不一致，依赖树整个乱了。
处理办法比较粗暴但有效：删掉node_modules，删掉所有 lock 文件，选定一个包管理器，重新安装。注意，package.json里如果依赖写得不全，删 lock 后版本浮动也可能翻车，所以能保留 lock 就保留 lock，能固定版本就固定版本。jeecg 这种依赖量级的项目，最怕团队里 npm、yarn、pnpm 混用，一人一个版本，构建结果各不相同。
2. 安装依赖这一步就能掀桌子：node-sass、镜像、锁文件
2.1 node-sass 永远是旧版 jeecg 的第一道坎
vue2 老版 jeecg 项目里如果用了node-sass，你在新环境npm install时经常会看到 node-gyp 编译失败、python 环境缺失、Visual Studio 编译工具找不到这类报错。原因很简单，node-sass 安装时需要根据当前 Node 版本去下载对应的二进制文件，下载源在国外，网络稍微不稳定就失败。就算网络正常，Node 版本太新，可能根本没有对应的预编译二进制，于是回退到本地源码编译，这时就需要 python 和 C++ 编译链。
最省事的方案是给 npm 设置镜像源，让 node-sass 从国内镜像下载二进制。在项目根目录创建.npmrc：
sass_binary_site=https://npmmirror.com/mirrors/node-sass/然后删掉node_modules重新安装。这个方法我试过最稳，不用改任何代码。
有些人会建议把 node-sass 换成 dart-sass，因为官方已经不维护 node-sass 了。但对于老 jeecg 项目，我一般不建议一上来就换，因为项目里某些组件可能依赖 node-sass 的旧版编译行为，换成 dart-sass 后部分样式输出会变，出现样式错乱更难排查。先尝试设置镜像，实在不行再考虑替换方案。
2.2 换镜像源的正确姿势
不管 vue2 还是 vue3，jeecg 的依赖量大，直接 npm install 经常超时、下载中断。用国内镜像能明显提速：
npm install --registry=https://registry.npmmirror.com如果想长期生效，写入项目根目录.npmrc：
registry=https://registry.npmmirror.com这里有一个我踩过的坑：不要为了图快用 cnpm 安装 jeecg 前端项目。cnpm 的 node_modules 目录结构和 npm 不一致，很多包会通过软链方式引用，jeecg 依赖太多，软链一多就出幺蛾子，最常见的是构建时Cannot find module 'xxx'，排查半天发现是 cnpm 装的依赖导出模式不对。我在老 jeecg 上被这个问题坑过两次，后来统一规定：这个项目只允许 npm 装，除非官方明确支持 pnpm 且配置好。
安装后如果还是莫名报错，先跑一次npm cache verify，再删node_modules重装。有时候不是依赖有问题，是本地缓存了损坏的包文件。
2.3 pnpm 安装新版 jeecg 的隐藏配置
新版 jeecg-boot-vue3 官方推荐 pnpm，但很多人漏了关键配置。如果你直接用pnpm install，有可能会遇到构建时找不到vite、找不到ant-design-vue的子依赖这类报错。原因在于 pnpm 默认的依赖隔离策略：它会把依赖放进.pnpm目录，不对项目直接暴露所有传递依赖。
解决办法是在项目根目录建.npmrc，写入：
shamefully-hoist=true这个配置会让 pnpm 把依赖提升到和 npm 类似的扁平结构下。加完这个配置，删掉node_modules重新pnpm install，新版 jeecg 的构建成功率会高很多。
另外 pnpm 自身版本也要注意。pnpm 7 和 pnpm 8 的 lockfileVersion 不一样，团队里有人用 7 有人用 8，提交的pnpm-lock.yaml会被反复修改，同样会造成依赖混乱。最好统一 pnpm 版本，或者干脆用 npm。对于交付项目，我倾向于选最简单可控的方案，而不是理论最优方案。
3. 构建过程中的两座大山：内存溢出与长时间无响应
3.1 JS heap out of memory 到底是什么问题
构建跑到一半，终端突然刷出一大段FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory，这是 jeecg 前端构建最经典的崩溃瞬间。
原理其实很直接：Node 的 V8 引擎在 64 位系统下，默认老生代内存上限大约是 2GB 左右，而 jeecg 这个量级的项目，打包时要把 ant-design-vue、echarts、codemirror、tinymce 这些巨型依赖全部读取、转换、优化、压缩，中间结果全部存内存里，上限到了就崩。
这个坑尤其容易出现在低配的开发机或者默认配置的 CI 机器上。本地开发用的是npm run serve，它不需要把所有东西压缩优化，内存压力没那么大，所以很多人在本地跑了一百遍都没事，放到服务器上 build 就崩，下意识以为服务器配置不够，其实更多时候只是 Node 内存上限没调。
3.2 设置构建内存的标准操作
直接改启动命令是最快的。Windows PowerShell 下：
$env:NODE_OPTIONS="--max-old-space-size=4096"Linux 或 macOS 下：
export NODE_OPTIONS="--max-old-space-size=4096"然后重新执行npm run build。如果这个环境变量设置成功，Node 进程会使用最大 4GB 堆内存，对大多数 jeecg 项目来说足够。
但手工设置环境变量只对当前终端有效，换个同事、换台机器又得重新弄。更推荐直接写进 package.json 的脚本里，需要跨平台就加 cross-env：
"build": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vue-cli-service build", "build:pro": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vue-cli-service build --mode production"vue3 新版同理，把命令换成vite build。
注意一个细节：内存上限不是越大越好。如果构建机物理内存只有 4GB，你设 4096，系统可能直接卡死或者触发 OOM Killer。建议按构建机内存的一半到三分之二设置，比如 8GB 机器设 4096 或 6144，16GB 机器设 8192。
3.3 构建慢、日志卡住时先别急着 Ctrl+C
jeecg 的依赖数量动辄几万个文件，首次构建需要解析整个依赖图，3 到 10 分钟都很正常。很多新手看到终端停在某个阶段半天不动，以为卡死了，直接 Ctrl+C，其实它正在做压缩或者序列化缓存。
我的建议是：给构建命令加上进度展示。vue-cli 项目可以：
vue-cli-service build --progressvite 项目默认就会显示构建进度百分比。如果进度条很久不推进，再考虑是不是真的卡住了。还有一个经验：如果在构建过程中查看 CPU，发现某个进程一直占满核心，说明它在正常干活；如果 CPU 占用很低，但日志也不动，那才需要怀疑是死锁或者某个插件挂起。
3.4 合理的 chunk 拆分对构建内存和首屏都有好处
jeecg 默认把大量代码打在一个 chunk 里，构建时这部分压缩要占用大量内存。合理拆分大依赖，能让构建过程的内存压力分散，产物也能被浏览器更好地缓存。
vue2 老项目建议在vue.config.js里调整 splitChunks：
configureWebpack: { optimization: { splitChunks: { chunks: 'all', cacheGroups: { echarts: { test: /[\\/]node_modules[\\/]echarts[\\/]/, name: 'chunk-echarts', priority: 10 }, antd: { test: /[\\/]node_modules[\\/]ant-design-vue[\\/]/, name: 'chunk-antd', priority: 10 } } } } }vue3 新版在vite.config.ts里配置：
build: { rollupOptions: { output: { manualChunks: { 'antd': ['ant-design-vue'], 'echarts': ['echarts'] } } } }注意：拆 chunk 会生成更多的 JS 文件，如果 nginx 或服务器没配好缓存策略，可能反而影响加载。我的习惯是：先不动拆分，用调内存的方式保障构建成功；等构建稳定了，再根据实际产物大小决定要不要拆分。jeecg 这种低代码平台，稳定优先，优化其次。
4. 构建成功后才是真正的修罗场：白屏、404与接口地址
4.1 白屏问题：先分清资源加载失败还是路由没挂载
构建成功不等于部署成功。部署后打开页面一片白，是 jeecg 交付项目最高频的问题。
第一步先看浏览器控制台和 Network 面板。如果控制台一堆 JS 文件 404，那是 publicPath 或 base 路径配错了。vue2 项目在vue.config.js里：
publicPath: process.env.VUE_APP_PUBLIC_PATH || './'vue3 项目在vite.config.ts里：
base: './'如果部署在域名根路径，用'/'也行。但如果你把前端产物放在某个子目录下，比如https://域名/jeecg/，就必须把 base 或 publicPath 设置成'/jeecg/'，否则 index.html 里引用的 JS 路径会指向根目录，结果全部 404。
如果 JS 都加载成功了，页面还是空白，那是另一个问题：路由没有匹配到任何页面组件。jeecg 的菜单是根据后端权限动态生成的，路由表也是动态拼出来的，这一步更容易翻车。我遇到过一种情况，开发环境一切正常，打包部署后白屏，控制台没有任何报错。最后定位到是动态路由匹配的视图路径不对，构建后的 chunk 文件与路由表对应不上，页面组件根本没被加载。这个放到第 5 章细说。
4.2 history 模式刷新 404 与 nginx 配置
jeecg 新老版本默认都使用 history 路由模式。这种模式的特点是：地址栏里没有#，看起来更干净，但部署到服务器上，如果只配置了根路径对应的静态文件，刷新页面时 nginx 会去磁盘找那个不存在的路径，于是返回 404。
这是静态服务器通病，解决方案是让 nginx 把所有路径都回退到 index.html：
location / { root /opt/web/dist; index index.html; try_files $uri $uri/ /index.html; }如果你的前端部署在子目录，location 也要对应改：
location /jeecg/ { alias /opt/web/dist/; try_files $uri $uri/ /jeecg/index.html; }这里还有个坑：try_files回退到 index.html 后，如果静态资源也存在 404，会被混淆。所以排查时一定先看 Network 面板，区分是 JS/CSS 资源 404，还是刷新整个页面 404。
如果实在不想配 nginx，也可以把路由模式改成 hash，在 router 的配置里把createWebHistory换成createWebHashHistory。但 jeecg 有些页面跳转和菜单高亮逻辑对 hash 模式支持不一定完美，能配 nginx 尽量配 nginx，别靠改路由模式偷懒。
4.3 接口地址打到产物里，部署就全挂
这是我最想强调的一个坑。jeecg 前端构建的时候，环境变量文件会被打进产物。vue2 老项目看.env.production：
VUE_APP_API_BASE_URL=/jeecg-bootvue3 新版看.env.production或.env.prod：
VITE_GLOB_API_URL=/jeecg-boot如果里面的地址是http://localhost:8080/jeecg-boot，那你构建出来的 dist 里所有请求都会指向 localhost，部署到服务器上之后，前端页面能打开，但登录请求全部失败，因为用户浏览器访问 localhost 指向的是用户自己的电脑。
正确做法是使用相对路径，比如/jeecg-boot，然后让 nginx 把该路径反向代理到后端服务：
location /jeecg-boot/ { proxy_pass http://127.0.0.1:8080/jeecg-boot/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }注意proxy_pass末尾的斜杠：如果后面没有斜杠，路径会按原样转发；如果目标后端路径也有/jeecg-boot，这种写法是最稳的。有人喜欢把前端请求改成自己的网关路径，那就要保证网关和 jeecg 后端的路径能对应上，否则登录第一个请求就失败。
我每次发布前都会检查一遍构建产物里的 JS 文件，搜索一下是否残留localhost。这一步花不了两分钟，能避免 90% 的部署后登录失败问题。
5. 代码层面的隐形炸弹：eslint、动态路由与第三方组件
5.1 lintOnSave 把 build 拦在半路
老版 jeecg 的 vue-cli 项目默认开启lintOnSave，意思是 build 的时候会先跑 eslint 检查。如果项目里有同事没遵守规范，带着一堆 error 提交代码，构建时就会直接报错，报错信息第一行往往写着Module Error然后是一堆 ESLint 规则。
这种坑特别气人，因为它不是构建工具的问题，是代码风格的问题。处理方案是在vue.config.js里关闭构建时的 lint：
lintOnSave: false这样 build 就跳过 eslint 检查。但要注意，这只是绕过了构建拦截，代码质量问题依然存在，建议保留单独的npm run lint命令在提交前检查。对于交付项目，我一般会关掉，因为客户要的是能部署的产物，不是开发规范执行现场。
5.2 动态组件与 import.meta.glob 的构建时差异
新版 jeecg 的权限菜单会根据后端返回的组件路径，动态加载对应的.vue文件。常见写法是用 Vite 的import.meta.glob做静态收集。比如：
const views = import.meta.glob('/src/views/**/*.vue')这种写法在开发环境用vite运行时能按需加载，但构建时会做一个静态扫描。如果目录路径写错了，或者某些页面的.vue文件根本不在扫描范围内，开发环境可能因为缓存和运行时行为正常，build 之后打包产物里没有对应的 chunk，点击菜单后页面空白，或者路由跳转 404。
我遇到过最隐蔽的情况是：views 目录里有人新加了一个二级目录，文件夹名大小写和路由配置不完全一致，在 Windows 开发机上大小写不敏感，一切正常；在 Linux 服务器上大小写敏感，构建后的路径匹配不上，结果就是只有某个菜单打不开。
排查思路：构建产物里搜一下对应页面的名字，如果根本搜不到，就是 glob 扫描没覆盖到。调整 glob 路径，或者把路由组件路径写完整。
5.3 第三方库的压缩兼容问题
有些 npm 包在开发环境跑得好好的，build一压缩就报错。常见的有SyntaxError: Unexpected token，比如：
SyntaxError: Unexpected token: punc (.)这种通常是某个依赖没有被 babel 正确转译，导致低版本浏览器不支持的语法进了产物。vue2 老项目可以在vue.config.js里配置：
transpileDependencies: true如果不想全部转译，可以指定具体包名：
transpileDependencies: ['xxx-library-name']vue3 项目可以调整 vite 的optimizeDeps或 build 参数。但这里我更想说的是一个经验：jeecg 自带的低代码相关依赖，不要轻易升级或降级。有一次我为了让某个功能更流畅，升级了 echarts 的版本，结果 build 直接报错，项目里的在线报表组件和旧版 echarts 深度耦合，回滚版本之后才恢复正常。这种平台级项目，依赖版本能不动就不动。
还有一类问题是构建时第三方库访问了浏览器 API，例如直接使用window、document。在压缩构建阶段，某些库没有做环境判断，会报window is not defined。解决办法要么换库，要么在构建配置里做兼容处理，但这类改动风险高，需要评估影响范围。
6. 常见报错速查表与我的排查习惯
6.1 按报错现象快速定位问题
整理一个速查表，基本都是我实际遇到过的，按现象查对应方案即可。
| 报错现象 | 典型信息 | 发生阶段 | 让我最后成功的方案 |
|---|---|---|---|
| 内存溢出 | FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed | 构建中 | 设置NODE_OPTIONS=--max-old-space-size=4096，或用 cross-env 写进 build 脚本 |
| Node 新版跑 webpack4 | error:0308010C:digital envelope routines::unsupported | 构建启动 | 切 Node 16，或设NODE_OPTIONS=--openssl-legacy-provider |
| node-sass 安装失败 | Cannot find module 'node-sass'、node-gyp 报错 | npm install | 项目.npmrc配置sass_binary_site=https://npmmirror.com/mirrors/node-sass/ |
| 部署后白屏且 JS 404 | Network 里/js/app.js 404 | 部署访问 | 检查publicPath（vue2）或base（vue3），子目录部署要配对应路径 |
| 刷新页面 404 | 首页能打开，F5 后 404 | 部署访问 | nginx 配置try_files $uri $uri/ /index.html |
| 登录失败，请求打到 localhost | Network 里请求地址包含localhost:8080 | 登录访问 | 修改.env.production的 API 地址为/jeecg-boot，并用 nginx 反代 |
| eslint 报错阻断构建 | Module Error+ ESLint 规则信息 | 构建中 | vue.config.js设置lintOnSave: false |
| pnpm 装完找不到依赖 | Cannot find module 'ant-design-vue' | 构建启动 | 项目.npmrc加入shamefully-hoist=true，重装依赖 |
| 压缩阶段 JS 语法报错 | SyntaxError: Unexpected token | 构建中 | 在transpileDependencies中加入对应依赖包 |
这张表不能解决所有问题，但能解决大多数 jeecg 构建问题。
6.2 我那套简单的排错流程与兜底手段
如果速查表定位不到，我的排查顺序基本固定。
第一步，固定 Node 版本。团队项目里统一用.nvmrc或者约定版本，先确认不是版本问题。很多诡异报错在切换 Node 版本后直接消失。
第二步，固定包管理器。删掉node_modules和所有 lock 文件，用同一个包管理器重装一遍。这个操作能解决依赖残留、缓存损坏、半装依赖等大部分问题。
第三步，看完整日志，不要只看最后两行。webpack 和 vite 的报错会提示是哪个模块、哪个文件，定位到具体路径后再去查代码改动。比如日志里出现某个.scss文件编译失败，那大概率是样式语法问题，不是环境问题。
第四步，检查最近的代码改动。git diff看package.json、vue.config.js、vite.config.ts、.env.production这几个关键文件。我遇到过客户现场打包失败，最后发现是有人为了调试临时改过接口地址，提交时一起带上去了。
最后再说一个百试不爽的习惯：拿到一个新 clone 的 jeecg 前端项目，第一步只看三个文件 ——package.json、vue.config.ts或vite.config.ts、.env.production。把 Node 版本、依赖安装方式、接口地址、部署路径全部确认一遍，再跑npm install。很多坑其实在 build 之前就已经埋好了，只是等着你某天在服务器上执行构建的时候引爆。
jeecg 前端构建的坑，说到底是低代码平台依赖庞大、版本敏感、配置复杂这几件事叠加的结果。环境变量、内存上限、路径配置、依赖树一致性，这些东西都理顺之后，npm run build会变得很平淡。平淡，对于一个交付项目来说，就是最好的状态。
