前端开发环境搭建指南

适用于 macOS 系统，使用 Homebrew 安装 NVM，并配置 Node.js 与 pnpm

本文将指导你在 macOS 上通过 Homebrew 快速搭建一个现代化的前端开发环境，包括：

使用 Homebrew 安装 NVM
通过 NVM 管理 Node.js 版本
安装并配置 pnpm 作为包管理器

一、前提：安装 Homebrew（如未安装）

打开 终端（Terminal） 或 iTerm2，运行以下命令安装 Homebrew：

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

安装完成后，验证：

bash
brew --version

二、使用 Homebrew 安装 NVM

在终端中执行：

bash
brew install nvm

⚠️ 注意：Homebrew 安装的 nvm 需要手动配置 shell 环境变量。

配置 Shell（以 Zsh 为例，macOS 默认）

创建 NVM 目录（用于存放 Node 版本）：

bash
mkdir ~/.nvm

编辑 ~/.zshrc 文件：

bash
nano ~/.zshrc

在文件末尾添加以下内容：

bash
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"  # Apple Silicon (M1/M2/M3)
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"

💡 如果你使用的是 Intel 芯片的 Mac，请将路径中的 /opt/homebrew 替换为 /usr/local：

bash
[ -s "/usr/local/opt/nvm/nvm.sh" ] && \. "/usr/local/opt/nvm/nvm.sh"
[ -s "/usr/local/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/usr/local/opt/nvm/etc/bash_completion.d/nvm"

保存并退出（在 nano 中按 Ctrl+O → 回车 → Ctrl+X）
重新加载配置：

bash
source ~/.zshrc

验证 NVM 是否可用：

bash
nvm --version

三、通过 NVM 安装 Node.js

列出所有 LTS 版本：

bash
nvm list-remote --lts

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

bash
nvm install --lts

或指定版本（例如 20.x）：

bash
nvm install 20

设置默认 Node.js 版本：

bash
nvm use --lts
nvm alias default lts/*

验证安装：

bash
node -v
npm -v

三、配置 npm 与 pnpm 的仓库源（Registry）

在国内开发时，官方 npm registry（https://registry.npmjs.org/）速度较慢，推荐切换为 淘宝 NPM 镜像 或 npmmirror.com（原淘宝镜像官方域名）。

1. 查看当前 npm registry

bash
npm config get registry
# 默认输出：https://registry.npmjs.org/

2. 设置 npm 使用国内镜像

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

✅ 推荐使用 https://registry.npmmirror.com（由阿里维护，更稳定）

验证是否生效：

bash
npm config get registry
# 应输出：https://registry.npmmirror.com

3. 安装 pnpm（此时会走新 registry）

bash
npm install -g pnpm

4. 设置 pnpm 的 registry

pnpm 不直接读取 npm 的配置，需单独设置：

bash
pnpm set registry https://registry.npmmirror.com

验证：

bash
pnpm config get registry
# 或
pnpm get registry

💡 提示：你也可以通过 .npmrc 或 .pnpmrc 文件进行项目级或全局配置（见下文）

四、（可选）通过配置文件管理 registry

全局配置 npm

在用户目录创建或编辑 ~/.npmrc：

bash
echo "registry=https://registry.npmmirror.com" >> ~/.npmrc

全局配置 pnpm

pnpm 会读取 ~/.npmrc，但也可显式写入其配置：

bash
# pnpm 也会尊重 ~/.npmrc 中的 registry 设置
# 或者使用 pnpm 命令写入
pnpm set registry https://registry.npmmirror.com

📌 注意：pnpm 优先读取 ~/.npmrc，其次才是内部配置。

五、临时使用官方源（如发布包时）

若需临时切回官方源（例如 npm publish 必须用官方 registry）：

bash
# npm 临时指定 registry
npm install --registry https://registry.npmjs.org

# pnpm 临时指定 registry
pnpm install --registry https://registry.npmjs.org

或者使用别名快速切换（推荐）：

在 ~/.zshrc 中添加：

bash
alias cnpm="npm --registry=https://registry.npmmirror.com"
alias cpm="pnpm --registry=https://registry.npmmirror.com"

然后你可以用 cnpm i 或 cpm add 快速使用镜像。

六、验证依赖安装速度

测试安装一个常用包（如 vite）：

bash
mkdir test-registry && cd test-registry
pnpm init
pnpm add -D vite

观察下载速度是否明显提升。

七、可选：优化 pnpm 配置

启用自动安装 peerDependencies（提升兼容性）：

bash
pnpm set auto-install-peers true
pnpm set strict-peer-dependencies false

八、测试开发环境

创建测试项目：

bash
mkdir test-pnpm-app
cd test-pnpm-app
pnpm init
pnpm add -D vite

检查是否生成 package.json 和 pnpm-lock.yaml，确认环境正常。

九、常见问题

Q: `nvm: command not found`？

请确认：

已正确编辑 ~/.zshrc
路径 /opt/homebrew/opt/nvm/nvm.sh（Apple Silicon）或 /usr/local/opt/nvm/nvm.sh（Intel）确实存在
执行了 source ~/.zshrc

可通过以下命令检查路径是否存在：

bash
ls /opt/homebrew/opt/nvm/nvm.sh      # Apple Silicon
ls /usr/local/opt/nvm/nvm.sh         # Intel

Q: 安装 pnpm 后命令找不到？

通常是因为全局 bin 路径未加入 PATH。但通过 NVM 安装的 npm 默认会把全局命令放在用户目录下，一般无需额外配置。若仍报错，可尝试：

bash
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

✅ 恭喜！你已在 macOS 上成功搭建基于 NVM + Node.js + pnpm 的前端开发环境。

Happy Coding! 🍏✨

🔗 镜像参考：

官方文档：https://npmmirror.com

GitHub：https://github.com/cnpm/npmmirror.com

目录