企业官网建设流程全解析

简介：Karma离线安装包面向前端开发与测试工程师，解决内网隔离或网络不稳定场景下无法便捷安装JavaScript测试框架的问题。压缩包约12.2MB，内含Karma核心模块及qs、tinycolor、send、adm-zip、async、deep-equal、ncp等常用依赖库，覆盖请求参数解析、静态资源服务、异步任务并发控制、ZIP读写以及对象深度比较等测试运行所需的基础能力。开发者只需解压并参照官方文档放置文件，即可在本地搭建完整的Karma测试环境，配合Jasmine、Mocha等测试库使用，并支持监控源码变化自动重跑测试，进而与Grunt、Gulp等构建工具集成。包内还包含sigmund哈希比较、bytes容量处理等辅助模块，便于测试状态跟踪与报告展示。目前已有1700余人学习下载，适合需要在隔离环境或弱网条件下开展前端自动化测试的团队与个人选用。

1. karma离线安装包到底是什么：一条命令装不上时，问题才真正开始

在内网环境里装 karma，很多人的第一反应是：把 node_modules 整个拷过去不就行了？这个思路往往在第一分钟就翻车。karma 是一个插件式测试运行器，它本体只负责启动 HTTP 服务、调度和执行，真正干活的是 karma-mocha、karma-chrome-launcher 这一圈插件，以及它们背后几十个传递依赖。离线安装包要解决的不是“把 karma 拷到内网”，而是把这个插件生态连同 npm 的解析元数据，完整地、按平台正确地搬到目标机器上，缺了任何一环，karma start 只会给你一个不明不白的报错。这篇笔记面向需要在内网、CI 离线环境搭前端测试的开发者，也面向要给团队分发工具链的维护者，从依赖结构讲到制作流程，再讲到最常踩的五个坑。

2. 离线包要先拆开看：karma 的依赖树与三条可落地的安装路线

2.1 karma 的“本体 + 插件 + 传递依赖”三层结构：离线包到底要装哪些东西

karma 的设计和大多数前端测试工具不一样，它不是一个把所有功能揉在一起的单体应用，而是一个薄薄的调度核心。karma 本体负责起一个基于 socket.io 的本地服务，把测试文件注入到浏览器页面里，收集浏览器回传的结果，再交给 reporter 输出。至于用哪套断言库、跑在哪个浏览器里，全是插件决定的。这就导致离线包的边界不是“karma 一个包”，而是“karma 加上你选的一套插件组合”。

这套组合最典型的三件套是：karma-mocha 提供 mocha 框架适配，mocha 本身是断言和测试框架，karma-chrome-launcher 负责拉起浏览器。这三者和 karma 本体之间没有强依赖关系，karma 不知道你装没装 mocha，也不关心你用的是 Chrome 还是 Firefox，它只认配置里写的 frameworks 和 browsers 名字。所以在做离线包时，必须先把项目里实际会用到哪些插件定下来，再按这个清单收集依赖，少一个就少一个能力。

还有一个容易被忽略的点：npm 7 之后会自动安装 peerDependencies，也就是 karma 插件在 package.json 里声明为 peer 的包，比如 karma-mocha 会要求配套的 mocha 版本。这个行为在联网环境下没什么感觉，缓存里自然会有，但离线打包时如果只盯着 karma 的 dependencies，peer 依赖就会被漏掉。等到内网跑起来，报一个 cannot find module 或版本不匹配，再回头补包就很浪费时间。karma-cli 也是同样的道理，它不是 karma 的依赖，而是独立发布的命令行工具，离线环境里如果没有它，npx karma start 会直接提示下载失败。

# 在干净的联网目录里，安装最小可行的 karma 测试组合 npm init -y npm install --save-dev karma karma-mocha mocha karma-chrome-launcher

这条命令里的四个包就是离线闭包的核心集合。karma 是调度器，karma-mocha 是 mocha 的适配器，mocha 是测试框架本体，karma-chrome-launcher 是浏览器启动器。注意 karma-cli 我没有放进这条命令，因为它应该装成全局工具，也可以在项目里通过 node_modules/.bin/karma 调用，后文避坑章节会专门讲它。

2.2 三条离线安装路线的对比：缓存复制、tgz 集合、私有镜像仓库

离线安装听起来只是“把包下载好带进去”，但落地方式至少有三条完全不同的路线，选错一条会在后续维护时付出成倍的代价。我一般先问三个问题：目标机器有几台、网络隔离多久、有没有一台长期运行的内网服务器。三个问题的答案基本就能决定路线。

第一条路线是直接复制 npm 的全局缓存目录。npm 安装时会把下载过的 tar 包和元数据缓存在本机，命今npm install --offline可以强制只从缓存读。这个方案的优势是操作最简单，只需要在联网机器上先完整 install 一遍，然后把整个缓存目录打成一个 tar 包，内网还原后继续 install 即可。缺点是缓存目录体积大，动辄几百 MB，而且缓存里会混入历史安装过的其他包，不够干净。

第二条路线是用 npm pack 把依赖逐个打成 tgz 文件。每个 tgz 是一个完整的、可离线安装的包，体积小、版本清晰，适合放到 U 盘或内网共享目录里分发。但 npm pack 只打当前指定的包，不会递归地把依赖一起打出来，想得到完整闭包，必须自己去遍历 package-lock.json，把每一个依赖都 pack 一遍。这条路线的问题在于 peer 依赖和 optional 依赖的处理，遍历脚本漏一个，内网就是一次翻车。

第三条路线是在内网部署一个私有 registry，常见做法是使用 verdaccio。把离线 tgz 批量发布到这个私有源上，内网开发者的 npm 完全指向它，此后安装、升级都走内网，不再需要外网。这个方案适合团队长期使用，也方便后续补包，代价是需要一台服务器，以及维护一份已发布包的清单。三条路线的具体命令和参数我在下一章逐步展开。

2.3 选型决策：什么样的环境该走哪条路

如果只是给内网一台开发机装 karma，复制 npm 缓存是最快的。我会在联网机器上用一个空目录把依赖装好，顺手生成 package-lock.json，再打包缓存。内网机器的 node 版本最好和联网机器保持一致，因为不同版本 npm 的缓存校验逻辑有差异，尤其是锁文件版本不同的时候，--offline 安装可能因为找不到对应缓存而报错。

如果是给多台机器分发，或者条件不允许马上搭服务器，tgz 集合更可控。但要将它和“复制 node_modules”严格区分开，tgz 是规范安装介质，node_modules 目录拷贝过去会因为路径、平台二进制等问题产生各种玄学错误。把 tgz 集合放到内网共享目录，配合一份 README 说明安装顺序，比到处传 U 盘更不容易出错。

如果是某公司或某实验室的长期内网开发环境，我强烈建议直接走 verdaccio。理由很朴素：离线包不是装一次就结束的，karma 插件会升级、测试框架会调整，私有 registry 允许你每次只把新增的几个 tgz 发布上去，内网其他人 npm install 就自动增量同步。缓存复制和 tgz 集合在“一次性交付”场景里够用，但每次变更都要重新制作整个离线包，维护成本会随着时间线性上升。

3. 从联网机器到内网：制作离线安装包的三步流程与完整命令

3.1 路线一：用 npm cache 做离线介质，最小命令与参数说明

先把联网机器准备好。这里有个关键习惯：不要拿一个已经有大量历史安装记录的目录来打包，缓存里多出来的包会全部混进离线介质，内网安装时 npm 虽然不会主动多装，但缓存校验会变慢，而且你无法确认最后交付的到底是什么版本。我会新建一个空目录，只装目标项目需要的包，让缓存保持干净。

# 第一步：在联网机器创建一个干净项目，并锁定版本 mkdir karma-offline && cd karma-offline npm init -y npm install --save-dev karma karma-mocha mocha karma-chrome-launcher # 第二步：找到 npm 缓存目录位置 npm config get cache # 第三步：把整个缓存目录打包成 tar 包 tar -czf karma-offline-cache.tgz -C "$(npm config get cache)" .

第一段命令里没有指定版本号，如果想固定 karam 的大版本，可以写成 karma@6 或 karma@5。建议在实际项目里先把 package.json 里的版本确定好，再执行安装，这样生成的 package-lock.json 就是离线安装时的唯一依据。npm config get cache会输出缓存目录的绝对路径，Linux 上通常是 ~/.npm，Windows 上是 %LOCALAPPDATA%\npm-cache。打包时用-C先切换进缓存目录再打包点文件，这样解压时直接解进目标目录即可，不会多套一层目录名。

内网机器上的还原操作更简单，但有一个参数不能省：--offline。不加这个参数，npm 仍然会尝试访问 lock 文件里记录的 registry 地址，内网没有外网权限时就会超时。npm ci和npm install的区别也要说清楚：npm ci 会严格按照 lock 文件安装，并且先删除现有 node_modules，是离线还原最可预期的操作；npm install 则可能因为 lock 文件与 package.json 不一致而重新解析依赖，反倒会去请求网络。

# 把离线缓存包放到内网机器后，解压到 npm 的缓存目录 tar -xzf karma-offline-cache.tgz -C "$(npm config get cache)" # 进入项目目录，完全离线安装 cd /path/to/karma-offline npm ci --offline --no-audit --no-fund

--no-audit和--no-fund这两个参数在离线环境下不只是提速，更是保命。npm 默认在安装完成后会去请求审计接口和基金赞助信息，这些请求指向外网，离线时会造成额外等待，甚至在某些代理环境下直接报错。离线介质场景里，这两个参数应该写进团队的统一安装命令里，避免每个人踩一遍。

3.2 路线二：npm pack 收集 tgz，用文件集合作分发介质

npm pack 的语义是“把某个包打成可发布的 tgz”，它只包含这个包自身的文件，不带依赖。所以如果你直接npm pack karma，拿到的 tar 包放进内网去 npm install，npm 只会看到依赖缺失。要拿到完整闭包，必须遍历 package-lock.json 里的全部包条目，逐个 pack。

我一般用一个 bash 脚本处理这件事，参数全部由 lock 文件驱动，不依赖任何手工清单。注意脚本里用了 jq，在联网机器上需要事先装好；如果没有 jq，也可以改用 node 脚本解析 JSON，逻辑一样。

#!/usr/bin/env bash set -euo pipefail # 离线包输出目录 mkdir -p offline-tgz cd offline-tgz # 从 lock 文件中取出所有 node_modules 下的包名 # .packages 的 key 形如 node_modules/foo 或 node_modules/@scope/bar jq -r '.packages | keys[] | select(startswith("node_modules/"))' ../package-lock.json | sed 's|^node_modules/||' | xargs npm pack --pack-destination ./ echo "tgz 文件已生成：$(ls ./ | wc -l) 个"

jq 提取的是 lock 文件里所有包路径，select(startswith("node_modules/"))把根项目和嵌套路径都包含进去。sed 去掉node_modules/前缀后，剩下的就是 npm 能识别的包名，形如karma、@babel/code-frame。xargs npm pack会逐批把它们打成 tgz，输出到当前目录。这里有一个常见的坑：npm pack 一次接收多个包名时，如果其中某个包名在 registry 上不存在（比如来自私有源的包），整条命令会失败。所以脚本里的set -euo pipefail能第一时间暴露问题，不会让打包工作在缺失状态下静默完成。

拿到 tgz 集合后，内网有两种用法。第一种是把 tgz 直接作为安装源，但这只适用于依赖数很少的场景，几十个 tgz 手动一个一个npm install ./xxx.tgz不现实。第二种是我更推荐的：把这些 tgz 作为种子包发布到内网 verdaccio，内网统一走 registry 安装，这个流程在下一节展开。tgz 集合真正的价值是“可审计”：每个 tgz 就是某个包在某个版本的快照，文件名里带着版本号，分发时谁缺了哪个包一眼就能看出来。

3.3 路线三：verdaccio 离线镜像，团队内网安装与更新一次到位

verdaccio 是搭建私有 npm registry 最常见的选择，它本身就是一个 npm 包，在联网机器上装好后，把存储目录整个搬到内网即可。先在一台内网服务器上初始化配置，我的做法是写一份尽可能简洁的 config.yaml，离线环境不需要 uplinks，也就是不配置任何外网上游源，所有包只从本地存储读取。

# verdaccio 离线环境最小配置 storage: /opt/verdaccio/storage auth: htpasswd: file: /opt/verdaccio/htpasswd uplinks: {} packages: '@*/*': access: $all publish: $authenticated '**': access: $all publish: $authenticated

这里的关键是uplinks: {}，它表示 verdaccio 不向上游 registry 拉取任何缺失的包。联网环境下的 verdaccio 通常配置一个指向官方仓库的 uplink，缓存缺失时自动透传，但离线场景里透传请求会每包超时一次，反而拖垮速度。storage 路径指向一块持久化目录，htpasswd 用来控制发布权限，普通开发者只要能读就好。

内网服务器启动后，把上一节生成的离线 tgz 批量发布上去。发布不需要在服务器本机做，任何一台能访问内网 registry 的机器都可以，我习惯直接用命令行发布，不用 verdaccio 的 Web 界面翻来翻去。

# 设置 registry 指向内网服务 npm config set registry http://内网地址:4873 # 登录（用户名和密码按自己团队约定） npm adduser --registry http://内网地址:4873 # 批量发布所有 tgz 到内网 registry cd offline-tgz for f in *.tgz; do npm publish "$f" --registry http://内网地址:4873 done

npm publish读取 tgz 内部的 package.json 来确定包名和版本，所以这些由 npm pack 生成的 tgz 可以直接发布，不需要额外整理。批量发布成功后，内网开发者的安装体验就和联网环境彻底一致：npm registry 指向内网，npm install 直接命中 verdaccio 存储，无外网请求，无超时，也无须关心缓存介质存放在哪台机器上。后续想升级某几个包，只需要在联网机器上把新版本的 tgz 打出来，再单独 publish 一次，其他开发者 npm install 就能拉到。

4. karma离线安装避坑：5 个让人翻车的常见问题与排查记录

4.1 现象：内网 npm install 报 ENOTFOUND 或 ETARGET，可我明明把包都带来了

这个问题几乎每个第一次做离线包的人都会撞上。拷了 node_modules 目录，也把 node_modules 放进内网项目里，结果 npm install 直接报找不到某个版本的包。原因在于 npm 的安装逻辑里，node_modules 目录不是一个合法的安装介质，真正决定装什么、从哪里装的是 package-lock.json 里的 resolved 字段，它默认指向官方 registry 的完整 URL。内网机器一读 lock 文件，发现要访问外网地址，网络不通就报 ENOTFOUND；如果 registry 里恰好没有 lock 记录的旧版本，就报 ETARGET。

解决方法是分两层来看。第一层，安装时必须加--offline参数，强制 npm 跳过网络解析，直接从缓存读取；第二层，离线介质必须包含 npm 缓存，而不仅仅是 node_modules 目录。也就是说，拷 node_modules 这条思路本身就要放弃，它只在极小项目和完全一致的环境里碰巧能跑，稍微碰到 peer 依赖变化就崩。正确姿势回到第 3 章的缓存复制流程：lock 文件 + 完整 npm cache +npm ci --offline。

4.2 现象：缓存还原后安装报 EINTEGRITY，sha512 校验不通过

EINTEGRITY 是离线场景里很打击人的一个错误，明明缓存是从联网机器拷过来的，内网一装就报包的校验和不匹配。绝大多数情况是缓存介质在传输过程中被改动过，或者打包时文件没有写完整。这类问题常见于用 U 盘拷贝时中途拔出、用压缩工具二次解压导致文件时间戳变化后校验不过，以及打包时把 npm cache 目录里的锁文件（_cacache 下的索引）和内容文件分开拷，拷到一半中断。

解决方式不复杂：第一，重新在联网机器上生成一份全新的缓存 tar 包，确保生成过程的完整性；第二，不要手工改动缓存目录里的任何文件，npm cache 是 content-addressable 的，文件名是内容的哈希，你改了文件名就等同于破坏了索引；第三，拷到内网后先执行一次npm cache verify，它会扫描并报告缓存完整性，发现问题立刻重新解压，而不是带着坏缓存继续安装。npm cache verify是离线安装前最好的体检命令，几秒钟扫完一整个缓存目录。

4.3 现象：Linux 上安装时报 Cannot find module 'fsevents' 或卡在 node-gyp 重新编译

karma 的依赖链里有一个叫 fsevents 的包，它是 macOS 专属的文件事件监听模块，用于 watch 模式下监听文件变化。问题就出在它是个 optional dependency，在 macOS 上安装时会下载 darwin 平台的预编译二进制，在 Linux 上则直接跳过。如果你在 macOS 上制作离线包并复制缓存到 Linux，npm 会发现缓存里有 fsevents 但平台不匹配，转而尝试重新编译，或者直接跳过导致运行时找不到模块。

这个坑的本质是离线介质有平台属性，尤其 optional dependencies 和原生模块（node-gyp 编译产出的 .node 文件）在跨平台复制时会水土不服。解决办法一条：在目标平台上制作离线包。给 Linux 内网分发，就在一台 Linux 联网机器上执行完整安装和缓存打包；给 macOS 分发，就在 macOS 上做。不要妄想一份离线包通吃所有系统。如果团队里没有 Linux 联网机器，那就放弃预编译二进制，改成在项目里固定 node 版本，并在内网机器上准备好完整的编译工具链（python、make、g++），否则 npm rebuild 时会卡到怀疑人生。

4.4 现象：离线机器上执行 npx karma start，提示下载 karma-cli 失败

npx 的逻辑是：如果当前项目的 node_modules/.bin 里没有对应命令，它会尝试从 registry 临时下载这个包来执行。离线机器上没有网络，下载必然失败。很多人把 karma 本体装好之后就忘了 karma-cli，但 karma start 这个命令恰恰不是 karma 提供的，它来自 karma-cli。karma-cli 的作用是解析命令行参数，再调用项目本地的 karma 模块，它是一个薄薄的壳，却是离线环境最容易漏的一层。

解决办法是把 karma-cli 显式纳入离线范围。如果走缓存复制路线，需要在联网机器上执行npm install -g karma-cli，把全局安装也跑一遍，这样它的缓存条目才会出现在 cache 里。如果走 verdaccio 路线，就确保 karma-cli 的 tgz 已经发布到内网 registry。安装到内网机器时，优先用npx --no-install karma start来检查命令是否本地可用，或者直接调用./node_modules/.bin/karma start，绕开 npx 的下载逻辑。这个习惯能让你一眼分辨出命令缺失还是 karma 本体出了问题。

4.5 现象：karma start 启动成功但没有浏览器被捕获，测试一直 pending

这是 karma 装好之后最常见的运行期问题。karma 会启动一个本地服务，然后通过 launcher 拉起浏览器，如果浏览器没起来，页面上就不会有人执行测试脚本，singleRun 模式会一直挂到超时。在离线内网服务器上，这个坑通常叠加两个原因：一是离线包里漏了 karma-chrome-launcher，配置里写了 Chrome 却找不到启动器；二是 Linux 服务器上根本没有图形环境，Chrome 默认沙箱模式起不来。

第二点的解决方式几乎成了 CI 环境标配：使用 Headless Chrome，并关闭沙箱。注意 Chrome 的沙箱依赖内核能力，在容器或部分内网服务器上，没有 user namespace 支持时 Chrome 会直接退出，日志里看不到任何有用信息，只留下一句 “Failed to move to new namespace”。在 karma 配置里加一个自定义 launcher 是最稳妥的做法。

// karma.conf.js 中增加一个无沙箱的 Headless Chrome 启动器 customLaunchers: { ChromeHeadlessNoSandbox: { base: 'ChromeHeadless', flags: ['--no-sandbox', '--disable-gpu'] } }

配置里把 browsers 改成['ChromeHeadlessNoSandbox']，大部分服务器环境就能跑起来。需要说明的是，--no-sandbox会降低浏览器隔离性，适合在内网测试服务器上使用，但不要把这个配置无脑带到面向不可信页面的场景里。最后还要检查一件事：karma 到底有没有捕获到浏览器，启动 log 里会打印Chrome Headless was captured，看不到这行字就说明 launcher 或浏览器本身还没就绪。

5. 验证离线包可用：最小配置、全量跑测与二次分发的习惯

离线包做完、内网装完，只成功了一半，另一半是验证这套介质确实能在干净环境里跑通测试。我一般会在内网机器上新建一个测试项目，只用最小配置跑一次 karma，确认整条链路是通的，再回头发给其他人。

// 最小可运行 karma.conf.js module.exports = function(config) { config.set({ basePath: '', frameworks: ['mocha'], files: ['test/**/*.spec.js'], browsers: ['ChromeHeadlessNoSandbox'], customLaunchers: { ChromeHeadlessNoSandbox: { base: 'ChromeHeadless', flags: ['--no-sandbox'] } }, singleRun: true, reporters: ['progress'] }); };

验证的标准是终端里出现Executed 3 of 3 SUCCESS，一行都不能少。如果只出现Executed 0 of 0，说明 files 的 glob 没匹配到测试文件，先检查路径；如果出现SUCCESS但数量不对，说明缓存里某个包版本和 lock 文件不一致，重新制作离线包。跑通之后建议把这条命令固化到团队的安装文档里：npm ci --offline --no-audit --no-fund && npx karma start --single-run，每个拿到离线包的人先执行这一行，能过说明介质没问题，不能过就从介质入手排查。

二次分发时，一个小小的习惯能省下大量沟通成本。把 karma-offline-cache.tgz、seed 项目的 package.json、package-lock.json、karma.conf.js 放在同一个目录下打包，文件名里带上日期。这个组合每一部分都有用：lock 文件保证安装版本一致，cache 提供离线介质，conf 提供可验证的最小配置。我不建议直接把 node_modules 一起打进去，它没有任何安装语义，只会让包体积凭空大几倍。

如果团队用 Docker 做 CI，离线缓存还有更优雅的用法：把离线包直接打进基础镜像，之后每次构建都不再碰网络。这个做法特别适合内网部署流水线。

FROM node:20 RUN mkdir -p /root/.npm COPY karma-offline-cache.tgz /tmp/ RUN tar -xzf /tmp/karma-offline-cache.tgz -C /root/.npm WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --offline --no-audit --no-fund

这个镜像构建完成后，所有依赖已经装进镜像层，CI 里后续步骤直接跑测试即可。注意 node:20 镜像里 npm 缓存路径是 /root/.npm，如果你用的是别的镜像或切了用户，记得先用npm config get cache确认路径，不要硬编码。有一次我帮同事查一个内网 CI 的问题，折腾半天发现就是缓存解压到了错误的目录，npm 在构建阶段重新触发了网络请求，整个流水线卡在超时上。那之后我把“先 verify 路径再解压”写进了镜像制作的检查清单。做离线包这件事，九成的坑都出在“你以为装好了，其实 npm 偷偷在走网络”这几个字上。希望这篇笔记能帮你少踩几个，一次就把 karma 离线环境搭顺。

本文还有配套的精品资源，点击获取