企业官网建设流程全解析

接到这台离线机器的时候，第一反应是头大：Windows 10、没有外网、要同时维护一个跑在node 14的老项目和一个跑在node 18的新项目，还得保证后面接手的人拿到机器就能直接用。这意味着nvm必须离线装，node两个版本必须离线备好，环境变量要配到重启不失效，中间最好一步都不走弯路。网上关于nvm的教程十个里有九个默认你能打开官网、能跑远程安装脚本，真正放到断网环境里，很多做法都没法落地。这篇文章是我这次离线实操的完整记录，覆盖nvm离线安装、node多版本离线放置、环境变量配置、切换原理，以及实测中踩到的几个坑和对应排查思路。打算照着做的人，不管是内网开发、客户现场交付，还是纯粹想把nvm切换版本这套逻辑彻底搞明白，都能对着步骤直接操作。

1. 什么场景下需要离线安装nvm，离线前要备好什么

1.1 会被迫走离线路线的环境

我这次遇到的机器属于“完全物理隔离网络”，终端和开发机之间靠U盘拷贝文件，别说npm registry，连常规软件官网都访问不了。这类环境常见于安全管控比较严格的开发内网、客户现场的数据分析盒子、以及一些预装系统不带开发工具又禁止联网的办公机器。除此之外，还有一些场景虽然不是完全断网，但网络策略会把github和nodejs官网这类域名拦掉，实际效果跟离线没有区别。

还有一种情况容易被忽略：公司内部有软件仓库，但仓库里的nvm版本很老，老到不支持你要用的node版本。这种情况下“离线”不是因为没网，而是因为官方下载源不可达，只能手动把新版nvm带入内网。判断自己属于哪一种，直接决定了准备工作的范围。如果是完全断网，nvm本体、node压缩包、npm依赖都要提前准备好；如果只是官方源被限制了，那可以优先考虑配置镜像源，不一定非要走完全离线。

1.2 在线安装和离线安装的本质差别

在线安装nvm的核心动作是“一行命令拉脚本”，脚本会从github下载nvm本体，然后再从node_mirror拉取指定版本的node压缩包，自动解压、自动注册。一到离线环境，这条链路就断了，因为脚本本身没有网络可用。但要注意：nvm本身的管理逻辑并不依赖网络，它只是按约定把不同版本的node放在特定目录下，再通过环境变量或符号链接指向当前版本。这意味着，只要我们把nvm的目录结构手动构造出来，它一样能正常工作。

所以离线安装的实质是两个问题：一是把nvm本体的文件放到正确位置上，二是把node版本包手动放进nvm认识的目录结构里。这两个问题理解了，后面所有步骤都有迹可循，而不是对着教程瞎试。

1.3 离线前的素材清单

离线前需要准备的素材，建议用一个表格理清楚，避免到了现场才发现少了一个包：

表格里最容易被忽略的是“node压缩包的系统架构”。我见过有人把win-x64的包放到32位机器上，nvm能识别出来但node跑不起来。另一个常见错误是只准备了node版本包，没有准备nvm本体，以为装好nvm之后能直接联网拉node，这在离线环境里根本不可能。提前在U盘里把上述素材放好，现场能省出大量时间。

2. Windows离线安装nvm：绿色zip方式全流程

2.1 为什么选择zip而不是exe安装包

nvm-windows官方提供了两种成果物：一个是nvm-setup.exe安装器，另一个是没有安装界面的nvm-noinstall.zip绿色包。我在离线环境里强烈建议选zip，原因有三：

第一，绿色包可以自己控制目录位置，不用被安装器带到C盘用户目录下。nvm这种工具不像业务软件，它对路径的敏感性很高，路径里出现中文或空格，后续执行某些命令时会出现莫名奇妙的问题。第二，绿色包不会主动写注册表，卸载和迁移都方便，拷走目录就能换机器继续用。第三，在断网机器上安装exe虽然也能跑，但联网机器和离线机器之间的操作逻辑不统一，容易在某个隐藏界面卡住。zip包解压即完成，简单直接。

如果你手里的安装包是exe且不方便换，nvm-setup.exe其实也支持静默安装参数。在命令行里执行：

nvm-setup.exe /S

可以跳过安装向导直接完成安装。但装完之后默认目录依然不可控，我还是建议能用zip就不用exe。

2.2 解压目录的选择与约定

我这次的目录规划是：

• nvm主目录：D:\nvm
• 符号链接目录：D:\nodejs

把nvm-noinstall.zip里的内容全部解压到D:\nvm，解压完成后目录下应该能看到elevate.cmd、nvm.exe、settings.txt（有的版本没有，需要手动创建）等文件。这里要特别提醒，D:\nvm路径一定不要带中文、不要带空格，C:\Users\张三\nvm这种路径在后续创建符号链接时非常容易踩坑。

为什么不放C盘？除了路径权限问题，还有一个现实考量：C盘空间敏感，node不同版本动辄几百MB，如果历史版本装多了，C盘很快被撑满。D盘或E盘这种数据盘更适合放环境工具。这个习惯在Linux下同样适用，把nvm放在独立的、有权限控制的目录下，后续升级、备份、迁移都方便。

2.3 创建最小可用的settings.txt

解压完成后，如果目录下没有settings.txt，手动新建一个，内容如下：

root: D:\nvm path: D:\nodejs arch: 64 proxy: none original_path: node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/

这个配置文件是整个nvm离线安装的核心。root告诉nvm到哪里找版本目录，path告诉nvm把符号链接创建在哪里，arch指定架构，node_mirror和npm_mirror虽然离线环境下用不到，但设置成国内镜像地址没有副作用，万一后续环境开放网络，下载速度会快很多。如果内网有自己的镜像站，把这两个地址换成内网地址即可。

original_path这一项在手动创建时可以留空，它是nvm安装器自动写入的，用于保存安装前系统PATH里的原有node路径。内部机制不依赖它也能工作，手动补配置的时候不需要管。

2.4 系统环境变量配置的完整步骤

在Windows搜索框输入“编辑系统环境变量”，打开“环境变量”对话框，做以下设置：

系统变量里新建两个变量：

• 变量名：NVM_HOME，变量值：D:\nvm
• 变量名：NVM_SYMLINK，变量值：D:\nodejs

在系统变量Path中追加两项（追加，不是替换）：

%NVM_HOME% %NVM_SYMLINK%

有的教程直接在Path里写死D:\nvm;D:\nodejs，两种方式等效，但用变量名的好处是，以后如果nvm目录换了，只需要改一处变量，而不用去Path的长串里找旧路径。追加Path有个细节：如果原来是C:\Program Files\nodejs\这种老版本node路径，建议把它从Path里删掉。否则后续可能出现node -v显示的还是系统自带node的情况，这个坑后面专门讲。

2.5 验证安装是否成功

配置完环境变量后，不能直接用当前窗口验证，因为环境变量已经在窗口启动时读取过了。必须新开一个cmd窗口，依次执行：

nvm version nvm list

如果nvm version正常输出版本号，说明nvm本体已经能识别。如果提示“不是内部或外部命令”，优先检查NVM_HOME变量是否设置成功，以及Path里是否真的包含了%NVM_HOME%。确认无误后还是不行，就把新开终端这步再执行一遍，大部分“环境变量无效”问题其实都是终端没重启。

3. 离线状态下node本体的安装：手动放置版本目录

3.1 nvm install在联网时到底做了什么

要理解离线安装node的正确做法，先要搞清楚nvm install在线时干了哪些活。它做的其实是四件事：第一，向远端版本列表发起请求，拿到可用的版本号；第二，根据当前系统架构拼出node压缩包的下载地址；第三，下载zip压缩包并解压到nvm的root目录下，形成一个名为vX.X.X的文件夹；第四，把这个版本登记为可用版本，等待nvm use指令来激活。

离线环境下，前三步全部失效，但第四步“登记”本质上只是目录扫描，nvm会扫描root目录下所有名为vX.X.X的文件夹，把它们当作已安装版本。这就是手动放置方案能成立的根本原因。我们不需要骗过下载系统，只需要手动完成“下载-解压-放置”这三个动作，让nvm能看到目录即可。

3.2 离线环境下手动放置node版本的操作步骤

以安装node 16.20.2为例，完整步骤如下：

1. 在联网机器上下载node-v16.20.2-win-x64.zip。
2. 解压到任意临时目录，得到node-v16.20.2-win-x64文件夹。
3. 把这个文件夹改名为v16.20.2。
4. 移动到nvm的root目录下，最终目录结构应该是D:\nvm\v16.20.2\node.exe。
5. 打开cmd，执行nvm use 16.20.2。
6. 执行node -v，如果输出v16.20.2，安装成功。

同样的步骤对node 18完全适用，下载node-v18.20.4-win-x64.zip，改名为v18.20.4，放到D:\nvm下即可。多个版本可以并存，nvm会在nvm list中全部列出来，需要哪个就用nvm use切换过去。

这里有个细节：zip包改名为v16.20.2时，目录内部是不需要改任何内容的，node.exe、npm.cmd这些可执行文件名在压缩包内部已经固定。真正起作用的是外层目录名，nvm靠目录名来识别版本号。所以不要改内部文件结构，只改外层文件夹名，取名为“v+完整版本号”的格式。

3.3 Linux离线环境下的对应操作

Linux服务器的离线安装思路完全一致，只是路径和命名空间不同。先把nvm的tar.gz包拷贝到服务器，解压到用户目录下：

mkdir -p ~/.nvm tar -xzf nvm-0.39.7.tar.gz -C ~/.nvm --strip-components=1

然后在~/.bashrc或~/.zshrc末尾追加：

export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

执行source ~/.bashrc让配置生效。接着处理node版本包，下载node-v16.20.2-linux-x64.tar.xz，解压后改名为v16.20.2，放到~/.nvm/versions/node/目录下，最终路径是~/.nvm/versions/node/v16.20.2/bin/node。最后执行nvm ls确认能识别到该版本，再nvm use 16.20.2切换。

Linux和Windows在路径设计上有区别。Windows是root目录下直接放vX.X.X，Linux则多一层versions/node，这是两个独立实现的历史差异，手动放置时需要严格按各自约定来。

3.4 自带的npm是否可用

node压缩包里已经包含了npm，所以手动放置版本后，npm通常是直接可用的。但有几个问题需要提前注意：

第一，npm的全局依赖包路径在Windows下默认是%APPDATA%\npm，在Linux下是/usr/lib/node_modules或者nvm管理的对应目录，这与当前激活的node版本没有必然关系。切换node版本后，之前装的全局包大多还能用，但原生模块可能需要重新编译。

第二，离线环境使用npm安装依赖时，如果没有内网镜像，npm install会卡在下载阶段。一个可行的做法是在联网机器上先执行npm pack或者用npm cache把依赖包缓存好，拷贝到离线机器后使用npm install --cache离线安装。更省事的方式是配置内网npm私服，让npm install在内网内完成下载。

4. settings.txt和系统环境变量的关键细节

4.1 settings.txt字段逐项拆解

settings.txt虽然只有几行，但每一项都对应一种行为。结合我这次离线安装的经验，整理了一个字段说明表：

在手动创建settings.txt时，最容易写错的是root和path的路径分隔符。Windows环境下路径可以写反斜杠，也可以写正斜杠，但不要混用。arch: 64这行也很重要，如果系统是64位却把arch漏掉，nvm在下载或验证node版本时可能默认使用32位包，导致安装后node无法运行。

4.2 环境变量设计的巧妙之处

nvm-windows的环境变量设计，我觉得是整个工具最值得学习的地方。它没有让每个node版本直接写进Path，而是引入了一个“中转目录”的概念。Path里永远只有D:\nodejs这一个目录，但这个目录本身不是一个实体文件夹，而是一个符号链接。切换版本时，nvm做的事情只是把符号链接从D:\nvm\v16.20.2改指向D:\nvm\v18.20.4，Path完全不用动。

这样做的好处非常明显：不管开几个终端、开了多少个进程，只要符号链接位置不变，它们看到的node版本就是一致的。对比手动管理PATH的做法，每切换一次版本就要改一次系统环境变量，改完还得重启终端，而且多个终端之间版本不一致的情况很难避免。nvm把“版本切换”从一个全局配置变更，变成了一个目录链接变更，效率和稳定性都高了一个量级。

4.3 PATH顺序对node版本解析的影响

如果这台机器以前装过官方node独立安装包，那么系统Path里大概率残留了一条C:\Program Files\nodejs\。这条路径如果排在D:\nodejs前面，那么即使nvm已经把符号链接指向了正确版本，系统在执行node命令时依然会先命中旧目录，导致node -v显示旧版本。

排查这个问题最直接的方式是Windows的where命令：

where node

它会按Path里的顺序打印出所有可执行文件的完整路径，排在最上面的就是当前实际生效的node。如果第一行是C:\Program Files\nodejs\node.exe，说明旧路径还在并且排在前面；如果第一行是D:\nodejs\node.exe，说明nvm接管成功。解决办法是在Path里把%NVM_SYMLINK%和%NVM_HOME%挪到列表最前面，或者直接把旧node的路径整条删掉。卸载旧node的过程最好在控制面板里完成，手动删除残留目录有风险，可能会影响其他依赖旧路径的软件。

5. nvm多版本切换的底层机制与日常操作

5.1 切换版本时底层到底做了什么

在Windows平台，nvm use 16.20.2本质上执行了两个文件系统操作：先删除D:\nodejs这个已有的符号链接，再创建一个新的符号链接指向D:\nvm\v16.20.2。这个过程不需要修改Path、不需要重启机器，所以切换速度快到几乎感觉不到。

如果对符号链接这个概念不熟悉，我手动执行一次mklink就能看透它的本质。以管理员身份打开cmd，执行：

mklink /J D:\nodejs D:\nvm\v16.20.2

执行完，D盘根目录会出现一个名为nodejs的文件夹，但它的图标和普通文件夹不同，打开后看到的是v16.20.2目录的全部内容。这个“文件夹”不占用额外空间，它只是指向真实目录的快捷方式，但对系统和命令行工具来说，它看起来就是一个真实的node安装目录。

Linux平台实现方式不一样。nvm不是创建符号链接，而是直接修改当前shell的PATH环境变量，把$NVM_DIR/versions/node/v16.20.2/bin置顶，让shell在查找命令时优先命中nvm管理的版本。这种实现有一个特点：每个新终端都要重新加载一次nvm脚本，所以~/.bashrc里必须有source nvm.sh那行配置，否则新终端里nvm命令会消失。

5.2 高频命令速查

多版本管理的日常操作集中在少数几个命令上，整理如下：

离线环境下，nvm install和nvm ls-remote这两个命令尽量别碰。执行nvm install时，如果网络不通会长时间卡在下载阶段，有的版本甚至不会自动超时。正确的做法就是第3章讲的手动放置目录，先放目录、再nvm use激活。nvm ls-remote则完全依赖网络，离线时执行结果为空或直接卡死，没有实际用途。

5.3 一个实际的版本切换场景

我这次维护的两个项目，一个用了node-sass这个老掉牙的原生模块，在node 18上编译必挂，只能跑在node 14上；另一个项目则是Vite 5，要求node 18以上。两个项目在同一台机器上交替开发，每天要切换好几次。

实际操作流程比想象中顺手。先打开项目A的目录，执行nvm use 14.21.3，node版本立即切换，接着正常npm run dev，所有node-sass相关的编译都能通过。切换到项目B时，执行nvm use 18.20.4，然后在新开的终端里启动Vite。需要注意的是，node版本切换后，如果项目里的node_modules是安装在其他版本下的，最好删除后重新执行npm install，否则一些原生模块会因为二进制不兼容而报各种奇怪的错。对于node-sass这种旧依赖，建议在package.json里固定node版本范围，或者在项目根目录写明.nvmrc，nvm后续版本已经支持自动读取这个文件来切换版本，减少人为操作失误。

6. 实测中的疑难杂症与完整排查链路

6.1 nvm use报“symlink creation failed”

这次实测中遇到的第一个拦路虎就是这个问题。在普通权限的cmd里执行nvm use 16.20.2，系统直接报“symlink creation failed”，切换失败。

先排查了D:\nodejs目录情况。原来这台机器之前手动创建过一个D:\nodejs文件夹，而且里面还有残留文件。nvm切换版本时，需要删除这个旧目录再创建符号链接，如果它里面内容不为空，删除动作就会被拒绝。把D:\nodejs里面的内容备份后清空，再次执行nvm use，问题依旧。

继续排查发现，当前终端是普通用户权限，没有以管理员身份运行。nvm创建的虽然看起来像Junction目录链接，但部分版本内部实现使用的创建方式在某些环境配置下仍需要管理员权限。换成管理员身份打开cmd执行nvm use 16.20.2，切换成功，node -v正确输出目标版本。

这个坑的排查链路总结如下：

• 排查点1：D:\nodejs是否已存在且非空
• 排查点2：cmd是否以管理员身份运行
• 排查点3：D:\nvm目录是否有完全控制权限
• 排查点4：磁盘格式是否为NTFS（FAT32不支持符号链接）

6.2 PowerShell执行npm时报“无法加载文件npm.ps1”

在PowerShell里执行npm命令，报错内容是：“无法加载文件 npm.ps1，因为在此系统上禁止运行脚本”。这个报错第一次遇到时容易懵，因为npm本身没问题，node也能跑，纯粹是PowerShell执行策略在拦截npm的脚本包装器。

原因在于Windows PowerShell的ExecutionPolicy默认是Restricted，禁止执行任何.ps1脚本文件。npm在Windows下通过npm.ps1这个PowerShell脚本对外提供服务，于是被一并拦截。解决的思路有两种：

一是在管理员PowerShell里执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这是把当前用户的执行策略改为“本地脚本可运行，远程脚本需要签名”，安全性足够，日常使用推荐这种。二是干脆不用PowerShell执行npm，改用cmd窗口。两种方式实测都能跑通，但建议顺手把执行策略改掉，避免以后在PowerShell里处理各种脚本时反复踩雷。

6.3 切换版本后node -v还是旧版本的排查

另一台机器上遇到的问题是，执行nvm use 18.20.4后，node -v依然输出系统之前安装的v14。看起来像是nvm切换失效，但nvm current又显示当前已经是18.20.4，两者自相矛盾。

用where node命令一查，问题立刻清楚了。输出结果第一行是C:\Program Files\nodejs\node.exe，第二行才是D:\nodejs\node.exe。也就是说，系统里存在两个node入口，PATH列表里旧node的路径排在前面，导致node命令优先命中旧版本。nvm current显示的是nvm管理的版本，但shell实际执行的文件是另一个。解决办法有两个：要么在系统设置里把%NVM_SYMLINK%和%NVM_HOME%挪到PATH最前面，要么把C:\Program Files\nodejs这条残留路径删掉。

这个案例说明，nvm切换失败不一定是nvm本身的问题，很大概率是旧环境残留和PATH顺序在作祟。遇到版本没切换的情况，先不要急着重装nvm，按where node输出结果逐条检查，多数都能定位到具体原因。

6.4 离线环境执行nvm install卡死的正确处理

在线环境用惯了nvm install的人，到离线环境很容易习惯性敲这个命令。我在一台机器上试过一次，输入nvm install 16.20.2后画面卡在“downloading node.js version 16.20.2...”，等了五分钟没有反应，最终用Ctrl+C强制终止。这是因为nvm在向node_mirror配置的地址发起下载请求，但网络不通，底层并不会主动快速超时。

正确的处理方式不需要等待，直接开新终端或终止当前命令，走手动放置目录的方案。在准备工作充分的前提下，整个过程不到两分钟：解压zip、改目录名、移动到root目录、nvm use激活。手动放置不会破坏nvm的版本管理状态，nvm list能看到对应版本。有一点需要留意，不要同时执行nvm install又手动放置同一个版本，避免目录被覆盖或产生冲突。

6.5 实测后的几个操作习惯建议

几次离线安装下来的经验，让我形成了几个固定的操作习惯，对后来人应该有帮助：

习惯一，备份一套完整的nvm目录。在联网机器上装好nvm和所有需要的node版本后，把整个D:\nvm目录拷到U盘。到了新机器直接解压、配置环境变量、跑nvm list，所有版本直接可用，连手动放置都省了。

习惯二，先改settings.txt再碰环境变量。无论什么平台，先确保配置文件的root和path正确，再设置系统环境变量。顺序反了可能出现nvm已经装了、环境变量也配了，但nvm找不到版本目录的诡异情况。

习惯三，验证环境时不要只执行node -v。建议把nvm current、where node、npm -v三个命令一并执行，一次性确认nvm状态、node解析路径和npm可用性。只验证一个点，很容易漏掉PATH顺序残留问题。

习惯四，离线机器上把node版本目录做成只读不是好主意。虽然版本文件夹一般不改动，但后续如果要在该目录下装全局npm包，还是需要写权限。普通用户权限下能正常使用，就不要画蛇添足改权限。

最后说点个人体会。这次离线装nvm让我意识到，理解工具的目录结构和工作原理，比死记一批命令重要得多。只要搞明白nvm的root目录下每个vX.X.X目录代表一个可用版本、D:\nodejs只是一个可变的符号链接，就算没有网络、没有安装脚本，也能手动搭出一套完整的多版本Node环境。跳出“必须有安装器才能装软件”的惯性思维之后，无论在线还是离线，很多环境配置问题都能找到更灵活、更可控的解法。