研发内网环境里搞过两年Node基建的人都绕不开一个痛npm install装不动。不是包太大也不是网速慢而是构建机可能根本出不了外网或者只能通过公司弱网出口去访问npm官方源稍微大一点的依赖树跑半小时还超时报错。我试过把node_modules整个复制来复制去试过用轻量开源方案临时顶上最后真正稳定落地的方案是用Nexus Repository Manager在公司内网搭一个本地仓库来存储npm包外网的包缓存进来内部的私有包发布进去团队统一一个registry地址研发、测试、生产构建三条链路全都走内网流量。这篇文章就是一次完整的实操复盘从选型到部署、从建仓到发布、从权限到备份中间带了不少踩坑记录希望对想在内网搭建npm仓库的同行有帮助。1. 为什么要在内网自建Nexus的npm仓库1.1 内网开发最头疼的几个场景在聊方案之前先说清楚问题本身。我见过太多团队在内网环境下被npm折腾得死去活来典型场景基本是这几类研发机不能访问公网npm install永远卡在sill idealTree buildDeps等半小时最后超时失败。网络虽然可以出公网但没有加速通道包体稍微大一些就断连甚至下载下来的包校验失败、内容损坏。团队有多条产品线A项目跑得好好的B项目一装依赖就崩最后查出来是某几个传递依赖的版本在外网源被更新或下架了内网机器拉不到历史版本构建无法复现。内部公共组件库只能靠git clone分发每次都要切分支、打tag版本管理一塌糊涂。以上任何一个问题落到业务上都是实打实的交付延迟。而Nexus内网本地仓库正好可以一次性覆盖这些痛点它能缓存外网的npm包让团队和内网CI都从本地拉取能托管内部私有包让组件库有了正规的发布通道能把所有依赖固化在可控的内网环境里降低供应链风险和网络抖动影响。1.2 为什么选Nexus而不是Verdaccio或者私有源SaaS很多团队听到“npm私有仓库”第一反应是用Verdaccio或者Sinopia配置确实快一个进程跑起来就能用。但如果你站在企业级内网环境的视角去评估Nexus的优势会更明显对比维度Nexus Repository ManagerVerdaccio / Sinopia多格式支持npm、Maven、Docker、PyPI、NuGet等一网打尽基本只专注npm权限模型仓库级/组级/用户级精细权限可对接LDAP权限较简单高可用与运维成熟的企业运维文档、REST API、Cleanup策略相对偏轻量社区方案长期维护Sonatype官方持续迭代社区维护偶有不兼容升级我做选型的一个实际体会是公司技术栈往往不止前端Java后端、Python脚本、容器镜像都有制品管理需求。与其给每个语言都搭一套私服不如在一台服务器上部署一个Nexus把npm、Maven、PyPI等仓库全部纳管。这样运维成本集中开发者也只需要记住一个Nexus入口。所以虽然Nexus初始配置比Verdaccio繁琐一些但这是一次性投入后期收益大得多。2. 彻底搞懂Nexus的三种仓库proxy、hosted、group2.1 proxy仓库内网缓存外部npm包的默认闸门proxy仓库从名字就能看出它的定位代理。开发者的npm客户端发起请求时Nexus先查本地缓存命中就直接返回没命中才会请求上游远程源比如官方源https://registry.npmjs.org下载完再缓存到本地。结果是同一个依赖在团队里只要有一个人装过后续所有人都是走内网缓存出网流量大幅下降安装速度也能拉满。但我必须提醒一个细节很多教程只告诉你“创建一个proxy仓库指向npmjs.org”却不说Nexus对npm元数据有自己的缓存策略。npm的registry机制比较特殊安装包的时候既要拉包的元数据metadata对应注册中心的JSON信息又要拉实际的tgz文件。Nexus对这两种数据分别有Maximum Component Age和Maximum Metadata Age两个参数。前者控制包件的缓存保留时间后者控制元数据新鲜度。我实际项目中的建议配置是Maximum Component Age设成1440分钟一天甚至更高因为组件本身是内容寻址的缓存的tgz不会“变坏”旧版本一直在拉取不受影响。Maximum Metadata Age设成10到30分钟不然你刚刚发布到上游源的新版本内网用户要等很久才能看到排查问题时最容易被误判为“网络不同步”。如果内网是完全不能出公网的物理隔离网那proxy仓库的上游地址可以指向一台有外网权限的临时代理机或者干脆在部署阶段临时开放外网把常用依赖预热一遍。这部分我在后面的“完全隔离网怎么预热依赖”小节里再展开。2.2 hosted仓库内部私有npm包的正式家园hosted仓库就是为“内网私有包”准备的。团队内部的公共组件比如company/ui、company/utils统一通过npm publish推送到这里别的项目安装时直接从内网拉取。hosted仓库把版本、权限、可追溯性都管住了比git clone方式先进得多。在实际创建npm hosted仓库时有一个容易踩的坑Nexus对npm私有包默认要求必须带scope命名空间。也就是说publish一个不带scope的包比如my-lib大概率会被拒绝报错原因是“name must conform to the npm naming rules”或scope校验失败。这个设计是为了防止内部包和外部公开包混淆属于安全保护机制不要轻易关掉。所以团队的私有包一定要统一规范公司名/包名比如acme/core、acme/components。关于这个坑后面的常见问题章节还会详细说。2.3 group仓库统一registry入口group仓库是一个聚合视图你可以把proxy仓库和hosted仓库一起挂进去然后给开发者一个统一的访问地址。比如http://10.0.0.18:8081/repository/npm-group/开发者完全不需要关心某个包是在hosted里还是proxy里也不用配置多个registry。Nexus会按group配置的成员顺序去搜索先查hosted里的私有包再查proxy里的缓存包都没有才触发上游下载。这个顺序很关键我强烈建议把hosted放在前面否则一旦项目里引入了一个与外部同名的内部包就会被代理仓库里的同名公共包覆盖造成依赖错乱。所以我们在生产环境的布局是npm-proxy指向外网官方源负责缓存公共包。npm-hosted存放公司私有包只允许登录用户publish。npm-group把上面两者聚合对外提供给研发、CI统一使用。三个仓库组成一套完整的内网npm分发体系这也是Nexus管理npm包的标准姿势。3. Nexus环境准备与安装部署全记录3.1 硬件要求与服务器规划Nexus本身是Java应用基于JVM运行内存和磁盘是它的主要消耗项。我自己部署的经验是最低配置2核CPU、4GB内存、100GB磁盘适合团队规模10人左右。推荐配置4核CPU、8GB内存、最少200GB磁盘适合50人以上团队或者有大量自动化构建任务的场景。磁盘空间容易被低估。npm包虽然单个不大但缓存的包一多几十GB很常见Maven和Docker反过来占得更厉害。建议单独挂载一个数据盘把Nexus的sonatype-work目录放到数据盘上避免系统盘被撑爆。3.2 JDK与Nexus安装包准备Nexus 3.x核心是Java服务需要JDK 8或JDK 11环境较新版本也支持JDK 17但官方长期推荐的还是8/11。Linux服务器上可以直接用包管理器安装或者下载压缩包解压配置。我习惯用OpenJDK命令大致如下# 以CentOS/RHEL系为例 sudo yum install -y java-11-openjdk java-11-openjdk-devel java -version然后从Sonatype官网下载Nexus 3的unix版压缩包一般文件名类似nexus-3.56.0-01-unix.tar.gz。上传到服务器后解压sudo mkdir -p /usr/local/nexus sudo tar -zxvf nexus-3.56.0-01-unix.tar.gz -C /usr/local/nexus --strip-components1 sudo chown -R nexus:nexus /usr/local/nexus解压完成后目录结构大概有两块nexus应用目录和sonatype-work数据目录。其中sonatype-work是核心数据所在所有仓库配置、包文件、索引都存在这里备份和恢复都围绕它进行。3.3 首次启动与admin密码修改启动命令很简单但有几个细节要注意cd /usr/local/nexus/bin ./nexus start第一次启动会比较慢因为要初始化数据库和元数据目录。启动完后访问http://服务器IP:8081默认端口是8081。如果页面打不开先检查防火墙和云安全组。Nexus 3新版本首次启动会生成一个随机管理员密码存放在sonatype-work/nexus3/admin.password文件里。你需要先用这个密码登录然后立即修改。老版本可能默认密码是admin123无论如何首次登录后的第一件事就是改密码和绑定管理员邮箱这一步千万不要省。登录后建议顺手把JVM内存参数调一下默认配置对4GB内存的机器偏保守。编辑nexus/bin/nexus.vmoptions把堆内存调上去-Xms4g -Xmx4g然后重启Nexus。内存参数是JVM领域的老话题堆太小会导致频繁Full GC表现就是管理页面卡顿、仓库下载速度忽快忽慢堆太大则会让服务器本身喘不过气所以最好根据机器可用内存来定。4. 在管理界面创建npm仓库三件套4.1 创建npm(proxy)代理仓库用管理员账号登录后进入Settings Repositories Create repository选择npm (proxy)。需要填写的关键字段Namenpm-proxy按自己团队习惯命名。Remote storagehttps://registry.npmjs.org。如果公司有内网访问外网的统一代理或者想用国内镜像加速也可以填https://registry.npmmirror.com但要注意镜像源和官方源的包一致性。Blob Store建议单独建一个npm-proxy-blob方便后续磁盘清理和数据分析。Maximum Component Age1440。Maximum Metadata Age30。保存后仓库就上线了。此时可以测试一下连通性在浏览器直接访问http://NexusIP:8081/repository/npm-proxy/能看到类似官方registry的JSON响应说明上游拉通。这里说一个实操经验如果公司网络到npm官方源走的是固定代理比如要通过http.proxy你需要在Nexus的HTTP/HTTPS代理设置里配置代理地址否则proxy仓库会连接超时。这个配置位置在Settings System HTTP/HTTPS Proxy很多人初次部署漏掉这一步导致仓库一直红名。4.2 创建npm(hosted)托管仓库接着创建npm (hosted)仓库Namenpm-hosted。Storage单独建一个blob。Hosted Type选择Online即可。Strict Content Type Validation保持勾选不关闭。创建好之后这个仓库就是团队私有npm包的家。建议你在创建初期就定好规则所有内部包必须带scope格式为公司标识/包名并且版本遵循SemVer规范。然后把这个规则写进团队的README文档因为后期如果一批包已经发布成无scope的裸名字再切换scope会牵动大量代码成本不小。4.3 创建npm(group)组合仓库并调整顺序最后创建npm (group)仓库Namenpm-group。Member Repositories把npm-hosted放在第一位npm-proxy放在第二位。保存之后npm-group就是开发者的统一入口。我建议在Nexus管理界面里再确认一遍成员顺序因为有些版本里“Add”之后默认顺序可能不是你要的顺序。group里成员顺序不只是优先级问题还会影响依赖解析的最终结果比如你本来想用内部包结果命中了同名外部包这种事故排查起来特别浪费时间。4.4 配置匿名访问的取舍如果你是在纯内网部署为了方便快速使用很多人会选择开启匿名访问。但我的建议是分阶段处理第一阶段联调期可以先开启匿名只读访问让团队能快速拉包减少一开始就被权限问题卡住的挫败感。第二阶段稳定期关闭匿名访问强制所有开发/CI用户走账号认证配合后面要说的npm Bearer Token Realm做权限审计。匿名访问的配置路径在Settings Anonymous Access。注意这里只控制“能不能访问仓库”真正发布权限还需要结合角色和用户配置。5. npm客户端配置与安装、发布实战5.1 开发机切换registry源让开发机使用内网Nexus仓库本质上就是修改npm的registry配置。推荐用项目级.npmrc而不是直接改全局配置这样每个项目一目了然。示例registryhttp://10.0.0.18:8081/repository/npm-group/ always-authtrue如果是完全离线内网通常在~/.npmrc里配置全局生效更适合但要注意always-authtrue必须保留否则部分npm版本在访问受保护仓库时会因为没带认证信息而返回401。验证是否生效npm config get registry npm view lodash version如果看到版本号正常返回说明内网仓库链路已经打通。此时再跑npm install速度会有质的提升。5.2 登录与发布私有包发布内部包到hosted仓库的命令如下npm login --registryhttp://10.0.0.18:8081/repository/npm-group/输入Nexus账号密码然后发布npm publish --registryhttp://10.0.0.18:8081/repository/npm-hosted/这里有一个很多新手都会踩的坑发布时registry必须指定npm-hosted而不是npm-group。因为group里聚合了proxy仓库如果你往group地址发布Nexus会判断该包不属于hosted成员直接返回400/403错误。这不是Nexus出了问题而是它的安全策略。所以安装依赖用npm-group。发布私有包用npm-hosted。这两个地址不要混。团队内部文档里一定要写明这条规范否则每天都会有人来问你“为什么publish失败了”。5.3 私有包从零发布示例假设我们要发一个内部工具包acme/utils步骤大概如下在项目根目录初始化npm init -y npm pkg set nameacme/utils npm pkg set version1.0.0配置package.json的publishConfig.registry防止团队成员发布时写错地址{ name: acme/utils, version: 1.0.0, publishConfig: { registry: http://10.0.0.18:8081/repository/npm-hosted/ } }登录并发布npm login --registryhttp://10.0.0.18:8081/repository/npm-group/ npm publish这样哪怕开发者忘记了registry地址npm publish也会自动走到publishConfig指定的仓库这个细节对内网团队协作非常实用。5.4 CI构建中的配置方式生产环境CI使用Nexus仓库时建议在流水线里使用专用的构建账号而不是管理员账号。Jenkins/GitLab CI的npm命令加上环境变量即可npm config set registry http://10.0.0.18:8081/repository/npm-group/ npm config set always-authtrue认证信息可以用环境变量方式注入比如把_authToken写进流水线凭据不要硬编码到代码仓库里。CI账号只需要read权限不需要publish权限除非流水线本身要承担发布任务。6. 权限模型、清理策略与备份恢复6.1 启用npm Bearer Token RealmNexus对npm客户端登录的支持依赖一个安全领域npm Bearer Token Realm。需要进入Settings Security Realms把npm Bearer Token Realm从Available列表移到Active列表保存。这个配置不开启的话npm login即使账号密码正确也可能登录失败或者登录成功后访问仓库依然401。这个细节经常被忽略因为管理界面本身看着很正常但就是npm客户端进不来。我遇到过不止一次所以专门拉出来提醒。6.2 创建开发/CI专用用户与角色在第4章我们说了权限分阶段这里给出具体的用户规划建议deployer可以publish到npm-hosted适合内部组件库的维护者。developer只读访问npm-group适合普通研发。ci-builder只读访问npm-group供CI系统使用。创建步骤是先建角色把对应仓库的read、browse、edit仅deployer勾选上再建用户把角色挂上去。Nexus的权限粒度虽然不是最细但对内网几十号人的团队来说完全够用。6.3 磁盘占用与Cleanup清理策略Nexus跑久了磁盘占用一定会涨尤其是proxy仓库缓存了大量外部包。控制磁盘的方式是配置Cleanup策略Settings System Cleanup Policies Create policy关键参数Format选npm。Criteria比如“组件最后下载时间超过30天”“组件最后修改时间超过60天”。然后把这个策略挂到npm-proxy仓库上。cleanup策略本质上是给Nexus一个“可以删除的组件列表”实际删除操作是异步的所以部署后要观察是否真正释放了空间。我这里有个建议proxy仓库的清理阈值可以适度放宽因为npm包缓存删掉后只要有人再请求一次它又会从上游拉回来清理只是为了防止无限膨胀反而hosted仓库的包要谨慎清理私有包一旦删除依赖它的项目就可能构建失败。6.4 备份与恢复实操Nexus的备份核心是sonatype-work目录。我的习惯是数据库和blob存储整体做文件系统快照用Linux的tar或rsync定时打包到备份磁盘。备份前最好停止Nexus或者接受小概率的数据不一致风险。对npm这种以文件缓存为主的场景有时候直接复制问题不大但为了严谨还是建议用官方推荐的离线备份方式。一个比较实用的恢复演练场景换一台新服务器安装同样的Nexus版本把sonatype-work解压回去启动服务所有仓库配置和缓存的包都会原样恢复。这个操作我在测试环境验证过两次效果是稳定可靠的。所以如果你决定用Nexus当内网npm仓库一定把备份纳入日常巡检别等磁盘坏了再后悔。7. 常见问题排查与避坑指南7.1 npm install返回404/401/403这个系列错误我总结下来90%是以下几个原因仓库地址写错比如把npm-group拼错或者端口、IP不对。Bearer Token Realm没启用表现为npm login能成功但install时401。上游源不可达proxy仓库红名导致组件请求失败。这时先浏览器访问proxy仓库地址看看是否有正常JSON返回。账号权限不足用户只有group仓库权限但请求里指向了hosted或proxy地址。排查时我习惯按这个顺序走先确认网络连通性再确认Nexus能访问上游然后确认Realms最后查权限。不要一上来就改账号配置容易越改越乱。7.2 npm publish报400/403提示scope错误前面说过Nexus对npm私有包要求必须带scope。如果你的包名是my-lib而不是acme/my-lib发布就会被拦。解决方案分两步修改package.json的name字段加上scope。确认publish时指定的仓库是hosted不是group。如果团队历史包袱实在重非要发不带scope的包可以创建hosted仓库时关闭scope限制但我不推荐这么做因为一旦不禁用后续内部包和外部包同名冲突的风险会一直存在。7.3 刚发布的包内网其他机器拉取不到这个现象通常不是包没发布成功而是Nexus的元数据缓存还没过期。尤其当你用npm-group作为统一入口时group成员里的proxy仓库可能缓存了旧元数据导致新版本不可见。解决办法是调整npm-proxy仓库的Maximum Metadata Age参数把时间调短比如10分钟。如果要立即生效也可以在Nexus管理界面中对proxy仓库执行Invalidate Cache操作但请注意这会让当前缓存的元数据作废下次请求会重新拉取上游速度略慢但不会出错。7.4 上传大体积包超时或失败npm包偶尔也会很大比如包含二进制资源或者内置skia/canvas一类的原生模块。当Nexus前端有Nginx反代时默认的client_max_body_size限制会导致上传413或者超时。解决方案是在Nginx配置里调整client_max_body_size 1024m; proxy_read_timeout 300s; proxy_send_timeout 300s;如果没有Nginx直接直连Nexus那一般不太会遇到这个限制但也要注意网络交换机或防火墙对长连接是否有限制。7.5 完全物理隔离的内网怎么预热依赖有些内网环境是永远不能出外网的这时候Nexus的proxy仓库指向外网没有任何意义因为它根本连不通。我的处理办法是在部署窗口期临时允许Nexus所在服务器访问一次外网把项目用到的基础依赖通过proxy仓库预热缓存。如果连临时外网都没有就准备一台能出外网的办公机把所有需要用到的tgz包下载下来再通过U盘或内部文件系统传到Nexus服务器用Nexus管理界面里的Upload component功能手动上传到hosted仓库。注意包名和版本要符合npm规范否则安装时对不上号。这种方法比较原始但对于强隔离环境来说已经是性价比最高的方式了。建议至少把lodash、react、vue、axios这类基础公共依赖提前预制好能解决大部分依赖问题。7.6 Nexus进程内存过高或频繁卡顿我在8GB内存的服务器上跑Nexus如果同时管理npm和Docker仓库16GB都未必富裕。如果你发现Nexus Web界面卡顿、仓库API响应慢先看内存指标然后调nexus.vmoptions的-Xms和-Xmx。另外尽量不要把Nexus和其他重型应用塞在同一台低配服务器上JVM应用最怕的就是内存被抢。8. 我实测过后的一些经验补充最后再分享几个实际项目里总结出来的细节文章里其他地方也提到了但这里集中说一下。第一Nexus管理界面的Settings Status页面可以快速看到仓库状态有异常会标红。建议运维同事每天花一分钟扫一眼尤其是proxy仓库因为上游网络一出问题它必然红名直接影响内网拉包。提前预警比等到开发报障再处理要舒服得多。第二团队里如果有人问“为什么我npm install了老半天还在转”先别急着怪内网先让他检查npm客户端用的registry到底是不是Nexus的group地址。很多人机器上残留着旧配置比如全局.npmrc和项目.npmrc冲突最终走的是公网源表现为时快时慢。第三发布私有包这件事一定要定版本规范推荐严格按照SemVer语义且每次发布前确认package.json里的版本号有没有递增。Nexus不像npm官方对重复发布限制那么严格但重复发布同名同版本会覆盖或报错内网流量再快也架不住版本混乱带来的排查成本。第四可以考虑写一个简单的发布脚本统一封装npm login、npm publish和版本检查减少人为失误。比如脚本里校验包名是否带scope、校验版本号是否递增、确认registry是否为hosted仓库全部通过才执行发布。这个脚本在团队协作中的价值不亚于Nexus本身的部署。我自己的感觉是Nexus内网npm仓库这整套东西一次性搭完之后日常维护成本并不高真正花时间的反而是规范和习惯。只要把仓库职责分清楚、权限管好、备份做到它的稳定性和效率都会远超直接依赖外网源的方式。希望这篇实操记录能帮你避开我踩过的那些坑在内网环境里把npm仓库这条路顺利走通。