Node.js 环境配置

当前推荐使用 Node.js 22 LTS 版本，原生支持 ES Module、fetch API、WebSocket 客户端、node:test 测试框架等现代特性。

Node.js 安装

官方安装包

访问 Node.js 官网下载对应系统的安装包：

官网地址：https://nodejs.org/
LTS 版本：长期支持版，稳定可靠
Current 版本：最新特性版，适合尝鲜

版本管理工具

nvm（Node Version Manager）

推荐使用 nvm 管理多个 Node.js 版本：

bash

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 安装最新 LTS 版本
nvm install --lts

# 安装指定版本
nvm install 22

# 切换版本
nvm use 22

# 查看已安装版本
nvm ls

# 查看可安装版本
nvm ls-remote

n（另一个版本管理工具）

bash

# 全局安装 n
npm install -g n

# 安装最新版本
n latest

# 安装 LTS 版本
n lts

# 安装指定版本
n 22

# 切换版本
n

fnm（Fast Node Manager）- 推荐

fnm 基于 Rust 构建，启动速度比 nvm 快 40 倍以上，跨平台支持：

bash

# macOS 安装
brew install fnm

# Linux 安装
curl -fsSL https://fnm.vercel.app/install | bash

# Windows 安装
winget install Schniz.fnm

# 安装 LTS 版本
fnm install --lts

# 安装指定版本
fnm install 22

# 使用指定版本
fnm use 22

# 设置默认版本
fnm default 22

# 配置 shell 自动切换（添加到 .zshrc / .bashrc）
eval "$(fnm env --use-on-cd)"

验证安装

bash

# 查看 Node.js 版本
node -v

# 查看 npm 版本
npm -v

# 查看 Node.js 安装路径
which node

# 查看 npm 安装路径
which npm

npm 配置

镜像源配置

由于网络原因，建议配置国内镜像源：

bash

# 查看当前镜像源
npm config get registry

# 设置淘宝镜像源
npm config set registry https://registry.npmmirror.com

# 设置官方镜像源
npm config set registry https://registry.npmjs.org

# 使用 nrm 管理镜像源
npm install -g nrm
nrm ls           # 查看所有镜像源
nrm use taobao   # 切换到淘宝镜像
nrm test         # 测试镜像源速度

npm 配置文件

npm 配置文件位置：

用户级：~/.npmrc
项目级：项目根目录/.npmrc
全局级：$PREFIX/etc/npmrc

常用配置项：

bash

# 查看所有配置
npm config list

# 设置配置项
npm config set <key> <value>

# 删除配置项
npm config delete <key>

# 常用配置
npm config set registry https://registry.npmmirror.com  # 镜像源
npm config set prefix "~/.npm-global"                   # 全局安装路径
npm config set cache "~/.npm-cache"                     # 缓存路径

环境变量配置

将全局安装的包添加到 PATH：

bash

# 编辑 ~/.bashrc 或 ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# 使配置生效
source ~/.bashrc
# 或
source ~/.zshrc

开发环境配置

编辑器推荐

VS Code：轻量级，插件丰富
WebStorm：功能强大的 IDE
Sublime Text：轻量快捷

VS Code 必备插件

ESLint：代码规范检查
Prettier：代码格式化
Node.js Tools：Node.js 开发工具
npm Intellisense：npm 包自动补全
Path Intellisense：路径自动补全
Bracket Pair Colorizer：括号匹配高亮

Node.js 调试配置

在项目根目录创建 .vscode/launch.json：

json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/app.js"
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Process",
      "port": 9229
    }
  ]
}

常见问题

权限问题

在 macOS/Linux 上避免使用 sudo：

bash

# 创建全局安装目录
mkdir ~/.npm-global

# 配置 npm 使用新目录
npm config set prefix '~/.npm-global'

# 添加到 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

清理 npm 缓存

bash

# 清理缓存
npm cache clean --force

# 验证缓存
npm cache verify

重新安装依赖

bash

# 删除 node_modules
rm -rf node_modules

# 删除 package-lock.json
rm package-lock.json

# 重新安装
npm install

环境检查清单

Node.js 22+ 开发新特性

原生 --watch 模式

无需安装 nodemon，Node.js 22+ 原生支持文件监视：

bash

# 监视文件变更并自动重启
node --watch app.js

# 监视指定路径
node --watch-path=./src app.js

# 配合 --env-file 使用
node --watch --env-file=.env app.js

原生 TypeScript 支持

Node.js 22.6+ 支持直接运行 TypeScript 文件（仅移除类型注解）：

bash

# Node.js 22.6 - 23.5
node --experimental-strip-types app.ts

# Node.js 23.6+ 默认启用
node app.ts

# 禁用类型剥离（如果需要）
node --no-experimental-strip-types app.js

--env-file 环境变量文件

Node.js 20.6+ 内置支持 .env 文件，无需 dotenv 库：

bash

# 加载 .env 文件
node --env-file=.env app.js

# 加载不同环境的配置
node --env-file=.env.production app.js
node --env-file=.env.development app.js

--run 命令

Node.js 23+ 稳定的 --run 命令，替代 npm run：

bash

# 运行 package.json 中的脚本
node --run build
node --run test
node --run dev

权限模型

Node.js 22.13+ 权限模型已稳定，增强安全性：

bash

# 启用权限模型
node --permission app.js

# 允许文件系统读取
node --allow-fs-read=./data app.js

# 允许网络访问
node --allow-net=api.example.com:443 app.js