企业官网建设流程全解析

研发内网环境里搞过两年Node基建的人都绕不开一个痛：npm install装不动。不是包太大，也不是网速慢，而是构建机可能根本出不了外网，或者只能通过公司弱网出口去访问npm官方源，稍微大一点的依赖树，跑半小时还超时报错。我试过把node_modules整个复制来复制去，试过用轻量开源方案临时顶上，最后真正稳定落地的方案，是用Nexus Repository Manager在公司内网搭一个本地仓库来存储npm包：外网的包缓存进来，内部的私有包发布进去，团队统一一个registry地址，研发、测试、生产构建三条链路全都走内网流量。这篇文章就是一次完整的实操复盘，从选型到部署、从建仓到发布、从权限到备份，中间带了不少踩坑记录，希望对想在内网搭建npm仓库的同行有帮助。

1. 为什么要在内网自建Nexus的npm仓库

1.1 内网开发最头疼的几个场景

在聊方案之前，先说清楚问题本身。我见过太多团队在内网环境下被npm折腾得死去活来，典型场景基本是这几类：

1. 研发机不能访问公网，npm install永远卡在sill idealTree buildDeps，等半小时最后超时失败。
2. 网络虽然可以出公网，但没有加速通道，包体稍微大一些就断连，甚至下载下来的包校验失败、内容损坏。
3. 团队有多条产品线，A项目跑得好好的，B项目一装依赖就崩，最后查出来是某几个传递依赖的版本在外网源被更新或下架了，内网机器拉不到历史版本，构建无法复现。
4. 内部公共组件库只能靠git clone分发，每次都要切分支、打tag，版本管理一塌糊涂。

以上任何一个问题，落到业务上都是实打实的交付延迟。而Nexus内网本地仓库正好可以一次性覆盖这些痛点：它能缓存外网的npm包，让团队和内网CI都从本地拉取；能托管内部私有包，让组件库有了正规的发布通道；能把所有依赖固化在可控的内网环境里，降低供应链风险和网络抖动影响。

1.2 为什么选Nexus而不是Verdaccio或者私有源SaaS

很多团队听到“npm私有仓库”，第一反应是用Verdaccio或者Sinopia，配置确实快，一个进程跑起来就能用。但如果你站在企业级内网环境的视角去评估，Nexus的优势会更明显：

我做选型的一个实际体会是：公司技术栈往往不止前端，Java后端、Python脚本、容器镜像都有制品管理需求。与其给每个语言都搭一套私服，不如在一台服务器上部署一个Nexus，把npm、Maven、PyPI等仓库全部纳管。这样运维成本集中，开发者也只需要记住一个Nexus入口。所以虽然Nexus初始配置比Verdaccio繁琐一些，但这是一次性投入，后期收益大得多。

2. 彻底搞懂Nexus的三种仓库：proxy、hosted、group

2.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-components=1 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)。

需要填写的关键字段：

• Name：npm-proxy，按自己团队习惯命名。
• Remote storage：https://registry.npmjs.org。如果公司有内网访问外网的统一代理，或者想用国内镜像加速，也可以填https://registry.npmmirror.com，但要注意镜像源和官方源的包一致性。
• Blob Store：建议单独建一个npm-proxy-blob，方便后续磁盘清理和数据分析。
• Maximum Component Age：1440。
• Maximum Metadata Age：30。

保存后仓库就上线了。此时可以测试一下连通性：在浏览器直接访问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)仓库：

• Name：npm-hosted。
• Storage：单独建一个blob。
• Hosted Type：选择Online即可。
• Strict Content Type Validation：保持勾选，不关闭。

创建好之后，这个仓库就是团队私有npm包的家。建议你在创建初期就定好规则：所有内部包必须带scope，格式为@公司标识/包名，并且版本遵循SemVer规范。然后把这个规则写进团队的README文档，因为后期如果一批包已经发布成无scope的裸名字，再切换scope会牵动大量代码，成本不小。

4.3 创建npm(group)组合仓库并调整顺序

最后创建npm (group)仓库：

• Name：npm-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，而不是直接改全局配置，这样每个项目一目了然。示例：

registry=http://10.0.0.18:8081/repository/npm-group/ always-auth=true

如果是完全离线内网，通常在~/.npmrc里配置全局生效更适合，但要注意always-auth=true必须保留，否则部分npm版本在访问受保护仓库时会因为没带认证信息而返回401。

验证是否生效：

npm config get registry npm view lodash version

如果看到版本号正常返回，说明内网仓库链路已经打通。此时再跑npm install，速度会有质的提升。

5.2 登录与发布私有包

发布内部包到hosted仓库的命令如下：

npm login --registry=http://10.0.0.18:8081/repository/npm-group/

输入Nexus账号密码，然后发布：

npm publish --registry=http://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，步骤大概如下：

1. 在项目根目录初始化：

npm init -y npm pkg set name="@acme/utils" npm pkg set version="1.0.0"

2. 配置package.json的publishConfig.registry，防止团队成员发布时写错地址：

{ "name": "@acme/utils", "version": "1.0.0", "publishConfig": { "registry": "http://10.0.0.18:8081/repository/npm-hosted/" } }

3. 登录并发布：

npm login --registry=http://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-auth=true

认证信息可以用环境变量方式注入，比如把_authToken写进流水线凭据，不要硬编码到代码仓库里。CI账号只需要read权限，不需要publish权限，除非流水线本身要承担发布任务。

6. 权限模型、清理策略与备份恢复

6.1 启用npm Bearer Token Realm

Nexus对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，发布就会被拦。解决方案分两步：

1. 修改package.json的name字段，加上scope。
2. 确认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仓库这条路顺利走通。