搞前端稍微有点规模的公司都会遇到一个很扎心的问题新同事入职git clone完项目跑npm install然后整个上午就耗在等依赖上了。运气好二十分钟装完运气差遇到某个二进制的包下载失败直接一天搭进去。我之前在一个内部网络不太稳定的环境里连续几次被这种问题打断后来实在受不了花了两三天时间把整套前端依赖的镜像方案梳理并落地到了 Nexus 上。这篇文章就是那次实践的完整记录包含方案选型、Nexus 仓库配置、node_modules主动上传和被动缓存两条镜像路径以及最后真正跑通时踩过的几个坑。先说清楚这里的 Nexus 是指 Sonatype 的 Nexus Repository Manager也就是常说的私服/制品仓库不是 Windows 桌面美化那个 Dock 软件。它能托管 npm、Maven、Docker 镜像、Raw 文件等乱七八糟的东西。而本文的主角是前端项目里人人又爱又恨的node_modules以及围绕它展开的“镜像至 Nexus”这件事。适合人群也很明确前端基建负责人、DevOps、以及那些被依赖安装折磨到想离职的普通前端开发。1. 先搞清楚把node_modules“镜像”到Nexus有哪几条路可以走1.1 直接拷贝node_modules为什么靠不住很多人第一反应是既然是内网用我直接把项目里的node_modules打包发到 Nexus其他人下载解压不就行了听起来很直接但实践过就会明白node_modules不是一个普通文件夹。它的结构很复杂npm 在安装依赖时会做依赖提升hoisting大量包被扁平化放到顶层同时.bin目录里塞满了指向真实包的软链接。在 Windows 上打包再在 macOS 或 Linux 上解压这些链接基本就废了。更麻烦的是原生模块比如node-sass、sharp、esbuild、rollup这类包安装时会根据当前系统架构下载编译好的二进制文件你在 Windows 上打出来的包拿到 Linux CI 上根本跑不起来。还有一层更隐蔽的问题就算一台机器上node_modules是好的直接解压到另一台机器上非常容易出现依赖“幽灵”问题——没有通过 package.json 声明却能正常 require因为它在别人的node_modules里恰好存在。这些问题排查起来极其痛苦。所以真正靠谱的“镜像”不是把文件夹搬家而是把依赖包本身搬到 Nexus让团队所有成员通过 Nexus 重新拉取、重新生成自己机器上的node_modules。1.2 三种常被叫做“镜像”的方案在我调研和实测之后发现“把 node_modules 镜像到 Nexus”这个说法在落地时其实有三种截然不同的玩法各有各的适用场景。方案做法适用场景优点缺点A. 托管仓库逐包发布将依赖包/私有包npm publish到 Nexus 的 hosted 仓库私有组件库、被修改过的第三方包、公网下架包包粒度可管理支持版本回滚不适合整库搬运操作量大B. raw仓库离线快照把整个node_modules打成 tgz上传到 Nexus 的 raw 仓库离线环境恢复、项目整体存档简单粗暴一条命令搞定跨平台容易翻车体积大C. proxy仓库自动缓存客户端指向 Nexus 的 proxy 仓库首次下载后自动留在 Nexus 内部内网加速、日常开发最推荐无感接入可持续累积第一次还是需要Nexus访问公网这三种不是“三选一”的关系我在实际落地时把它们组合起来用了效果比单独使用任何一个都稳定。1.3 大多数团队落地时的组合拳我推荐的做法是以 C 为主B 做兜底A 只用于特殊情况。为什么要以 C 为主因为 proxy 仓库相当于一个“会记住的中间人”。团队开发时正常走npm install第一次 Nexus 会去公网把依赖拉回来并缓存第二次开始依赖就存在 Nexus 本地了速度直接起飞。开发体验几乎没有改变不需要手动维护包列表日常积累下来缓存就是一座完整的依赖镜像库。B 的价值在于应付极端情况。比如 Nexus 所在服务器刚搭好proxy 仓库还是冷的第一个跑npm install的人还是会很慢。这时候如果提前往里塞一个打好的node_modules.tgz就能让离线恢复变得非常简单。A 则更多是私有场景。比如团队内部开发的组件库、二次修改过的某个有 bug 的第三方包这些内容本来就不应该出现在公网仓库里直接发布到 Nexus hosted 仓库然后让 group 仓库优先从 hosted 里找实现内部包对开发者的完全透明。2. 环境准备Nexus部署与npm代理、托管、组合仓库的配置要点2.1 Docker部署与首次登录Nexus 部署最省心的是走 Docker 官方镜像。我这边使用的是sonatype/nexus3长期稳定版本选一个你信任的 tag 就行比如3.66.0。部署命令很简单docker pull sonatype/nexus3:3.66.0 docker run -d \ --name nexus \ --restartalways \ -p 8081:8081 \ -v nexus-data:/nexus-data \ sonatype/nexus3:3.66.0这里有个很容易让新手慌的细节Nexus 启动非常慢容器起来之后8081 端口可能要等 2 到 5 分钟才能正常响应。不要一看docker ps显示 UP 就去访问大概率会提示连接拒绝。这个阶段可以看日志判断docker logs -f nexus直到看到类似“Started Sonatype Nexus OSS”这样的日志才说明服务真正可用了。首次登录需要拿到初始管理员密码Nexus 会把密码生成到数据目录的admin.password文件中Docker 部署时通过下面这条命令读取docker exec -it nexus cat /nexus-data/admin.password然后访问http://你的服务器IP:8081用用户名admin和读出来的密码登录。登录成功后系统会强制要求修改管理员密码。2.2 三类npm仓库分别解决什么问题Nexus 3 的仓库类型虽然多但针对 npm 镜像核心就三类proxy代理、hosted托管、group组合。配置路径是登录后进入 Settings —— Repositories —— Create repository。npm(proxy)这是让 Nexus 自动缓存公网依赖的关键。Remote storage 填https://registry.npmjs.org/其他选项基本可以保持默认。它做的事情就是当你内网请求某个 npm 包时如果本地没有就去公网拉一份然后存下来下次再有同样的请求直接返回缓存内容。npm(hosted)托管仓库用于存放私有包或者主动上传的内部依赖。Deployment policy 我建议选 Allow redeploy因为后续发布脚本可能会有覆盖更新的需求不允许重部署会给自己找麻烦。npm(group)组合仓库把上面的 proxy 和 hosted 全部加进去。客户端只需要配置一个 group 仓库的地址Nexus 会自动在成员仓库里查找包。这里有一个关键的配置顺序问题group 仓库里成员顺序会影响查找逻辑。如果 proxy 在前那依赖查找时会优先查代理仓库找不到再去 hosted 仓库。我建议把 proxy 放前面因为日常绝大多数依赖都来自公网。想隐藏某个有问题的公网包版本时再在 hosted 里放一个同名同版本的占位包这样 group 会在 prox 之后在 hosted 找到它也可以达到“禁用一个坏版本”的效果。网上有些文章推荐“hosted 在前借用 SNAPSHOT”但这对 npm 场景不适用npm 本身没有 SNAPSHOT 语义。2.3 推荐的安全初始化配置Nexus 默认可以匿名访问所有仓库这在内网环境是很危险的。我建议按下面几个步骤收紧权限在 Security —— Realms 中启用npm Bearer Token Realm。这个不启用的话后续用npm login登录 Nexus 会频繁报认证失败是一个非常隐蔽的坑。在 Security —— Users 中创建一个专门用于前端部署的账号比如fe-deploy而不是直接拿 admin 到处用。给它授予nx-repository-view-npm-*-browse和nx-repository-view-npm-*-read权限如果需要向 hosted 仓库发布还要加上nx-repository-view-npm-npm-hosted-add。在 Security —— Anonymous Access 里把匿名访问关掉至少把匿名用户对 npm 仓库的权限收掉。如果你是完全内网且纯开发环境也可以保留只读匿名访问具体依据你的安全等级要求来。3. 主动上传依赖npm托管仓库与整包离线快照两种操作3.1 定向publish到托管仓库的脚本先说方案 A也就是把依赖包主动推到 hosted 仓库。虽然不推荐把整个node_modules批量 publish但私有包这个场景很常用而且当某些公网包因为许可证或版本下架原因无法正常拉取时也需要手动 publish 一个副本。我写过一个批量发布的脚本适用于/data/private-packages目录下存放的多个私有包NEXUS_HOSTnexus.example.com:8081 REGISTRYhttp://${NEXUS_HOST}/repository/npm-hosted/ TOKEN你的部署token cd /data/private-packages for pkg in */; do echo publishing $pkg ( cd $pkg npm publish --registry$REGISTRY ) done注意这里的 npm publish 命令认的是 package.json 里的 name 和 version所以不管是私有包还是镜像包都要保证这两个字段完整。而且如果包名已经存在于托管仓库里Nexus 会报 400 冲突需要把 version 往上提一个版本或者开启 Allow redeploy 策略。我在实践中发现直接遍历node_modules逐包 publish 是非常不靠谱的。很多被 npm 安装到node_modules里的包其实是残缺副本缺少打包所需的描述信息有的包名还带scope直接 publish 会带来一堆脏数据。真要镜像第三方包正规路径是拿到它的原始 tarball 再发布或者干脆交给方案 C 让 proxy 自动缓存。3.2 整目录打包上传raw仓库方案 B 更简单也更贴合“把 node_modules 传到 Nexus”这个标题的字面意思把整个目录打成压缩包放到 raw 仓库。先在 Nexus 里创建一个raw(hosted)类型仓库名字叫raw-hosted或者frontend-snapshots。然后在本机执行打包。在动手之前我强烈建议先做一次精简因为node_modules里藏着大量缓存和冗余文件直接打出来体积会大得离谱。# 先清理没有被 package.json 引用的包 npm prune --production # 然后再打包 tar -czf node_modules.tgz node_modules如果你只是想做个纯离线恢复不需要保留开发依赖--production可以帮你砍掉一大半体积。但如果你希望恢复后还能继续开发就不要加生产环境限定而是用npm prune npm dedupe这两个命令能去掉多余副本并尝试扁平化依赖树之后打出来的包会小很多。上传到 raw 仓库用curl就够了我习惯按“项目名/日期”组织目录curl -u fe-deploy:你的密码 \ --upload-file node_modules.tgz \ http://nexus.example.com:8081/repository/raw-hosted/demo-app/20260601/node_modules.tgzmacOS 或 Linux 上传这类大文件时curl实测很稳几十 MB 到几百 MB 都没问题。Windows 环境我更建议用 PowerShell 里的Invoke-WebRequest但要注意默认的-Method Put和--upload-file的语义略有差异别传上去之后资源损坏了。3.3 离线恢复时的验证步骤从 Nexus 拉回快照并解压不是把 tgz 放回去就完事了一定要做验证curl -u fe-deploy:你的密码 -O \ http://nexus.example.com:8081/repository/raw-hosted/demo-app/20260601/node_modules.tgz # 解压回项目目录 tar -xzf node_modules.tgz -C /path/to/demo-app/然后立刻检查依赖树是否完整cd /path/to/demo-app npm ls --depth0如果输出没有报错说明快照和当前项目的 package.json 是匹配的。这一步很关键因为node_modules快照是一个静态时间点它可能与最新的 package.json 不一致直接使用会导致开发时出现奇怪的模块找不到问题。另外再强调一次跨平台问题同一份 tgz 在 macOS 上打好后拿到 Linux CI 上大概率可以用因为两者都是类 Unix 系统软链接基本能保留。但 Windows 打出的包拿到 Linux 上基本必挂。所以我建议各平台各自维护快照文件目录名上区分清楚比如node_modules-macos.tgz、node_modules-linux.tgz。4. 被动热缓存让Nexus自动把公网依赖留在内网4.1 代理仓库的工作过程方案 C 是我最推荐长期使用的也是“镜像”二字在私服语境下最正宗的含义。它的工作过程可以这样理解开发者的npm install请求先到达 Nexus 的 group 仓库group 把请求交给 proxy 仓库proxy 检查本地有没有这个包的缓存。没有就去远程仓库比如https://registry.npmjs.org/下载然后返回给开发者并保留一份副本有就直接返回副本。这个设计最舒服的点在于整个缓存过程对外部完全透明开发者甚至不需要知道 Nexus 的存在只是 registry 地址变了而已。而且 Nexus 的 proxy 仓库会记录包的所有版本不会像某些简单代理那样只缓存最新版。4.2 客户端统一指向group仓库客户端配置方式有很多种最简单粗暴的是改全局 registrynpm config set registry http://nexus.example.com:8081/repository/npm-group/但我实际项目中更推荐在项目根目录加一个.npmrc这样只对当前项目生效不影响机器上的其他项目也不会污染全局配置。文件内容如下registryhttp://nexus.example.com:8081/repository/npm-group/ replace-registry-hostalways请特别注意第二行。这是我在多次排障后加进去的救命题后面会专门讲。如果 Nexus 已经关闭了匿名访问客户端还需要做一次登录认证npm login --registryhttp://nexus.example.com:8081/repository/npm-group/输入账号密码后npm 会把 token 写进用户目录下的.npmrc。之后所有从这个 registry 发起的请求都会自动带上认证信息。4.3 lockfile是最大的隐形拦截者现在来说那个折腾了我很久的问题为什么明明把 registry 配到了 Nexusnpm install还是会有大量请求跑到公网去答案藏在 lockfile 里。不管你是用package-lock.json、yarn.lock还是pnpm-lock.yaml里面都会记录每个包下载时的具体地址。比如package-lock.json里每个依赖项的resolved字段会写得清清楚楚node_modules/axios: { version: 1.7.2, resolved: https://registry.npmjs.org/axios/-/axios-1.7.2.tgz, integrity: sha512-... }当锁文件存在时npm 会优先按照resolved字段指定的地址下载而不是根据你当前配置的 registry。也就是说即使你把 registry 改成了 Nexus锁文件里的 URL 还是公网地址请求依然会绕过 Nexus 直接打到公网。这时候replace-registry-host配置就派上用场了。这个配置项从 npm 8 开始引入可选值有npmjs、never、always。当设为always时npm 会把锁文件里的 registry 主机部分替换成你当前配置的 registry从而保证所有请求都走 Nexus。registryhttp://nexus.example.com:8081/repository/npm-group/ replace-registry-hostalways如果你用的 npm 版本比较老不支持这个配置项那最直接的办法就是删掉 lockfile 重新生成一次让锁文件里的地址变成 Nexus 的地址。但这样会导致依赖版本发生漂移所以有条件还是建议升级 npm。4.4 pnpm与yarn接入时的差异团队如果使用 pnpm情况会稍微不一样。pnpm 读取的也是.npmrc所以 registry 配置一样有效。但 pnpm 的锁文件pnpm-lock.yaml里每个包的信息同样记录了 tarball 地址。好消息是 pnpm 在请求包时通常会把配置的 registry 作为优先来源坏消息是如果你手动改过 registrypnpm 可能会吐出一堆警告并提示 lockfile 与 registry 不匹配。最省心的处理方式是配好.npmrc之后删除pnpm-lock.yaml重新生成一次性把所有 tarball 地址刷成 Nexus。代价是版本可能会按当前 semver 范围重新解析但只要 package.json 里版本约束合理实际变化通常很小。yarn classic也就是 yarn 1.x没有replace-registry-host这个概念它固执地信任yarn.lock里的resolved字段。我试过改 registry 之后依然有一堆请求打到公网解决办法是删掉yarn.lock重新装一次。如果你用的 yarn 3 或 4则建议在.yarnrc.yml里配置npmRegistryServer: http://nexus.example.com:8081/repository/npm-group/yarn berry 对 registry 的掌控更强配合锁文件重生成效果很好。5. 实测对比与踩坑排查从配置到真正生效的最后一公里5.1 一组有代表性的实测数据为了让大家对这套方案的实际收益有个概念我拿一个 Vue3 Vite 的中型项目做了测试。项目依赖数量大概 600 个包node_modules解压后体积约 800MB。场景耗时说明公网冷安装 npm install10-15 分钟频繁出现 tarball 下载超时Nexus proxy 冷缓存10-15 分钟第一次所有包都要从公网进入缓存Nexus proxy 热缓存30-90 秒依赖已在 Nexus 本地纯内网下载整包快照解压恢复2-3 分钟主要是 tar 解压时间还需跑 npm ls 验证差别最明显的不是总耗时而是稳定性。公网环境下600 个包里只要有一个下载失败整次安装就失败运气不好还要手动删掉缓存重新来。走了 Nexus 之后除了第一次需要等待填充缓存其余时间基本不会出幺蛾子。5.2 排查链路一配置了Nexus却仍然访问公网这是被问得最多的一个问题。排查链路我总结成固定套路先看当前生效的 registry 到底是啥npm config get registry注意这个命令读取的是全局和用户级.npmrc如果项目里有项目级.npmrc要在项目目录下执行。确认项目根目录有没有.npmrc内容里有没有replace-registry-hostalways。查package-lock.json里resolved字段的地址是registry.npmjs.org还是 Nexus 的地址。如果是前者说明锁文件在引导请求走向公网。如果以上配置都没问题还可以去 Nexus 服务器上看请求日志。Nexus 的访问日志一般位于/nexus-data/log/request.log当开发者执行npm install时里面会刷刷刷出现大量来自内网 IP 的请求记录。如果日志里没有任何请求说明流量压根没到 Nexus问题必然出在客户端配置上。我用这套链路排查过五六次每一次最后都落在 lockfile 或.npmrc位置这两个原因上。5.3 排查链路二npm login一直报401Nexus 上配完仓库之后执行npm login很容易碰到 401 认证失败但这不代表账号密码错了。我在第一次搭建时就卡在这里后来翻文档才意识到默认情况下 Nexus 虽然能用账号密码访问 UI但 npm 客户端的 Bearer Token 认证域没有启用。解决办法是在 Nexus UI 中进入 Security —— Realms找到npm Bearer Token Realm把它从右侧“Inactive”加入左侧“Active”。保存之后再执行npm login就能正常返回 authenticated 状态了。另一个容易导致 401 的原因是账号权限不够。如果你用的是自己新建的fe-deploy账号必须确认它至少在 group 仓库上有read和browse权限否则即使认证成功拉取包时也会被拒绝。5.4 排查链路三缓存命中但版本不对Nexus 的 proxy 仓库在找不到包时默认会把 404 也缓存一段时间也就是所谓的 negative cache。当一个包刚发布到公网你马上去内网拉取Nexus 可能还没有它就把“不存在”这个结果缓存了等公网真正有了这个包内网还是持续返回“不存在”非常误事。遇到这种情况处理方式是进入对应 proxy 仓库的 Settings点开Invalidate Cache把缓存里的错误信息清掉。如果这个包是你自己刚 publish 到 hosted 仓库的也需要检查 hosted 仓库的 Deployment policy 是不是Allow redeploy否则版本已经存在时也会因为禁止覆盖而显得像“缓存没更新”。另外Nexus 的 Cleanup Policy 如果配置不当会按时间自动清理缓存组件。对 npm proxy 这类长期依赖的仓库我建议不要设置太激进的老化策略或者直接不启用自动清理靠人工在磁盘空间告警时再处理。毕竟依赖缓存丢了可以再拉一遍但代价是团队又一次集体变慢。还有一个容易被忽略的小细节如果你在使用npm ci时必须重新下载所有包它会忽略node_modules里已有的内容直接从 registry 拉取。所以即使你刚解压了快照npm ci还是会按锁文件从头下载一遍。这时候正确的离线姿势是用npm install --offline或者干脆直接解压快照然后npm ls验证而不要强行跑npm ci。6. 一点补充把node_modules镜像这件事放进更大的体系里整套 Nexus 依赖镜像方案跑通之后我个人的体会是它解决的不只是“下载慢”这个问题更重要的是把前端依赖的可控性拿了回来。以前团队里每个人的node_modules都是各自从公网野路子拉回来的不同时间、不同网络、不同运气装出来的依赖树可能都不一样。大家嘴上说着“我这边能跑啊”实际上没人的环境是同一个版本组合。有了 Nexus 之后依赖来源统一了缓存统一了锁文件和 registry 的配合也有标准了“我这边能跑”这句经典台词出现的频率明显下降。再往后走你还可以把这套东西和 CI 流水线结合。构建镜像时不让 Docker 直接去公网拉依赖而是通过 Nexus 中转既能保证构建复现性又能给 Nexus 留一份已构建过的依赖缓存。甚至团队里一些非 npm 的产物比如构建好的 tar 包、体积较大的二进制文件、离线安装包都可以扔进 raw 仓库统一管理。Nexus 本来就是一个多面手前端依赖只是它能力范围内很小的一块。最后我分享一个每次配新环境都会用的操作序列先把 Docker 起好创建 proxy、hosted、group 三个仓库启用 npm Bearer Token Realm然后在项目.npmrc里写清 registry 和replace-registry-host最后用npm ci冷跑一次填充缓存。这套动作熟练之后十分钟能完成但换来的是团队今后每天都在享受的稳定安装体验。如果你之前只是听说过 Nexus一直没动手按这篇文章的顺序配一遍就能感受到“依赖秒下”到底是什么体验了。 
长河君 · 2026/10/1 23:34:14 · 阅读 1.2k Nexus搭建npm镜像私服：node_modules依赖加速与缓存方案实践
搞前端稍微有点规模的公司都会遇到一个很扎心的问题新同事入职git clone完项目跑npm install然后整个上午就耗在等依赖上了。运气好二十分钟装完运气差遇到某个二进制的包下载失败直接一天搭进去。我之前在一个内部网络不太稳定的环境里连续几次被这种问题打断后来实在受不了花了两三天时间把整套前端依赖的镜像方案梳理并落地到了 Nexus 上。这篇文章就是那次实践的完整记录包含方案选型、Nexus 仓库配置、node_modules主动上传和被动缓存两条镜像路径以及最后真正跑通时踩过的几个坑。先说清楚这里的 Nexus 是指 Sonatype 的 Nexus Repository Manager也就是常说的私服/制品仓库不是 Windows 桌面美化那个 Dock 软件。它能托管 npm、Maven、Docker 镜像、Raw 文件等乱七八糟的东西。而本文的主角是前端项目里人人又爱又恨的node_modules以及围绕它展开的“镜像至 Nexus”这件事。适合人群也很明确前端基建负责人、DevOps、以及那些被依赖安装折磨到想离职的普通前端开发。1. 先搞清楚把node_modules“镜像”到Nexus有哪几条路可以走1.1 直接拷贝node_modules为什么靠不住很多人第一反应是既然是内网用我直接把项目里的node_modules打包发到 Nexus其他人下载解压不就行了听起来很直接但实践过就会明白node_modules不是一个普通文件夹。它的结构很复杂npm 在安装依赖时会做依赖提升hoisting大量包被扁平化放到顶层同时.bin目录里塞满了指向真实包的软链接。在 Windows 上打包再在 macOS 或 Linux 上解压这些链接基本就废了。更麻烦的是原生模块比如node-sass、sharp、esbuild、rollup这类包安装时会根据当前系统架构下载编译好的二进制文件你在 Windows 上打出来的包拿到 Linux CI 上根本跑不起来。还有一层更隐蔽的问题就算一台机器上node_modules是好的直接解压到另一台机器上非常容易出现依赖“幽灵”问题——没有通过 package.json 声明却能正常 require因为它在别人的node_modules里恰好存在。这些问题排查起来极其痛苦。所以真正靠谱的“镜像”不是把文件夹搬家而是把依赖包本身搬到 Nexus让团队所有成员通过 Nexus 重新拉取、重新生成自己机器上的node_modules。1.2 三种常被叫做“镜像”的方案在我调研和实测之后发现“把 node_modules 镜像到 Nexus”这个说法在落地时其实有三种截然不同的玩法各有各的适用场景。方案做法适用场景优点缺点A. 托管仓库逐包发布将依赖包/私有包npm publish到 Nexus 的 hosted 仓库私有组件库、被修改过的第三方包、公网下架包包粒度可管理支持版本回滚不适合整库搬运操作量大B. raw仓库离线快照把整个node_modules打成 tgz上传到 Nexus 的 raw 仓库离线环境恢复、项目整体存档简单粗暴一条命令搞定跨平台容易翻车体积大C. proxy仓库自动缓存客户端指向 Nexus 的 proxy 仓库首次下载后自动留在 Nexus 内部内网加速、日常开发最推荐无感接入可持续累积第一次还是需要Nexus访问公网这三种不是“三选一”的关系我在实际落地时把它们组合起来用了效果比单独使用任何一个都稳定。1.3 大多数团队落地时的组合拳我推荐的做法是以 C 为主B 做兜底A 只用于特殊情况。为什么要以 C 为主因为 proxy 仓库相当于一个“会记住的中间人”。团队开发时正常走npm install第一次 Nexus 会去公网把依赖拉回来并缓存第二次开始依赖就存在 Nexus 本地了速度直接起飞。开发体验几乎没有改变不需要手动维护包列表日常积累下来缓存就是一座完整的依赖镜像库。B 的价值在于应付极端情况。比如 Nexus 所在服务器刚搭好proxy 仓库还是冷的第一个跑npm install的人还是会很慢。这时候如果提前往里塞一个打好的node_modules.tgz就能让离线恢复变得非常简单。A 则更多是私有场景。比如团队内部开发的组件库、二次修改过的某个有 bug 的第三方包这些内容本来就不应该出现在公网仓库里直接发布到 Nexus hosted 仓库然后让 group 仓库优先从 hosted 里找实现内部包对开发者的完全透明。2. 环境准备Nexus部署与npm代理、托管、组合仓库的配置要点2.1 Docker部署与首次登录Nexus 部署最省心的是走 Docker 官方镜像。我这边使用的是sonatype/nexus3长期稳定版本选一个你信任的 tag 就行比如3.66.0。部署命令很简单docker pull sonatype/nexus3:3.66.0 docker run -d \ --name nexus \ --restartalways \ -p 8081:8081 \ -v nexus-data:/nexus-data \ sonatype/nexus3:3.66.0这里有个很容易让新手慌的细节Nexus 启动非常慢容器起来之后8081 端口可能要等 2 到 5 分钟才能正常响应。不要一看docker ps显示 UP 就去访问大概率会提示连接拒绝。这个阶段可以看日志判断docker logs -f nexus直到看到类似“Started Sonatype Nexus OSS”这样的日志才说明服务真正可用了。首次登录需要拿到初始管理员密码Nexus 会把密码生成到数据目录的admin.password文件中Docker 部署时通过下面这条命令读取docker exec -it nexus cat /nexus-data/admin.password然后访问http://你的服务器IP:8081用用户名admin和读出来的密码登录。登录成功后系统会强制要求修改管理员密码。2.2 三类npm仓库分别解决什么问题Nexus 3 的仓库类型虽然多但针对 npm 镜像核心就三类proxy代理、hosted托管、group组合。配置路径是登录后进入 Settings —— Repositories —— Create repository。npm(proxy)这是让 Nexus 自动缓存公网依赖的关键。Remote storage 填https://registry.npmjs.org/其他选项基本可以保持默认。它做的事情就是当你内网请求某个 npm 包时如果本地没有就去公网拉一份然后存下来下次再有同样的请求直接返回缓存内容。npm(hosted)托管仓库用于存放私有包或者主动上传的内部依赖。Deployment policy 我建议选 Allow redeploy因为后续发布脚本可能会有覆盖更新的需求不允许重部署会给自己找麻烦。npm(group)组合仓库把上面的 proxy 和 hosted 全部加进去。客户端只需要配置一个 group 仓库的地址Nexus 会自动在成员仓库里查找包。这里有一个关键的配置顺序问题group 仓库里成员顺序会影响查找逻辑。如果 proxy 在前那依赖查找时会优先查代理仓库找不到再去 hosted 仓库。我建议把 proxy 放前面因为日常绝大多数依赖都来自公网。想隐藏某个有问题的公网包版本时再在 hosted 里放一个同名同版本的占位包这样 group 会在 prox 之后在 hosted 找到它也可以达到“禁用一个坏版本”的效果。网上有些文章推荐“hosted 在前借用 SNAPSHOT”但这对 npm 场景不适用npm 本身没有 SNAPSHOT 语义。2.3 推荐的安全初始化配置Nexus 默认可以匿名访问所有仓库这在内网环境是很危险的。我建议按下面几个步骤收紧权限在 Security —— Realms 中启用npm Bearer Token Realm。这个不启用的话后续用npm login登录 Nexus 会频繁报认证失败是一个非常隐蔽的坑。在 Security —— Users 中创建一个专门用于前端部署的账号比如fe-deploy而不是直接拿 admin 到处用。给它授予nx-repository-view-npm-*-browse和nx-repository-view-npm-*-read权限如果需要向 hosted 仓库发布还要加上nx-repository-view-npm-npm-hosted-add。在 Security —— Anonymous Access 里把匿名访问关掉至少把匿名用户对 npm 仓库的权限收掉。如果你是完全内网且纯开发环境也可以保留只读匿名访问具体依据你的安全等级要求来。3. 主动上传依赖npm托管仓库与整包离线快照两种操作3.1 定向publish到托管仓库的脚本先说方案 A也就是把依赖包主动推到 hosted 仓库。虽然不推荐把整个node_modules批量 publish但私有包这个场景很常用而且当某些公网包因为许可证或版本下架原因无法正常拉取时也需要手动 publish 一个副本。我写过一个批量发布的脚本适用于/data/private-packages目录下存放的多个私有包NEXUS_HOSTnexus.example.com:8081 REGISTRYhttp://${NEXUS_HOST}/repository/npm-hosted/ TOKEN你的部署token cd /data/private-packages for pkg in */; do echo publishing $pkg ( cd $pkg npm publish --registry$REGISTRY ) done注意这里的 npm publish 命令认的是 package.json 里的 name 和 version所以不管是私有包还是镜像包都要保证这两个字段完整。而且如果包名已经存在于托管仓库里Nexus 会报 400 冲突需要把 version 往上提一个版本或者开启 Allow redeploy 策略。我在实践中发现直接遍历node_modules逐包 publish 是非常不靠谱的。很多被 npm 安装到node_modules里的包其实是残缺副本缺少打包所需的描述信息有的包名还带scope直接 publish 会带来一堆脏数据。真要镜像第三方包正规路径是拿到它的原始 tarball 再发布或者干脆交给方案 C 让 proxy 自动缓存。3.2 整目录打包上传raw仓库方案 B 更简单也更贴合“把 node_modules 传到 Nexus”这个标题的字面意思把整个目录打成压缩包放到 raw 仓库。先在 Nexus 里创建一个raw(hosted)类型仓库名字叫raw-hosted或者frontend-snapshots。然后在本机执行打包。在动手之前我强烈建议先做一次精简因为node_modules里藏着大量缓存和冗余文件直接打出来体积会大得离谱。# 先清理没有被 package.json 引用的包 npm prune --production # 然后再打包 tar -czf node_modules.tgz node_modules如果你只是想做个纯离线恢复不需要保留开发依赖--production可以帮你砍掉一大半体积。但如果你希望恢复后还能继续开发就不要加生产环境限定而是用npm prune npm dedupe这两个命令能去掉多余副本并尝试扁平化依赖树之后打出来的包会小很多。上传到 raw 仓库用curl就够了我习惯按“项目名/日期”组织目录curl -u fe-deploy:你的密码 \ --upload-file node_modules.tgz \ http://nexus.example.com:8081/repository/raw-hosted/demo-app/20260601/node_modules.tgzmacOS 或 Linux 上传这类大文件时curl实测很稳几十 MB 到几百 MB 都没问题。Windows 环境我更建议用 PowerShell 里的Invoke-WebRequest但要注意默认的-Method Put和--upload-file的语义略有差异别传上去之后资源损坏了。3.3 离线恢复时的验证步骤从 Nexus 拉回快照并解压不是把 tgz 放回去就完事了一定要做验证curl -u fe-deploy:你的密码 -O \ http://nexus.example.com:8081/repository/raw-hosted/demo-app/20260601/node_modules.tgz # 解压回项目目录 tar -xzf node_modules.tgz -C /path/to/demo-app/然后立刻检查依赖树是否完整cd /path/to/demo-app npm ls --depth0如果输出没有报错说明快照和当前项目的 package.json 是匹配的。这一步很关键因为node_modules快照是一个静态时间点它可能与最新的 package.json 不一致直接使用会导致开发时出现奇怪的模块找不到问题。另外再强调一次跨平台问题同一份 tgz 在 macOS 上打好后拿到 Linux CI 上大概率可以用因为两者都是类 Unix 系统软链接基本能保留。但 Windows 打出的包拿到 Linux 上基本必挂。所以我建议各平台各自维护快照文件目录名上区分清楚比如node_modules-macos.tgz、node_modules-linux.tgz。4. 被动热缓存让Nexus自动把公网依赖留在内网4.1 代理仓库的工作过程方案 C 是我最推荐长期使用的也是“镜像”二字在私服语境下最正宗的含义。它的工作过程可以这样理解开发者的npm install请求先到达 Nexus 的 group 仓库group 把请求交给 proxy 仓库proxy 检查本地有没有这个包的缓存。没有就去远程仓库比如https://registry.npmjs.org/下载然后返回给开发者并保留一份副本有就直接返回副本。这个设计最舒服的点在于整个缓存过程对外部完全透明开发者甚至不需要知道 Nexus 的存在只是 registry 地址变了而已。而且 Nexus 的 proxy 仓库会记录包的所有版本不会像某些简单代理那样只缓存最新版。4.2 客户端统一指向group仓库客户端配置方式有很多种最简单粗暴的是改全局 registrynpm config set registry http://nexus.example.com:8081/repository/npm-group/但我实际项目中更推荐在项目根目录加一个.npmrc这样只对当前项目生效不影响机器上的其他项目也不会污染全局配置。文件内容如下registryhttp://nexus.example.com:8081/repository/npm-group/ replace-registry-hostalways请特别注意第二行。这是我在多次排障后加进去的救命题后面会专门讲。如果 Nexus 已经关闭了匿名访问客户端还需要做一次登录认证npm login --registryhttp://nexus.example.com:8081/repository/npm-group/输入账号密码后npm 会把 token 写进用户目录下的.npmrc。之后所有从这个 registry 发起的请求都会自动带上认证信息。4.3 lockfile是最大的隐形拦截者现在来说那个折腾了我很久的问题为什么明明把 registry 配到了 Nexusnpm install还是会有大量请求跑到公网去答案藏在 lockfile 里。不管你是用package-lock.json、yarn.lock还是pnpm-lock.yaml里面都会记录每个包下载时的具体地址。比如package-lock.json里每个依赖项的resolved字段会写得清清楚楚node_modules/axios: { version: 1.7.2, resolved: https://registry.npmjs.org/axios/-/axios-1.7.2.tgz, integrity: sha512-... }当锁文件存在时npm 会优先按照resolved字段指定的地址下载而不是根据你当前配置的 registry。也就是说即使你把 registry 改成了 Nexus锁文件里的 URL 还是公网地址请求依然会绕过 Nexus 直接打到公网。这时候replace-registry-host配置就派上用场了。这个配置项从 npm 8 开始引入可选值有npmjs、never、always。当设为always时npm 会把锁文件里的 registry 主机部分替换成你当前配置的 registry从而保证所有请求都走 Nexus。registryhttp://nexus.example.com:8081/repository/npm-group/ replace-registry-hostalways如果你用的 npm 版本比较老不支持这个配置项那最直接的办法就是删掉 lockfile 重新生成一次让锁文件里的地址变成 Nexus 的地址。但这样会导致依赖版本发生漂移所以有条件还是建议升级 npm。4.4 pnpm与yarn接入时的差异团队如果使用 pnpm情况会稍微不一样。pnpm 读取的也是.npmrc所以 registry 配置一样有效。但 pnpm 的锁文件pnpm-lock.yaml里每个包的信息同样记录了 tarball 地址。好消息是 pnpm 在请求包时通常会把配置的 registry 作为优先来源坏消息是如果你手动改过 registrypnpm 可能会吐出一堆警告并提示 lockfile 与 registry 不匹配。最省心的处理方式是配好.npmrc之后删除pnpm-lock.yaml重新生成一次性把所有 tarball 地址刷成 Nexus。代价是版本可能会按当前 semver 范围重新解析但只要 package.json 里版本约束合理实际变化通常很小。yarn classic也就是 yarn 1.x没有replace-registry-host这个概念它固执地信任yarn.lock里的resolved字段。我试过改 registry 之后依然有一堆请求打到公网解决办法是删掉yarn.lock重新装一次。如果你用的 yarn 3 或 4则建议在.yarnrc.yml里配置npmRegistryServer: http://nexus.example.com:8081/repository/npm-group/yarn berry 对 registry 的掌控更强配合锁文件重生成效果很好。5. 实测对比与踩坑排查从配置到真正生效的最后一公里5.1 一组有代表性的实测数据为了让大家对这套方案的实际收益有个概念我拿一个 Vue3 Vite 的中型项目做了测试。项目依赖数量大概 600 个包node_modules解压后体积约 800MB。场景耗时说明公网冷安装 npm install10-15 分钟频繁出现 tarball 下载超时Nexus proxy 冷缓存10-15 分钟第一次所有包都要从公网进入缓存Nexus proxy 热缓存30-90 秒依赖已在 Nexus 本地纯内网下载整包快照解压恢复2-3 分钟主要是 tar 解压时间还需跑 npm ls 验证差别最明显的不是总耗时而是稳定性。公网环境下600 个包里只要有一个下载失败整次安装就失败运气不好还要手动删掉缓存重新来。走了 Nexus 之后除了第一次需要等待填充缓存其余时间基本不会出幺蛾子。5.2 排查链路一配置了Nexus却仍然访问公网这是被问得最多的一个问题。排查链路我总结成固定套路先看当前生效的 registry 到底是啥npm config get registry注意这个命令读取的是全局和用户级.npmrc如果项目里有项目级.npmrc要在项目目录下执行。确认项目根目录有没有.npmrc内容里有没有replace-registry-hostalways。查package-lock.json里resolved字段的地址是registry.npmjs.org还是 Nexus 的地址。如果是前者说明锁文件在引导请求走向公网。如果以上配置都没问题还可以去 Nexus 服务器上看请求日志。Nexus 的访问日志一般位于/nexus-data/log/request.log当开发者执行npm install时里面会刷刷刷出现大量来自内网 IP 的请求记录。如果日志里没有任何请求说明流量压根没到 Nexus问题必然出在客户端配置上。我用这套链路排查过五六次每一次最后都落在 lockfile 或.npmrc位置这两个原因上。5.3 排查链路二npm login一直报401Nexus 上配完仓库之后执行npm login很容易碰到 401 认证失败但这不代表账号密码错了。我在第一次搭建时就卡在这里后来翻文档才意识到默认情况下 Nexus 虽然能用账号密码访问 UI但 npm 客户端的 Bearer Token 认证域没有启用。解决办法是在 Nexus UI 中进入 Security —— Realms找到npm Bearer Token Realm把它从右侧“Inactive”加入左侧“Active”。保存之后再执行npm login就能正常返回 authenticated 状态了。另一个容易导致 401 的原因是账号权限不够。如果你用的是自己新建的fe-deploy账号必须确认它至少在 group 仓库上有read和browse权限否则即使认证成功拉取包时也会被拒绝。5.4 排查链路三缓存命中但版本不对Nexus 的 proxy 仓库在找不到包时默认会把 404 也缓存一段时间也就是所谓的 negative cache。当一个包刚发布到公网你马上去内网拉取Nexus 可能还没有它就把“不存在”这个结果缓存了等公网真正有了这个包内网还是持续返回“不存在”非常误事。遇到这种情况处理方式是进入对应 proxy 仓库的 Settings点开Invalidate Cache把缓存里的错误信息清掉。如果这个包是你自己刚 publish 到 hosted 仓库的也需要检查 hosted 仓库的 Deployment policy 是不是Allow redeploy否则版本已经存在时也会因为禁止覆盖而显得像“缓存没更新”。另外Nexus 的 Cleanup Policy 如果配置不当会按时间自动清理缓存组件。对 npm proxy 这类长期依赖的仓库我建议不要设置太激进的老化策略或者直接不启用自动清理靠人工在磁盘空间告警时再处理。毕竟依赖缓存丢了可以再拉一遍但代价是团队又一次集体变慢。还有一个容易被忽略的小细节如果你在使用npm ci时必须重新下载所有包它会忽略node_modules里已有的内容直接从 registry 拉取。所以即使你刚解压了快照npm ci还是会按锁文件从头下载一遍。这时候正确的离线姿势是用npm install --offline或者干脆直接解压快照然后npm ls验证而不要强行跑npm ci。6. 一点补充把node_modules镜像这件事放进更大的体系里整套 Nexus 依赖镜像方案跑通之后我个人的体会是它解决的不只是“下载慢”这个问题更重要的是把前端依赖的可控性拿了回来。以前团队里每个人的node_modules都是各自从公网野路子拉回来的不同时间、不同网络、不同运气装出来的依赖树可能都不一样。大家嘴上说着“我这边能跑啊”实际上没人的环境是同一个版本组合。有了 Nexus 之后依赖来源统一了缓存统一了锁文件和 registry 的配合也有标准了“我这边能跑”这句经典台词出现的频率明显下降。再往后走你还可以把这套东西和 CI 流水线结合。构建镜像时不让 Docker 直接去公网拉依赖而是通过 Nexus 中转既能保证构建复现性又能给 Nexus 留一份已构建过的依赖缓存。甚至团队里一些非 npm 的产物比如构建好的 tar 包、体积较大的二进制文件、离线安装包都可以扔进 raw 仓库统一管理。Nexus 本来就是一个多面手前端依赖只是它能力范围内很小的一块。最后我分享一个每次配新环境都会用的操作序列先把 Docker 起好创建 proxy、hosted、group 三个仓库启用 npm Bearer Token Realm然后在项目.npmrc里写清 registry 和replace-registry-host最后用npm ci冷跑一次填充缓存。这套动作熟练之后十分钟能完成但换来的是团队今后每天都在享受的稳定安装体验。如果你之前只是听说过 Nexus一直没动手按这篇文章的顺序配一遍就能感受到“依赖秒下”到底是什么体验了。