Jenkins前端打包构建老项目拯救指南

最近由于要将一些老的项目部署流程规范化，很多老的前端项目打包都会有奇奇怪怪得问题出现，这边将一些坑记录下，顺便也写下处理思路。

前言：一般来说前端镜像构建最主要得就是出包，只要能出包问题基本解决了百分之八十，剩下得都是比较机械固定得步骤。所以一般来说我都是先本地起一个虚拟机，出包以后将调整好的编译语句放在jenkins上，所以本篇文章主要也是针对前端编译出包这块。

一般编译流程如下：

1.首先一般来说我们都是先看git项目得readme文档，在这里你需要得到四个东西，分别是涉及到得node版本，编译命令，打包命令，以及是否是hbuilder构建得项目（如果是hbuilder构建得，这个打包比较麻烦，需要在编译环境新建开发环境，具体可以参看别的教程，情况比较少，这边不展开）

2.常规项目一般安装依赖包都是npm install 但是一般来说这个安装速度非常慢，即使配置了国内得镜像仓库也并不会快很多，所以我一般都是直接试用yarn install && yarn builld 如果可以大功告成！！！如果不行，那么你可以蛮试下npm install && npm run build 如果可以，大功告成！

好，常规思路基本说的差不多，如果以上还不能解决，你需要理解以下知识，这边大概列一下。

1.npm ci是个好东西，这边援引下别的地方得解释：

此命令与 npm install 类似，不同之处在于它旨在用于自动化环境，例如测试平台、持续集成和部署——或任何您希望确保对依赖项进行全新安装的情况。 使用 npm install 和 npm ci 的主要区别是： 项目必须有一个现有的 package-lock.json 或 npm-shrinkwrap.json。 如果包锁中的依赖项与 package.json 中的依赖项不匹配，npm ci 将退出并出错，而不是更新包锁。 npm ci 一次只能安装整个项目：无法使用此命令添加单个依赖项。 如果 node_modules 已经存在，它将在 npm ci 开始安装之前自动删除。 它永远不会写入 package.json 或任何包锁：安装基本上是冻结的。

从以上信息，我们可以知道，npm ci 不会修改lock文件与package.json文件，同时严格按锁文件安装整棵项目树

2.npm install --package-lock-only 这个也是个好东西

--package-lock-only 是 npm 的一个布尔参数，用于只生成或更新 package-lock.json 文件，而不修改 node_modules。这在需要锁定依赖版本但不想重新安装依赖时非常有用。 例如，如果你有现成的 node_modules，但缺少 package-lock.json，可以直接生成： npm install --package-lock-only --offline --package-lock-only：仅生成/更新 package-lock.json，忽略 node_modules。 --offline：离线模式，依赖从本地缓存或现有 node_modules 获取。 这样可确保生成的锁文件与当前依赖版本完全一致，非常适合老项目或生产环境还原。 常见场景 从现有 node_modules 生成锁文件 当项目缺失 package-lock.json 时，可基于生产环境的 node_modules 生成： npm install --package-lock-only --offline 仅更新锁文件而不安装依赖 在修改了 package.json 后，只想同步更新锁文件： npm update --package-lock-only

好，综上，--package-lock-only 是根据package.json确定要安装的包的版本，然后创建一个package-lock.json 所以这个命令其实不在乎是否已经有 node_modules

3.很多时候会有需要在package.json 中 用到"overrides" 这个字段

这个字段主要在 npm 8 最新版上被支持，npm 7 及以下的版本中并没有这个能力，不过到还是有办法在旧版 npm 上用上这个能力，如果一定要使用 好像也行，具体参看百度，这边不展开，如果需要用，我的建议是升级npm版本。

4.关于npm 速度慢排查

可以在npm install 后面加上 --verbose 这个主要是打印详细执行步骤的信息，在这里的输出可以很清晰的看出问题卡在哪里。

5.关于npm install 跟npm ci 得区别

这边援引一篇文章写得不错，链接如下

npm install 与 npm ci 的区别与应用场景深解-腾讯云开发者社区-腾讯云

大概总结下，

npm install ：

当项目存在锁文件时，npm install会被锁文件驱动（并遵循npm-shrinkwrap.json、package-lock.json、yarn.lock的优先级）。 (npm Docs)

任何会更新node_modules或package.json依赖的命令（包含npm install）都会自动同步已有的 lockfile。 (npm Docs)

它描述 exact tree，并服务于 subsequent installs 生成 identical trees。 (npm Docs)

另外，当npm检测到老版本 lockfile 时，也可能在安装过程中自动升级 lockfile 内容以补齐缺失信息。 (npm Docs)

简单来说npm install出的lock文件并不是一成不变的，在相当的情况下还会改变lock的内容。

npm ci :

npm ci 不会修改lock文件与package.json文件，同时严格按锁文件安装整棵项目树

6.存在lock文件的情况下，可能node版本跟npm版本不是很重要，或者你可以用20的node打包14的老项目，这是可能的。

7.不同的环境可能下载的依赖不一样

比如chromedriver 这个依赖，会有linux版本或者windows版本，直接从不同环境拉过来的可能不能直接用。

8. .npmrc 这个文件会影响你下载依赖的仓库，如果跟你预想的不一样多半是开发提交了这个文件

9. npm版本最好跟lockversion匹配不然估计会碰到奇奇怪怪的bug

好，铺垫的差不多了，现在说说实际可能的问题：

问题： 一天一个呆瓜开发，提交了老项目的代码，同时可能会有不该交的文件交了，然后该交的文件没交，同时给你指定的npm版本为6.x ，对于这个老东西，你上了常规手段，一打一个报错。

好，解决方案如下：

排查下git仓库是否存在lock文件，一般这种老项目的切入点都是lock文件，如果没有让开发生成一个推送git仓库，常规来说到这步也就成了，如果这部不行，好多半是开发整错环境了，这个时候你可以让你们对比下npm list的版本差异，通常是因为两个环境的实际依赖版本不一样导致的，好，如果呆瓜开发不对比，或者沟通不畅，你可以考虑--package-lock-only手动生成下lock文件，然后npm ci ，但是这种情况一定要改package.json 这个是绕不过去的。如果开发还是不配合，那就让他改代码把，哪里报错改哪里！

补一条：

最近有打包镜像typescript类型的项目，然后跑着跑着突然就发现打镜像寄了，然后依赖下载都正常，下载完以后报错，

EPERM EPERM: operation not permitted, write

然后感觉有点莫名其妙，构建期间使用的是默认root权限，几经周折，询问ai总结如下

即使你已尝试了多种方法，问题依旧，原因在于这个权限错误是多个因素叠加的结果。 Alpine Linux 的严格权限检查：你使用的 node:24-alpine 基础镜像，其核心是 musl libc 库。与常用的 glibc 相比，musl 对文件系统权限的检查更为严格。在解压和设置文件时间戳（futime）等操作时，这种严格性可能触发权限错误。 Docker 文件系统的限制：Docker 的镜像层是只读的。在构建过程中，尽管最上层（container layer）是可写的，但 pnpm 的一些底层操作可能因无法穿透到只读层而失败。 pnpm 自身的 bug：在 pnpm 的某些版本（如 v10.5.0）中，存在一个已知缺陷：在执行配置操作时，它会错误地尝试在根目录（/） 下创建临时文件（如 /.npmrc.X），而普通用户（甚至 root 在某些环境下）没有根目录的写入权限，从而导致 EPERM 错误。 问题的根源在于 Alpine Linux (musl libc)、Docker 文件系统机制以及 pnpm 特定版本缺陷这三者组合产生的不兼容性。

然后遂换了base镜像，由alpine镜像换到slim镜像解决。。。。

这边随便总结下两个镜像的区别