Node.js 开发环境配置指南

> 分类：环境配置 | 平台：macOS + Linux | 难度：⭐⭐

## 目标环境

完成本文后，你将拥有：

| 工具 | 用途 | 默认版本 |
|------|------|----------|
| nvm | Node.js 版本管理 | latest |
| Node.js | JavaScript 运行时 | v22 LTS |
| npm | 包管理器（内置） | v10+ |
| pnpm | 高效包管理器 | v10+ |

![Node.js 环境架构](https://mrdoc.wangziheng.vip/media/202605/2026-05-16_182053_6394880.8232828113996877.png)

## 系统要求

- **macOS**：10.15+ (Catalina 及以上)
- **Linux**：主流发行版（Ubuntu 20.04+ / Debian 11+ / CentOS 8+）
- **必需工具**：`curl` 或 `wget`、`git`

```bash
# 检查基础工具
curl --version && git --version
```

## 安装步骤

### 1. 安装 nvm

nvm（Node Version Manager）允许你在同一台机器上安装和切换多个 Node.js 版本。

```bash
# 官方安装脚本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
```

安装完成后，重新加载 Shell 配置：

```bash
source ~/.bashrc    # Bash 用户
source ~/.zshrc     # Zsh 用户
```

验证安装：

```bash
nvm --version
# 输出：0.40.3
```

### 2. 安装 Node.js

**安装最新 LTS 版本（推荐）：**

```bash
nvm install --lts
```

**安装指定版本：**

```bash
nvm install 22
nvm install 18
```

**切换版本：**

```bash
nvm use 22
nvm use 18
```

**设置默认版本：**

```bash
nvm alias default 22
```

### 3. 安装 pnpm

pnpm 比 npm 更快、更节省磁盘空间（使用硬链接共享依赖）。

```bash
npm install -g pnpm
```

配置 pnpm 自动安装 Node.js（可选，与 nvm 共存时无需此步）：

```bash
pnpm setup
```

![终端安装过程](https://mrdoc.wangziheng.vip/media/202605/2026-05-16_182054_2596860.9185857022987782.png)

## 验证安装

依次执行以下命令，确认所有工具安装正确：

```bash
node -v     # v22.x.x
npm -v      # 10.x.x
pnpm -v     # 10.x.x
nvm --version  # 0.40.x
```

快速创建一个测试项目：

```bash
mkdir hello-node && cd hello-node
pnpm init
pnpm add express
node -e "console.log('Node.js is ready! 🚀')"
```

## 常见问题 FAQ

### Q: `nvm: command not found`

**原因**：Shell 配置未生效。

**解决**：

```bash
# 手动添加到 ~/.bashrc 或 ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
```

然后 `source ~/.bashrc`。

### Q: 切换 Node 版本后全局包丢失

**原因**：nvm 的全局包按 Node 版本隔离。

**解决**：重新安装全局包，或使用 pnpm 管理全局工具：

```bash
nvm use 22
npm install -g pnpm typescript
```

### Q: `pnpm: command not found`

**原因**：全局 bin 目录不在 PATH 中。

**解决**：

```bash
pnpm setup    # 自动添加 PATH
source ~/.bashrc
```

### Q: npm 安装速度慢

**解决**：使用国内镜像：

```bash
npm config set registry https://registry.npmmirror.com
pnpm config set registry https://registry.npmmirror.com
```

### Q: 权限错误 `EACCES`

**解决**：不要使用 `sudo npm install -g`，改用 nvm 管理的 Node（无需 sudo）：

```bash
nvm use default
npm install -g <package>   # 无需 sudo
```

## 卸载 / 清理

### 卸载特定 Node 版本

```bash
nvm uninstall 18
```

### 卸载 nvm

```bash
rm -rf "$NVM_DIR"
# 然后删除 ~/.bashrc / ~/.zshrc 中的 nvm 相关行
```

### 清理 npm 缓存

```bash
npm cache clean --force
pnpm store prune
```

---

> 💡 **提示**：建议始终使用 nvm 管理 Node.js，避免系统包管理器安装导致的权限和版本问题。