序言

本教程由「小荣的网络开发日志」实操整理编写，实操踩坑验证，内容真实可靠。

遇到操作问题可直接联系作者，转载需标注原文出处，禁止私自篡改商用。

承接网站、APP、小程序、各类脚本定制开发；

AI 编程教学、一对一项目全程陪跑，提供免费技术咨询。

联系方式： 微信：rongyaolg 电话：18375295913

1.1 一句话解释

Node.js 是一个可以让 JavaScript 脱离浏览器、直接在电脑上运行的工具。

打个比方：浏览器是 JavaScript 的"家"，网页里的 JavaScript 只能在浏览器里跑。而 Node.js 相当于给 JavaScript 盖了一座新房子，让它可以独立运行在电脑上，能干更多的事。

1.2 Node.js 能做什么

1.3 为什么前端开发必须装 Node.js

如果你准备学习前端开发（React、Vue、小程序等），Node.js 不是可选项，而是必需品。原因很简单：

• 创建项目需要 Node.js（npm create vite、npx create-react-app）
• 安装第三方库需要 Node.js（npm install）
• 本地运行项目需要 Node.js（npm run dev）
• 打包上线需要 Node.js（npm run build）

这些命令全部依赖 Node.js，没有它寸步难行。

💡 npm 是什么？ npm（Node Package Manager，Node 包管理器）随着 Node.js 一起安装。它像一个"应用商店"，你可以通过它下载别人写好的代码包，省去从零编写的麻烦。

二、为什么用 NVM 而不是直接安装

2.1 直接安装的问题

去 Node.js 官网下载安装包，一次只能装一个版本。但现实是：

• 公司老项目需要 Node.js 14
• 新项目需要 Node.js 18
• 最新教程用的是 Node.js 20

如果直接安装，你就得反复卸载重装，非常痛苦。

2.2 NVM 解决了什么

**NVM（Node Version Manager，Node 版本管理器）**可以让你在同一台电脑上安装和切换多个 Node.js 版本，一行命令搞定。

复制# 切换不同版本的 Node.js，只需一条命令：
nvm use 18    → 切换到 Node.js 18
nvm use 20    → 切换到 Node.js 20

✅ 推荐：使用 NVM 管理 Node.js 是当前国内前端开发的标准做法。绝大多数团队都会要求开发者通过 NVM 安装。

2.3 两个 NVM 的区别

由于 Windows 和 macOS 系统差异很大，NVM 有两个独立版本：

它们功能相同，只是实现不同，请按自己的系统选择对应章节。

三、Windows 安装 NVM

3.1 下载 nvm-windows

打开官方下载页面：

官方地址：https://github.com/coreybutler/nvm-windows/releases

在页面往下滑动中找到 Assets（资源文件），点击 nvm-setup.exe 下载。

3.2 运行安装程序

1. 双击下载好的 nvm-setup.exe，点击 Next。
2. 同意协议，点击 I Agree。
3. 选择 NVM 安装路径。

⚠️ 注意：安装路径中不能包含空格和中文字符！推荐使用默认路径 C:\Users\你的用户名\AppData\Roaming\nvm。

4. 选择 Node.js 的快捷方式路径（保持默认即可），点击 Next。
5. 点击 Install，等待完成。

3.3 验证 NVM 安装

安装完成后，打开 PowerShell 或 命令提示符 (CMD)。

💡 如何打开终端？ 按键盘 Win + R，输入 powershell 或 cmd，回车即可。

输入以下命令：

复制nvm version

如果看到类似 1.1.12 的版本号，说明 NVM 安装成功。

⚠️ 如果提示 "nvm 不是内部或外部命令"，请重启电脑后再试一次。如果仍然不行，参考常见问题排查。

四、macOS 安装 NVM

4.1 打开终端

在 Launchpad 中找到 终端（Terminal），或在 Spotlight（按 Command + 空格）中搜索"终端"。

4.2 安装 Homebrew（如果没有装过）

Homebrew 是 macOS 上的软件包管理器，类似一个命令行版的 App Store。有了它，安装和管理软件非常方便。

检查是否已安装 Homebrew：

复制brew --version

如果提示 command not found，说明没有安装。在终端中执行以下命令安装：

复制/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

官方地址：https://brew.sh

安装过程会提示输入电脑密码（输入时屏幕不会显示，这是正常的安全机制），耐心等待即可。

4.3 使用 Homebrew 安装 NVM

在终端中执行：

复制brew install nvm

官方地址：https://github.com/nvm-sh/nvm

4.4 配置 NVM 环境变量

安装完成后，需要让终端"认识" NVM。在终端执行：

复制# 创建 NVM 工作目录
mkdir ~/.nvm

# 编辑 shell 配置文件（macOS 默认使用 zsh）
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"' >> ~/.zshrc

💡 为什么这样做？ 每次打开终端时，系统会读取 ~/.zshrc 文件。我们把这些配置写进去，就能让 NVM 在每次打开终端时自动生效。

如果你是 Intel 芯片的 Mac（较老机型），将 /opt/homebrew 替换为 /usr/local：

复制echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/usr/local/opt/nvm/nvm.sh" ] && \. "/usr/local/opt/nvm/nvm.sh"' >> ~/.zshrc
echo '[ -s "/usr/local/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/usr/local/opt/nvm/etc/bash_completion.d/nvm"' >> ~/.zshrc

⚠️ 如何判断自己的 Mac 芯片类型？ 点击屏幕左上角苹果图标 → 关于本机 → 查看"处理器"或"芯片"。显示 M1/M2/M3/M4 的是 Apple 芯片，使用 /opt/homebrew；显示 Intel 的使用 /usr/local。

4.5 使配置生效

复制source ~/.zshrc

4.6 验证 NVM 安装

复制nvm --version

如果看到版本号（如 0.39.7），说明 NVM 已成功安装。

⚠️ 如果提示 command not found，先关闭终端重新打开再试。如果仍然不行，检查 ~/.zshrc 文件是否包含了上面的配置。

五、使用 NVM 安装 Node.js

以下步骤 Windows 和 macOS 通用，使用相同的命令。

5.1 查看可安装的 Node.js 版本

复制nvm list available

会列出所有可以安装的 Node.js 版本。通常我们关注 LTS 标记的版本。

5.2 安装 Node.js

推荐安装最新的 LTS 版本。以下以 Node.js 22 为例：

复制nvm install 22

等待下载和安装完成，NVM 会自动帮你搞定一切。

5.3 选择要使用的版本

复制nvm use 22

执行后终端会提示 Now using node v22.x.x，表示已切换到 Node.js 22。

💡 原理说明：NVM 在切换版本时，实际上是修改了系统路径，让终端找到不同版本的 Node.js。这个过程只在当前终端窗口生效，不会影响其他窗口。

5.4 查看已安装的版本

复制nvm list

前面带 * 的版本就是当前正在使用的。

六、配置 npm 国内镜像（必做）

6.1 为什么要配置镜像

npm 官方服务器在国外，国内直接访问速度很慢，甚至可能下载失败。我们需要把 npm 的下载源指向国内镜像站。

✅ 推荐：使用淘宝提供的 npm 镜像（由 npmmirror.com 维护），速度快且稳定。

6.2 配置镜像

复制npm config set registry https://registry.npmmirror.com

6.3 验证配置

复制npm config get registry

如果输出 https://registry.npmmirror.com，说明配置成功。

💡 以后想恢复默认怎么办？

复制npm config set registry https://registry.npmjs.org

七、验证安装是否成功

依次执行以下命令，确认一切正常：

7.1 检查 Node.js 版本

复制node -v

应该输出类似 v22.xx.xx 的版本号。

7.2 检查 npm 版本

复制npm -v

应该输出类似 10.x.x 的版本号。

八、常见问题排查

8.1 Windows：提示"nvm 不是内部或外部命令"

原因：环境变量没有生效。

解决方法：

1. 重启电脑（最简单有效的方法）。
2. 如果重启后仍然不行，手动检查环境变量：右键"此电脑" → 属性 → 高级系统设置 → 环境变量 → 系统变量 Path → 确认里面有 C:\Users\你的用户名\AppData\Roaming\nvm。

8.2 macOS：每次打开终端都要重新执行 `nvm use`

原因：没有设置默认版本。

解决方法：

复制nvm alias default 20

这样每次打开终端都会自动使用 Node.js 20。

8.3 npm install 报网络错误

原因：可能是网络问题或镜像没有配置成功。

解决方法：

1. 重新执行第六章的镜像配置。
2. 如果仍然失败，尝试关闭代理软件（VPN、Clash 等）后再试。
3. 检查网络连接是否正常。

8.4 macOS 安装时提示权限不足

解决方法：在命令前加 sudo，然后输入密码。

复制sudo brew install nvm

⚠️ 不推荐直接给 npm 全局安装加 sudo，这会带来安全风险。如果 npm 全局安装需要权限，参考以下解决方法：

复制mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

8.5 安装过程中杀毒软件报警

原因：nvm-windows 的安装包可能被某些杀毒软件误报。

解决方法：nvm-windows 是知名的开源项目，从官方 GitHub 下载的安装包是安全的。临时关闭杀毒软件的实时防护，安装完成后再开启。

九、NVM 常用命令速查

复制# 查看已安装的 Node.js 版本
nvm list

# 安装指定版本
nvm install 20

# 安装最新 LTS 版本
nvm install lts

# 切换版本
nvm use 18

# 查看当前版本
nvm current

# 设置默认版本
nvm alias default 20

# 卸载指定版本
nvm uninstall 14

十、总结

恭喜你完成了 Node.js 开发环境的搭建！来回顾一下你都做了什么：

现在你可以：

• 用 npm init 创建新项目
• 用 npm install 安装第三方库
• 用 npx create-react-app 创建 React 项目
• 用 npm create vite 创建 Vue 或 React 项目
• 用微信开发者工具开发小程序