Node.js 开发环境配置 - 码剑客

从零配置 Node.js 开发环境：Windows 与 Linux/macOS 安装、nvm/fnm 多版本切换、npm 换源、pnpm 启用、工程创建与常见报错排查。

Node.js 20 LTS / 22 LTS更新于 2026-10-29共 29 条

安装与版本管理

Windows 上安装 Node.js LTS，安装后需重开终端让 PATH 生效

# Windows（官方 LTS 安装包走 winget）
winget install OpenJS.NodeJS.LTS

macOS 用 Homebrew，Ubuntu 用 NodeSource 源安装指定大版本

# macOS
brew install node@20
# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Windows 安装 fnm 作为版本管理器（比 nvm-windows 更快，无需管理员权限）

winget install Schniz.fnm

安装并切换到 Node 20，列出本机已安装版本

fnm install 20
fnm use 20
fnm list

需在 PowerShell 配置中启用 fnm env --use-on-cd，才能进入目录时自动切换版本

用 nvm 安装并切换版本，同时设为默认版本

# macOS / Linux
nvm install 20
nvm use 20
nvm alias default 20

启用 pnpm，推荐用 corepack 锁定团队内的 pnpm 版本

corepack enable pnpm
npm install -g pnpm@9

镜像源与代理

切换 npm 到国内镜像源，并确认当前生效源

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

pnpm 使用独立配置，需要单独设置镜像源

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

写入项目根目录 .npmrc，只对当前项目生效，避免影响其他项目

registry=https://registry.npmmirror.com
strict-ssl=true

公司代理或本地代理环境下配置 npm 代理

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

关闭代理时清理代理配置，否则会出现一直超时

npm config delete proxy
npm config delete https-proxy

环境变量

确认 Node/npm 版本与全局安装目录

node -v
npm -v
npm config get prefix

查看全局 node_modules 路径，排查全局包问题时使用

npm root -g

设置 NODE_ENV，Windows 用 setx，macOS/Linux 写入 shell 配置

# Windows PowerShell（永久生效，需重开终端）
setx NODE_ENV development
# macOS / Linux
echo 'export NODE_ENV=development' >> ~/.zshrc

确认 npm 全局 bin 目录已在 PATH 中，否则全局命令会提示找不到

# Windows
echo %APPDATA%\npm
# macOS / Linux
echo $PATH | tr ":" "\n" | grep npm

创建工程与验证

用 Vite 创建 Vue + TypeScript 工程

npm create vite@latest my-app -- --template vue-ts

初始化最小工程并直接运行入口文件

npm init -y
node index.js

安装依赖并启动本地开发服务器

npm install
npm run dev

生产构建后用 preview 验证产物是否正常

npm run build
npm run preview

打印当前 Node 版本与平台，用于确认实际生效的运行时

node -e "console.log(process.version, process.platform)"

编辑器与插件

命令行安装 Vue、ESLint、Prettier 扩展，团队可写进初始化脚本

code --install-extension Vue.volar
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode

在仓库根目录固定 Node 版本，配合 nvm use 自动切换

echo 20 > .nvmrc

声明 engines 字段，安装时提示不兼容的 Node 版本

npm pkg set engines.node=">=20"

常见问题排查

版本不对时先确认命令实际指向哪个可执行文件

# Windows
where node
# macOS / Linux
which -a node

高危

依赖安装异常或校验失败时清理 npm 缓存

npm cache verify
npm cache clean --force

清理缓存后首次安装会重新下载，网络差时会明显变慢

PowerShell 提示无法加载 npm.ps1 时，放宽当前用户的执行策略

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

公司自签证书导致 UNABLE_TO_VERIFY_LEAF_SIGNATURE 时临时关闭校验

npm config set strict-ssl false

仅用于内网环境，排查完请改回 true，避免中间人风险

开发服务器端口被占用时，先找到占用进程再决定是否结束

# Windows
netstat -ano | findstr :5173
# macOS / Linux
lsof -i :5173

Linux/macOS 全局安装报 EACCES 权限错误时，改用用户目录作为全局前缀

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc