搞前端稍微有点规模的公司，都会遇到一个很扎心的问题：新同事入职，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 \ --restart=always \ -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_HOST="nexus.example.com:8081" REGISTRY="http://${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.tgz"macOS 或 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 --depth=0如果输出没有报错，说明快照和当前项目的 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仓库
客户端配置方式有很多种，最简单粗暴的是改全局 registry：
npm config set registry http://nexus.example.com:8081/repository/npm-group/但我实际项目中更推荐在项目根目录加一个.npmrc，这样只对当前项目生效，不影响机器上的其他项目，也不会污染全局配置。文件内容如下：
registry=http://nexus.example.com:8081/repository/npm-group/ replace-registry-host=always请特别注意第二行。这是我在多次排障后加进去的救命题，后面会专门讲。
如果 Nexus 已经关闭了匿名访问，客户端还需要做一次登录认证：
npm login --registry=http://nexus.example.com:8081/repository/npm-group/输入账号密码后，npm 会把 token 写进用户目录下的.npmrc。之后所有从这个 registry 发起的请求都会自动带上认证信息。
4.3 lockfile是最大的隐形拦截者
现在来说那个折腾了我很久的问题：为什么明明把 registry 配到了 Nexus，npm 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。
registry=http://nexus.example.com:8081/repository/npm-group/ replace-registry-host=always如果你用的 npm 版本比较老，不支持这个配置项，那最直接的办法就是删掉 lockfile 重新生成一次，让锁文件里的地址变成 Nexus 的地址。但这样会导致依赖版本发生漂移，所以有条件还是建议升级 npm。
4.4 pnpm与yarn接入时的差异
团队如果使用 pnpm，情况会稍微不一样。pnpm 读取的也是.npmrc，所以 registry 配置一样有效。但 pnpm 的锁文件pnpm-lock.yaml里，每个包的信息同样记录了 tarball 地址。好消息是 pnpm 在请求包时通常会把配置的 registry 作为优先来源，坏消息是如果你手动改过 registry，pnpm 可能会吐出一堆警告，并提示 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 install | 10-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-host=always。查
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一直报401
Nexus 上配完仓库之后，执行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，一直没动手，按这篇文章的顺序配一遍，就能感受到“依赖秒下”到底是什么体验了。
