本质是构建环境与本地不一致：Node版本、node_modules来源或缓存状态出错，导致npm install看似执行却未生效，进而引发Module not found等错误。
Jenkins 构建失败，报 Module not found 或 Cannot find module，本质不是“缺包”，而是构建环境与本地不一致——Node 版本、node_modules 来源、缓存状态三者之一出错。
为什么 npm install 在 Jenkins 上不生效
常见现象：Jenkins 流水线里写了 npm install，但构建时仍提示找不到 @dcloudio/uni-cli、cross-env 等关键依赖。根本原因不是命令没执行，而是：
-
package-lock.json由高版本 npm（如 v9+）生成，而 Jenkins 节点上是 npm v6 或更低，导致解析失败或跳过部分依赖 - 项目用了
yarn，但 Jenkins 执行的是npm install，lock 文件不兼容，node_modules结构错乱 - Jenkins 工作空间残留了旧的
node_modules，且权限为只读（尤其从 zip 解压来的），npm install实际没写入新包
cross-env: Permission denied 的真实原因
这不是权限配置问题，而是 cross-env 二进制文件没被正确安装或执行路径损坏。典型触发场景：
- 手动把本地
node_modules压缩后传到 Jenkins 服务器解压 —— Linux 下文件权限丢失，node_modules/.bin/cross-env没有可执行位 - 使用了不同架构的 Node（比如本地是 macOS ARM64，Jenkins 是 x86_64 Ubuntu），导致某些 native 模块（如
fsevents）无法加载，连带破坏cross-env启动链 -
npm install过程中被中断（如超时、磁盘满），.bin目录下符号链接残缺
解决方式不是加 chmod +x，而是统一用 npm rebuild 重建所有二进制链接：npm rebuild cross-env --no-bin-links && npm rebuild（后者确保全部依赖重装）。
Node 版本不匹配引发的隐性依赖错误
uni-app 官方明确要求 Node ≥ 14.18.0（2026 年起推荐 ≥ 18.17.0）。Jenkins 节点若仍是 Node 12 或 14.0.x，会出现：
-
ERR_REQUIRE_ESM：新版@vue/cli或unplugin-vue-components使用 ESM，默认不兼容 CommonJS require -
Invalid version：package.json中engines.node字段被忽略，但实际依赖的子模块（如esbuild）已停止支持低版本 -
npm ci失败：因 lock 文件中包含integrity字段格式变更，老 npm 无法校验
务必在 Jenkinsfile 或构建脚本开头显式检查：node -v && npm -v && npm ci --ignore-scripts；若失败，直接退出，不继续构建。
最稳妥的依赖同步方案
别传 node_modules，也别信“一次安装永久复用”。Jenkins 构建应遵循幂等原则：
- 每次构建前清空工作目录：
rm -rf node_modules package-lock.json（避免残留干扰） - 统一用
npm ci替代npm install：它严格按package-lock.json安装，不更新 lock，更快更确定 - 若项目用 yarn，必须在 Jenkins 节点预装对应版本的 yarn（如
yarn set version 1.22.19），并始终用yarn install --frozen-lockfile - 对
devDependencies中的 CLI 工具（如@dcloudio/uni-cli），确保它们出现在package.json的dependencies或devDependencies里，而非全局安装 —— Jenkins 节点不应依赖全局环境
真正容易被忽略的点：Jenkins Agent 的 shell 环境可能未加载 nvm 或 volta 配置，node 命令实际调用的是系统自带的老版本。检查方式不是看 which node，而是用 env | grep PATH 看实际生效的路径。
