Node.js安装部署避坑指南

很多新手在「nodejs安装」这一步就卡住了：官网下载慢、装完命令找不到、npm 报权限错、多项目版本冲突。这篇文章把我踩过的坑一次性讲清楚，从安装方式选择到部署上线，给你一套可复用的流程。

一、先选安装方式，别急着下安装包

Node.js 的安装方式主要有三种，选错了后面全是坑：

• 官网安装包（.msi / .pkg）：图形化、最简单，适合纯新手，但版本切换麻烦。
• nvm / nvm-windows：版本管理器，推荐给所有需要维护多个项目的开发者。
• 包管理器（Homebrew / apt / winget）：适合习惯命令行的用户，升级方便。

我的建议很直接：只要你不是只跑一个 demo，就用 nvm。项目 A 要 Node 16，项目 B 要 Node 20，用安装包你只能反复卸载重装。

二、Windows 下用 nvm-windows 安装

先去 GitHub 下载 nvm-setup.exe，安装时注意两点：安装路径不要有空格和中文；它会问你要不要接管已有的 Node，如果之前装过，建议先卸载干净再装。

nvm version
nvm install 20.11.1
nvm use 20.11.1
node -v
npm -v

如果 nvm use 报错「exit status 1」，通常是权限问题，用管理员身份打开终端再执行即可。

三、macOS / Linux 用 nvm 脚本安装

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm alias default lts/*

国内网络访问 GitHub 慢的话，可以改用 Gitee 镜像，或者给终端配置代理。安装完记得 nvm alias default，否则新开终端会回到系统默认版本。

四、必坑指南：这 6 个问题最容易翻车

1. 命令找不到（command not found）

装完 node -v 提示找不到，九成是环境变量没配好。Windows 检查系统变量 Path 里有没有 Node 安装目录；macOS/Linux 检查 ~/.bashrc 或 ~/.zshrc 是否加载了 nvm 脚本。改完记得重开终端。

2. npm 全局安装报 EACCES 权限错误

不要用 sudo npm install -g，会把文件权限搞乱。正确做法是改 npm 全局目录：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

3. 淘宝镜像配了但装包还是慢

现在推荐用 npmmirror，注意只配 registry 即可，不要乱改其他源：

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

4. 多版本切换后全局包消失

这是正常现象。每个 Node 版本有独立的全局包目录，切换版本后需要重新安装全局工具，比如 npm i -g pnpm yarn。

5. node-sass / sharp 等原生模块编译失败

这类包依赖本地编译环境。Windows 需要安装 Visual Studio Build Tools 和 Python；Linux 需要 build-essential。更省事的办法是换用纯 JS 实现的替代包，比如用 dart-sass 替代 node-sass。

6. 生产环境直接用 root 跑 Node

部署时不要用 root 启动服务，一旦被攻破风险极大。建议创建专用用户，配合 pm2 做进程守护：

npm i -g pm2
pm2 start app.js --name my-api
pm2 save
pm2 startup

五、部署上线的几个实用建议

• 用 .nvmrc 锁定项目 Node 版本，团队协作不打架。
• 服务器上用 nvm install --lts 而不是追最新版，稳定性优先。
• 用 pm2 或 systemd 托管进程，别用 nohup node app.js & 裸跑。
• 配合 Nginx 做反向代理和 HTTPS，Node 只监听本地端口。
• 上线前执行 npm ci 而不是 npm install，保证依赖版本一致。

六、总结

「nodejs安装」本身不难，难的是环境隔离和后续维护。记住三条：用 nvm 管理版本、别用 sudo 装全局包、生产环境用 pm2 加普通用户。把这三点做好，后面 90% 的坑都能绕过去。