1. 为什么要在内网环境自建 npm 私服做过前端基础设施的同学大概都有过这种经历团队规模一上来依赖管理就成了一个绕不开的坎。尤其是那些研发环境与公网物理隔离的团队每次新同学入职配环境、每次 CI 流水线跑构建都要面对同一个灵魂拷问——这些 npm 包到底从哪来。公网 npm registry 在隔离环境里根本访问不了靠 U 盘拷贝node_modules又极其脆弱不同操作系统、不同 Node 版本之间的原生模块比如node-sass、sharp、esbuild这类带二进制绑定的包经常直接罢工。更别提版本一致性了A 同学本地能跑B 同学拉下来就报错排查半天发现是某个间接依赖被解析到了不同的小版本。所以在内网搭一套自己的 npm 私服本质上解决的是三个问题依赖来源可控、版本解析可复现、离线环境可安装。而 Nexus3 配合 Yarn 这套组合是我实测下来在隔离环境里最稳的方案之一。Nexus3 是 Sonatype 出品的仓库管理器它原生支持 npm、Maven、Docker、PyPI 等多种格式的仓库托管一个服务就能把前端、后端、镜像的私服全包了。它的 npm 支持分三种仓库类型hosted私有发布、proxy代理公网、group聚合前两者。在离线场景里我们主要用hosted来存自己上传的包用group来给客户端提供一个统一入口。Yarn 这边它的离线能力比 npm 原生要成熟得多。Yarn 有offline mirror机制可以把所有依赖的 tarball 缓存到本地目录配合.yarnrc配置就能实现完全离线的安装。这套机制和 Nexus3 的 hosted 仓库结合起来就是一套完整的离线依赖供应链。这篇文章适合谁看如果你是团队里负责前端基建的工程师或者正在为隔离环境搭建依赖仓库又或者你只是单纯想搞清楚 npm 私服到底怎么落地那接下来的内容应该能帮你少走不少弯路。我会从整体设计思路讲起然后拆解 Nexus3 的部署配置、Yarn 的离线镜像制作、客户端接入最后把踩过的坑整理成排查表。2. 整体方案设计与核心思路拆解2.1 三种仓库类型的职责划分在动手之前先把 Nexus3 里 npm 相关的三种仓库类型理清楚这决定了你后面怎么组织目录结构。npm (hosted)是私有仓库用来存放团队自己开发的包或者你手动上传的第三方包。它支持npm publish直接推送也支持通过界面或 API 上传 tarball。在离线场景里我们主要靠它来承载所有需要分发的依赖。npm (proxy)是代理仓库正常情况下它会去远程 registry 拉包并缓存。但在完全隔离的环境里这个类型其实用不上因为你根本连不出去。不过如果你的环境是「半隔离」——比如有一台跳板机能访问公网——那可以先用 proxy 把包缓存下来再导出迁移。npm (group)是聚合仓库它可以把多个 hosted 和 proxy 仓库聚合成一个地址对外提供服务。客户端只需要配置 group 的地址就能同时访问私有包和代理包不用来回切换 registry。在纯离线环境里我的建议是建一个 hosted 仓库存所有包再建一个 group 仓库指向它客户端统一用 group 地址。这样以后如果环境有了变化需要加 proxy 仓库只需要把 proxy 加进 group 的成员列表客户端配置完全不用动。2.2 为什么选 Yarn 而不是 npm 原生很多人会问npm 自己也有npm pack和--offline参数为什么还要用 Yarn 的离线镜像核心差异在于依赖树的确定性。npm 在安装时会根据package.json里的 semver 范围去解析实际版本不同时间点解析出来的结果可能不同。而 Yarn 的yarn.lock会锁定每一个包的精确版本和完整性哈希配合offline mirror目录安装时直接按 lock 文件里的路径去取 tarball完全不依赖网络解析。另一个原因是 Yarn 的离线镜像目录结构非常清晰。执行yarn config set yarn-offline-mirror ./npm-packages-offline-cache之后所有下载的 tarball 会以包名-版本.tgz的格式平铺在目录里文件名里的特殊字符会被转义。这个目录可以直接打包迁移也可以批量上传到 Nexus3。还有一点是 Yarn 的--offline标志配合--frozen-lockfile使用能强制要求 lock 文件存在且不更新这在 CI 环境里特别有用——任何依赖变动都必须显式提交 lock 文件避免了「本地能跑、CI 挂掉」的经典问题。2.3 离线部署的完整数据流把整个方案的数据流串一下方便你理解每一步在干什么。第一步在一台能访问公网的机器上用 Yarn 安装项目依赖同时开启yarn-offline-mirror把所有 tarball 缓存到本地目录。这一步产出的是一堆.tgz文件和一个yarn.lock。第二步把这批 tarball 批量上传到 Nexus3 的 hosted 仓库。上传方式可以是界面手动传也可以用脚本调 Nexus3 的 REST API 批量推。第三步在隔离环境的客户端上配置.yarnrc和.npmrc把 registry 指向 Nexus3 的 group 地址同时把yarn-offline-mirror指向一个本地缓存目录可选。第四步执行yarn install --offline --frozen-lockfileYarn 会优先从本地缓存找 tarball找不到再去 registry 拉。在完全隔离环境里所有包都已经在 Nexus3 里了所以这一步能顺利完成。这个流程的关键在于tarball 的完整性哈希必须和 lock 文件里记录的一致。如果上传过程中文件损坏或者 Nexus3 返回的内容被篡改Yarn 会直接报 integrity check 失败。所以上传后最好做一次校验。3. Nexus3 部署与 npm 仓库配置实操3.1 Nexus3 的安装与初始化Nexus3 的安装方式有好几种官方提供了 Docker 镜像、tar.gz 包和 RPM 包。在隔离环境里我一般推荐用 tar.gz 包因为不依赖 Docker 运行时迁移也方便。下载对应版本的nexus-3.x.x-xx-unix.tar.gz解压到/opt/nexus目录。目录结构里有两个关键文件夹nexus-3.x.x-xx是程序目录sonatype-work是数据目录。数据目录里存着所有仓库的 blob、配置和索引迁移时只需要打包这个目录。启动前先改一下nexus-3.x.x-xx/bin/nexus.vmoptions把 JVM 堆内存调大一点。默认配置是-Xms2703m -Xmx2703m如果服务器内存充足建议调到 4G 以上因为 npm 仓库的元数据索引比较吃内存。同时把-XX:MaxDirectMemorySize也相应调大避免大文件上传时出现直接内存溢出。启动命令是./bin/nexus run前台运行方便看日志。确认没问题后可以用./bin/nexus start后台启动。默认端口是 8081初始管理员密码在sonatype-work/nexus3/admin.password文件里。注意第一次登录后会强制要求修改密码改完之后那个admin.password文件会被删除。如果你在自动化脚本里需要用到初始密码记得在第一次登录前把它读出来存好。3.2 创建 npm hosted 仓库的关键参数登录 Nexus3 管理界面进入Repository-Repositories-Create repository选择npm (hosted)。几个关键参数需要留意Name是仓库的唯一标识建议用npm-hosted这种语义清晰的名字。Online保持勾选表示仓库可用。Storage里的Blob store用默认的就行如果包量特别大可以单独建一个 blob store 挂到不同的磁盘上。Hosted区域里有两个选项Deployment policy和Allow redeploy。Deployment policy有三个值Allow redeploy、Disable redeploy、Read-only。在离线场景里因为我们要反复上传同一个包的同一个版本比如修复了 tarball 损坏的问题建议选Allow redeploy否则重复上传会报 400 错误。Allow redeploy这个选项在 npm 仓库里其实对应的是是否允许覆盖已存在的版本。npm 官方 registry 是不允许覆盖已发布版本的但私服里我们没这个限制灵活一点更好。创建完成后仓库地址是http://nexus-host:8081/repository/npm-hosted/。这个地址后面会用到。3.3 创建 npm group 仓库并聚合成员再创建一个npm (group)仓库名字叫npm-group。在Member repositories里把刚才建的npm-hosted加到右边。如果以后有 proxy 仓库也一并加进来。group 仓库的地址是http://nexus-host:8081/repository/npm-group/。客户端配置 registry 时用这个地址就能同时访问 hosted 和 proxy 里的包。这里有个细节group 仓库的成员顺序会影响解析优先级。Nexus3 会按成员列表从上到下依次查找找到就返回。所以如果你有多个 hosted 仓库把优先级高的放上面。在纯离线场景里只有一个 hosted顺序无所谓。3.4 用 REST API 批量上传 tarball手动在界面上传几百个包是不现实的必须用脚本。Nexus3 提供了 REST API 来上传组件npm 格式的上传接口是curl -u admin:password -X POST \ http://nexus-host:8081/service/rest/v1/components?repositorynpm-hosted \ -F npm.assetpackage-name-1.0.0.tgz注意这里的npm.asset是固定字段名后面跟和文件路径。上传成功后返回 204 状态码。批量上传的脚本思路是遍历离线镜像目录里的所有.tgz文件逐个调这个接口。但这里有个坑——文件名里的特殊字符需要处理。Yarn 的离线镜像目录里包名里的/会被替换成-会被保留所以像babel/core这种包文件名可能是babel-core-7.0.0.tgz。上传时 Nexus3 会根据 tarball 内部的package.json来解析真实的包名和版本所以文件名不影响但你要确保 tarball 本身是完整的。另一个坑是并发上传。如果包特别多串行上传会很慢。可以写个简单的并发控制比如用xargs -P 4开 4 个并发。但不要开太多Nexus3 的默认连接池有限并发太高会报 503。find ./npm-packages-offline-cache -name *.tgz | \ xargs -P 4 -I {} curl -s -u admin:password \ -X POST http://nexus-host:8081/service/rest/v1/components?repositorynpm-hosted \ -F npm.asset{}上传完成后可以在 Nexus3 界面里Browse那个 hosted 仓库看看包的数量和版本是否对得上。4. Yarn 离线镜像的制作与客户端接入4.1 在联网机器上生成离线镜像找一台能访问公网的机器把项目的package.json和yarn.lock拷过去。如果没有yarn.lock先执行一次yarn install生成。然后配置离线镜像目录yarn config set yarn-offline-mirror ./npm-packages-offline-cache yarn config set yarn-offline-mirror-pruning true第一个命令指定缓存目录第二个命令开启修剪模式——当 lock 文件里的依赖被移除时对应的 tarball 也会从缓存目录里删掉保持目录干净。接着执行yarn install --frozen-lockfile--frozen-lockfile确保不会更新 lock 文件所有依赖都按现有 lock 解析。执行完成后npm-packages-offline-cache目录里应该有一堆.tgz文件数量等于 lock 文件里所有包的版本数。提示如果你的项目有多个子包monorepo建议在根目录执行一次完整的安装确保所有 workspace 的依赖都被缓存。Yarn 的离线镜像目录是全局共享的不同子包的依赖会合并到同一个目录。4.2 离线镜像目录的结构与校验生成的目录结构是平铺的所有 tarball 都在同一层。文件名格式是包名-版本.tgz其中包名里的/被替换成-保留。比如babel-core-7.23.0.tgz lodash-4.17.21.tgz react-18.2.0.tgz每个 tarball 的完整性由yarn.lock里的integrity字段保证。这个字段是 SHA-512 哈希Yarn 在安装时会校验。如果 tarball 在传输过程中损坏校验会失败并报错。为了提前发现问题可以在上传前做一次批量校验。思路是解析yarn.lock提取每个包的resolvedURL 和integrity值然后对本地 tarball 计算哈希并比对。这个脚本用 Node.js 写比较方便因为可以直接用yarn.lock的解析库。如果嫌麻烦至少要做一次抽样校验——随机抽 10% 的 tarball用shasum -a 512算一下和 lock 文件里的值对比。我遇到过因为磁盘坏道导致 tarball 损坏的情况抽样校验能提前发现。4.3 客户端 .yarnrc 与 .npmrc 配置在隔离环境的客户端上需要配置两个文件。.npmrc里配置 registryregistryhttp://nexus-host:8081/repository/npm-group/.yarnrc里配置 registry 和离线镜像registry http://nexus-host:8081/repository/npm-group/ yarn-offline-mirror ./npm-packages-offline-cache yarn-offline-mirror-pruning true注意.yarnrc的语法和.npmrc不同键值之间是空格分隔不是等号。这是很多人第一次配置时容易搞错的地方。如果客户端本地也有离线镜像目录比如从联网机器拷贝过来的Yarn 会优先从本地目录找 tarball。找不到再去 registry 拉。在完全隔离环境里本地目录可以留空所有包都从 Nexus3 拉。4.4 执行离线安装与验证配置完成后在项目目录执行yarn install --offline --frozen-lockfile--offline标志告诉 Yarn 不要尝试访问网络只用本地缓存和 registry。--frozen-lockfile确保 lock 文件不被修改。如果一切正常安装会顺利完成。如果报错常见的有两类一是integrity check failed说明 tarball 损坏或版本不匹配二是Couldnt find package说明某个包没有上传到 Nexus3。验证安装结果是否完整可以对比node_modules里的包数量和 lock 文件里的条目数。更严格的做法是跑一次项目的构建和测试确保所有依赖都能正常加载。注意--offline标志在 Yarn 1.x 和 Yarn 2 里的行为不同。Yarn 1.x 的--offline会强制使用缓存如果缓存里没有会直接报错。Yarn 2 的离线机制改成了.yarn/cache目录配合enableGlobalCache配置方式完全不同。这篇文章讲的是 Yarn 1.x 的经典离线镜像方案因为它在隔离环境里部署最简单兼容性也最好。5. 常见问题排查与避坑经验实录5.1 上传后安装报 integrity 错误这是最常见的问题表现是yarn install时报某个包的integrity check failed。原因通常是 tarball 在上传过程中被修改了。Nexus3 在上传 npm 包时会解析 tarball 并重新计算哈希。如果 tarball 本身是完整的Nexus3 返回的内容应该和原始文件一致。但有些情况下Nexus3 的存储层可能会对文件做压缩或转码导致哈希变化。排查方法是从 Nexus3 下载那个包的 tarball和本地的原始文件做diff或哈希对比。如果确实不一致尝试重新上传或者检查 Nexus3 的 blob store 配置。另一个可能的原因是 lock 文件里的integrity值和 tarball 不匹配。这种情况通常发生在手动修改过 lock 文件或者从不同来源合并了 lock 文件。解决办法是删掉 lock 文件重新生成然后重新制作离线镜像。5.2 包名大小写导致的解析失败npm 的包名是大小写敏感的但有些文件系统比如 macOS 的默认文件系统是大小写不敏感的。在联网机器上生成的离线镜像文件名可能被系统自动转成了小写导致上传到 Nexus3 后包名不匹配。比如React和react在 npm 里是两个不同的包但在 macOS 上可能被当成同一个文件。解决办法是在 Linux 机器上生成离线镜像或者在打包传输时用tar保留原始文件名。5.3 并发上传导致的 503 错误前面提到用xargs -P做并发上传但如果并发数太高Nexus3 会返回 503 Service Unavailable。这是因为 Nexus3 的默认线程池有限同时处理太多请求会排队超时。解决办法是把并发数降到 2 到 4同时在脚本里加重试逻辑。遇到 503 时等待几秒再重试通常第二次就能成功。upload_with_retry() { local file$1 local retries3 while [ $retries -gt 0 ]; do if curl -s -o /dev/null -w %{http_code} -u admin:password \ -X POST http://nexus-host:8081/service/rest/v1/components?repositorynpm-hosted \ -F npm.asset$file | grep -q 204; then return 0 fi retries$((retries - 1)) sleep 2 done echo Failed to upload $file return 1 }5.4 Yarn 版本不一致导致的 lock 文件冲突如果团队里有人用 Yarn 1.x有人用 Yarn 2lock 文件的格式会不一样导致解析失败。Yarn 1.x 的 lock 文件是自定义格式Yarn 2 的是 YAML 格式两者不兼容。解决办法是在项目根目录放一个.yarnrc或package.json里的engines字段强制指定 Yarn 版本。或者在 CI 里用yarn --version检查版本不对直接报错。5.5 常见问题速查表问题现象可能原因排查方法解决方案integrity check failedtarball 损坏或哈希不匹配对比本地和 Nexus3 的 tarball 哈希重新上传或重新生成离线镜像Couldnt find package包未上传到 Nexus3在 Nexus3 界面搜索包名补传缺失的包503 Service Unavailable并发上传过高查看 Nexus3 日志降低并发数加重试逻辑包名大小写不匹配文件系统大小写不敏感检查 tarball 文件名在 Linux 上生成离线镜像lock 文件解析失败Yarn 版本不一致检查 yarn --version统一 Yarn 版本安装速度极慢Nexus3 索引未重建查看仓库的索引状态手动触发索引重建5.6 几个我踩过的坑第一个坑是忘了改 Deployment policy。默认是Read-only上传时直接报 400。改成Allow redeploy后正常。这个选项在创建仓库时不太显眼但很关键。第二个坑是Nexus3 的 blob store 磁盘满了。npm 包虽然单个不大但数量多了之后占用很可观。建议给 blob store 单独挂一块盘并设置监控告警。磁盘满了之后 Nexus3 会进入只读模式所有上传和下载都会失败。第三个坑是Yarn 的离线镜像目录没有修剪。跑了几次yarn install之后目录里堆了几百个不再使用的旧版本 tarball。开启yarn-offline-mirror-pruning true后每次安装会自动清理不再引用的包。但这个选项有个副作用如果你在多个项目之间共享同一个离线镜像目录修剪时会误删其他项目需要的包。所以建议每个项目用独立的镜像目录或者干脆不开启修剪定期手动清理。第四个坑是Nexus3 的匿名访问权限。默认情况下Nexus3 允许匿名用户读取仓库内容。在隔离环境里这通常没问题但如果你的环境有安全要求需要在Security-Anonymous里关闭匿名访问然后给客户端配置认证信息。认证信息可以写在.npmrc里registryhttp://nexus-host:8081/repository/npm-group/ //nexus-host:8081/repository/npm-group/:_authbase64encoded注意这里的_auth是 Base64 编码的用户名:密码不是明文。生成方式是echo -n admin:password | base64。6. 方案扩展与长期维护建议6.1 定期同步增量依赖离线环境不是一次搭建就一劳永逸的。项目在迭代依赖在更新每隔一段时间就需要把新的包同步到 Nexus3。我的做法是维护一个「同步清单」记录每次新增的依赖。在联网机器上更新package.json和yarn.lock后重新生成离线镜像然后用脚本对比新旧镜像目录的差异只上传新增的 tarball。这样比全量上传快得多也减少了 Nexus3 的存储压力。对比差异可以用comm命令comm -13 (ls old-cache | sort) (ls new-cache | sort)这会列出只在 new-cache 里存在的文件也就是新增的 tarball。6.2 用 Nexus3 的清理策略控制存储增长Nexus3 支持为仓库配置清理策略Cleanup Policy可以按时间或版本数自动删除旧包。在Repository-Cleanup Policies里创建策略然后在仓库配置里关联。对于 npm 仓库我一般设置「保留最近 5 个版本」或「保留最近 90 天」。但要注意如果某个旧版本被其他项目的 lock 文件引用删除后会导致安装失败。所以清理策略要谨慎使用最好先做一次依赖分析确认哪些版本还在被引用。6.3 监控与告警Nexus3 本身提供了一些健康检查接口可以集成到监控系统里。关键指标包括磁盘使用率、请求响应时间、上传失败率、仓库大小。磁盘使用率是最重要的因为 Nexus3 磁盘满了之后会进入只读模式影响所有依赖安装。建议设置 80% 告警90% 严重告警。请求响应时间可以反映 Nexus3 的性能状况。如果响应时间突然变长可能是索引过大或 JVM 内存不足需要调整配置。6.4 备份与迁移Nexus3 的所有数据都在sonatype-work目录里备份这个目录就相当于备份了整个服务。建议定期做全量备份并在迁移前做一次完整备份。迁移到新服务器时把sonatype-work目录打包拷过去解压到相同路径然后启动 Nexus3 即可。注意新服务器的 Nexus3 版本要和旧服务器一致否则数据格式可能不兼容。如果只是迁移 npm 仓库的数据也可以用 Nexus3 的导出功能。在仓库配置里有个Export选项可以把仓库内容导出成 JSON 或 tarball。但导出功能对 npm 格式的支持不太完善我一般还是直接备份整个sonatype-work目录。这套方案我在几个不同规模的团队里都落地过从几十个包的小项目到上千个包的大型 monorepo整体稳定性很好。关键是把离线镜像的制作和上传流程脚本化减少人工操作这样每次依赖更新都能快速同步。Nexus3 的 group 仓库设计也让后续扩展变得很灵活哪天环境允许访问公网了加一个 proxy 仓库进去就行客户端完全无感。