Node.js 安装与配置指南
Node.js 安装与配置指南
当前 LTS：v24.15.0Current：v25.9.0
一、安装 Node.js
1.1 版本管理器（官方推荐）
支持多版本共存与切换，适合开发环境。
nvm：
| 平台 | 安装 |
|---|---|
| Windows | 下载 nvm-windows 安装后重启终端 |
| macOS / Linux | curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash |
nvminstall24# 安装 Node 24.xnvm use24# 切换到 Node 24.xnvmaliasdefault24# 设为默认版本nvm list# 查看已安装版本nvminstall<version># 安装指定版本nvm use<version># 切换版本fnm（Rust 编写，速度更快）：
| 平台 | 安装 |
|---|---|
| Windows | winget install Schniz.fnm |
| macOS / Linux | curl -fsSL https://fnm.vercel.app/install | bash |
fnminstall24fnm use241.2 官方安装包
前往 Node.js 官网下载页 下载对应平台安装包：
| 平台 | 格式 |
|---|---|
| Windows | 安装程序（.msi）或 独立文件（.zip） |
| macOS | 安装包（.pkg） |
| Linux | 手动解压（见下方） |
Linux 手动安装：
mkdir~/optwgethttps://nodejs.org/dist/v24.15.0/node-v24.15.0-linux-x64.tar.xztar-xvfnode-v24.15.0-linux-x64.tar.xz-C~/optmv~/opt/node-v24.15.0-linux-x64 ~/opt/node配置环境变量，在~/.profile末尾追加：
exportNODE_HOME=$HOME/opt/nodeexportPATH=$PATH:$NODE_HOME/bin执行source ~/.profile或重启系统生效。
1.3 系统包管理器
# Windows (Chocolatey)chocoinstallnodejs# macOS (Homebrew)brewinstallnode# Linux (NodeSource 仓库)curl-fsSLhttps://deb.nodesource.com/setup_current.x|sudo-Ebash-sudoapt-getinstall-ynodejs1.4 Docker
dockerpull node:24-alpinedockerrun-it--rm--entrypointshnode:24-alpinenode-v# v24.15.0npm-v# 11.12.1二、配置环境
2.1 安装包管理器
npm 随 Node.js 自带，按需安装其他包管理器：
npminstall-gnpm# 升级 npm 自身npminstall-gpnpm# 安装 pnpmnpminstall-gyarn# 安装 yarnnpminstall-gcnpm# 安装 cnpm（淘宝定制客户端，部分场景需要）2.2 切换国内镜像
国内网络环境下，建议将默认源切换为淘宝镜像：
npmconfigsetregistry https://registry.npmmirror.comnpmconfigsetdisturl https://npmmirror.com/mirrors/nodepnpmconfigsetregistry https://registry.npmmirror.compnpmconfigsetdisturl https://npmmirror.com/mirrors/nodeyarnconfigsetregistry https://registry.npmmirror.comyarnconfigsetdisturl https://npmmirror.com/mirrors/node
disturl控制二进制包（如 node-sass、esbuild 等）的下载源，不配置会走官方源导致安装失败。
使用 nrm 快速切换镜像源：
npx nrm use taobao# 切换到淘宝源npx nrm usenpm# 切换回官方源2.3 统一目录管理
将所有包管理器的全局包和缓存集中到同一目录，便于管理。
创建目录：
:: Windows mkdir D:\web-pm\npm mkdir D:\web-pm\pnpm mkdir D:\web-pm\yarn# macOS / Linuxmkdir-p~/web-pm/npm ~/web-pm/pnpm ~/web-pm/yarn配置路径：
:: Windows npm config set prefix D:\web-pm\npm\global npm config set cache D:\web-pm\npm\cache pnpm config set store-dir D:\web-pm\pnpm\store pnpm config set global-dir D:\web-pm\pnpm\global pnpm config set global-bin-dir D:\web-pm\pnpm\global\bin yarn config set cache-folder D:\web-pm\yarn\cache yarn config set global-folder D:\web-pm\yarn\global# macOS / Linuxnpmconfigsetprefix ~/web-pm/npm/globalnpmconfigsetcache ~/web-pm/npm/cachepnpmconfigsetstore-dir ~/web-pm/pnpm/storepnpmconfigsetglobal-dir ~/web-pm/pnpm/globalpnpmconfigsetglobal-bin-dir ~/web-pm/pnpm/global/binyarnconfigsetcache-folder ~/web-pm/yarn/cacheyarnconfigsetglobal-folder ~/web-pm/yarn/global配置环境变量：
Windows 将以下路径添加到系统 PATH：
D:\web-pm\npm\global D:\web-pm\pnpm\global\bin D:\web-pm\yarn\global\node_modules\.binmacOS / Linux：
# zshecho'export PATH="$HOME/web-pm/npm/global/bin:$HOME/web-pm/pnpm/global/bin:$HOME/web-pm/yarn/global/node_modules/.bin:$PATH"'>>~/.zshrcsource~/.zshrc# bashecho'export PATH="$HOME/web-pm/npm/global/bin:$HOME/web-pm/pnpm/global/bin:$HOME/web-pm/yarn/global/node_modules/.bin:$PATH"'>>~/.bashrcsource~/.bashrc目录结构：
web-pm/ ├─ npm/ │ ├─ global/ 全局包 │ └─ cache/ 缓存 ├─ pnpm/ │ ├─ global/ 全局包 │ └─ store/ 缓存仓库 └─ yarn/ ├─ global/ 全局包 └─ cache/ 缓存三、验证
node-v# 期望: v24.x.xnpm-v# 期望: 11.x.xnpmconfig get registry# 期望: https://registry.npmmirror.com/npmconfig get disturl# 期望: https://npmmirror.com/mirrors/nodenpmconfig get prefix# Windows: D:\web-pm\npm\global | Linux: ~/web-pm/npm/globalpnpmconfig get registrypnpmstore pathpnpmconfig get global-diryarnconfig get registryyarncachediryarnglobaldir四、常见问题
npm run dev 报错 esbuild 相关
npmconfig get ignore-scripts# 如果返回 true，执行：npmconfigsetignore-scriptsfalsenodenode_modules/esbuild/install.jsnpmrun dev全局安装报 EACCES 权限错误
原因：npm 默认全局目录需要 sudo 权限。
解决：配置统一目录（见 2.3 节），将全局包安装到用户目录下即可避免。
nvm 切换版本后全局包丢失
nvm 的全局包按 Node 版本隔离，切换版本后需重新安装：
nvminstall24npminstall-gpnpmyarn# 重新安装全局包