Node.js 安装与配置指南

目录

1. Node.js 版本说明
2. 方式一：NodeSource 官方仓库（GPG 验证，推荐服务器端）
3. 方式二：nvm 版本管理器（推荐开发环境）
4. 方式三：官方预编译二进制包（GPG 验证）
5. 方式四：包管理器直接安装（不推荐）
6. npm 镜像源配置
7. 配置全局安装路径
8. 常见问题与排查

---

Node.js 版本说明

版本线	状态	说明
Node.js 22.x	✅ 当前 LTS	推荐生产环境使用（2026-04 进入 LTS）
Node.js 20.x	✅ LTS	长期支持至 2026-04
Node.js 18.x	⚠️ 即将 EOL	2025-04 停止维护
Node.js 23.x	🔄 当前开发版	非 LTS，适合尝鲜

生产环境建议使用当前 LTS 版本（偶数版）。如需切换版本建议使用 nvm。

---

方式一：NodeSource 官方仓库（GPG 验证，推荐服务器端）

NodeSource 是 Node.js 官方推荐的第三方仓库，提供 .deb / .rpm 包，支持 GPG 密钥验证，方便通过系统包管理器管理。

Ubuntu / Debian

# === 方法 A：使用 NodeSource 安装脚本（自动处理 GPG 密钥）===

# 安装 Node.js 22.x LTS（当前 LTS）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装 Node.js 20.x LTS
# curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# 安装后直接通过 apt 安装
sudo apt install -y nodejs

# 验证
node --version
npm --version

手动添加仓库（不执行脚本）

# 如果想手动控制，不跑远程脚本，可以按以下步骤

# 1. 安装依赖
sudo apt update
sudo apt install -y ca-certificates curl gnupg

# 2. 创建 keyrings 目录
sudo mkdir -p /etc/apt/keyrings

# 3. 下载并导入 NodeSource GPG 密钥
#    密钥指纹：1655A0AB68576280
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 4. 添加 NodeSource 仓库（以 Node.js 22.x 为例）
NODE_MAJOR=22
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] \
  https://deb.nodesource.com/node_${NODE_MAJOR}.x nodistro main" | \
  sudo tee /etc/apt/sources.list.d/nodesource.list

# 5. 安装
sudo apt update
sudo apt install -y nodejs

# 验证
node --version
npm --version

使用镜像加速（清华源）

NodeSource 官方源在国内可能较慢，可使用清华镜像替代。

# 1. 导入 GPG 密钥（同上）
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 2. 使用清华镜像源（Node.js 22.x）
NODE_MAJOR=22
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] \
  https://mirrors.tuna.tsinghua.edu.cn/nodesource/deb/node_${NODE_MAJOR}.x nodistro main" | \
  sudo tee /etc/apt/sources.list.d/nodesource.list

# 3. 安装
sudo apt update
sudo apt install -y nodejs

CentOS / RHEL / Fedora

# 1. 添加 NodeSource 仓库（以 22.x 为例）
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -

# 或手动添加
# sudo dnf install https://rpm.nodesource.com/node_22.x/nodesource-release-el9-1.noarch.rpm

# 2. 安装
sudo dnf install -y nodejs

# 验证
node --version
npm --version

---

方式二：nvm 版本管理器（推荐开发环境）

nvm（Node Version Manager）可以在用户目录下管理多个 Node.js 版本，无需 sudo，版本切换灵活。
安装过程中自动下载并验证 Node.js 官方发布的二进制包。

安装 nvm

# 使用官方安装脚本（从 GitHub 下载）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash

# 如果 GitHub 访问慢，使用 ghproxy.com 加速
# curl -o- https://ghproxy.com/https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc   # 或 source ~/.zshrc

安装 Node.js

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

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

# 安装指定版本
nvm install 22
nvm install 20.18.0

# 使用指定版本
nvm use --lts          # 使用 LTS
nvm use 20             # 使用 v20.x
nvm use 22             # 使用 v22.x

# 设置默认版本（新 shell 自动使用）
nvm alias default 22

# 查看已安装版本
nvm list

# 卸载版本
nvm uninstall 18

配置 nvm 镜像加速

nvm 默认从 Node.js 官方源下载二进制包，可配置镜像站加速。

# 在 ~/.bashrc 或 ~/.zshrc 中添加以下配置
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
# 或使用清华镜像
# export NVM_NODEJS_ORG_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/nodejs-release/

添加后重新加载 source ~/.bashrc，再执行 nvm install 即可从镜像站下载。

---

方式三：官方预编译二进制包（GPG 验证）

直接从 Node.js 官方下载预编译二进制包，手动验证 GPG 签名。
适合离线安装或需要完全控制安装路径的场景。

# === 以下步骤以 Node.js 22.14.0 LTS 为例，版本号请替换为最新 ===

# 1. 设定版本和架构
VERSION=v22.14.0
ARCH=linux-x64   # 或 linux-arm64（ARM 架构）

# 2. 下载 Node.js 二进制包
wget https://nodejs.org/dist/${VERSION}/node-${VERSION}-${ARCH}.tar.xz

# 下载签名文件
wget https://nodejs.org/dist/${VERSION}/SHASUMS256.txt
wget https://nodejs.org/dist/${VERSION}/SHASUMS256.txt.sig

# 3. 导入 Node.js 官方 GPG 公钥并验证签名
# 参考 Node.js 官方发布的密钥列表：https://github.com/nodejs/node#release-keys
# 常用密钥（以当前发布经理密钥为例）：
curl -fsSL https://github.com/nodejs/node/raw/main/src/node_release_keys.gpg \
  | gpg --import -

# 或逐个导入发布经理密钥：
# for key in \
#   4ED778F539E3634C779C87C6D7062848A1AB005C \
#   141F07595B7B3FFE74309A937405533BE57C7D57 \
#   74F12602B6F1C4E913FAA37AD3A89613643B6201 \
#   DD792F5973C6DE52C432CBDAC77ABFA00DDBF2B7 \
#   CC68F5A3106FF448322E48ED27F5E38D5B0A215F \
#   8FCCA16FEF1EF22B25B1CF9C0E5B6AE5C0C6E9C0 \
#   A4C0A90B2144C241F93F2071B3ED4F81864475A4 \
#   A48C2BEE680E841632CD5E39F5442CA622A25C29 \
#   4DE8FEBC3DA654155FDA2963F60A6B5473D9071E \
# ; do \
#   gpg --keyserver keyserver.ubuntu.com --recv-keys "$key"; \
# done

# 4. 验证签名
gpg --verify SHASUMS256.txt.sig SHASUMS256.txt

# 5. 验证文件校验和
grep "node-${VERSION}-${ARCH}.tar.xz" SHASUMS256.txt | sha256sum -c -

# 6. 解压并安装到 /usr/local
sudo tar -xJf node-${VERSION}-${ARCH}.tar.xz -C /usr/local --strip-components=1

# 7. 验证
node --version
npm --version

使用镜像加速下载

# 从镜像站下载替代官方源（以清华镜像为例）
VERSION=v22.14.0
ARCH=linux-x64

wget https://mirrors.tuna.tsinghua.edu.cn/nodejs-release/${VERSION}/node-${VERSION}-${ARCH}.tar.xz
wget https://mirrors.tuna.tsinghua.edu.cn/nodejs-release/${VERSION}/SHASUMS256.txt
wget https://mirrors.tuna.tsinghua.edu.cn/nodejs-release/${VERSION}/SHASUMS256.txt.sig

# GPG 验证步骤同上
gpg --verify SHASUMS256.txt.sig SHASUMS256.txt
grep "node-${VERSION}-${ARCH}.tar.xz" SHASUMS256.txt | sha256sum -c -

sudo tar -xJf node-${VERSION}-${ARCH}.tar.xz -C /usr/local --strip-components=1

---

方式四：包管理器直接安装（不推荐）

系统自带源中的 Node.js 版本通常较旧，不推荐用于开发。

# Ubuntu/Debian（版本可能很旧，如 12.x）
sudo apt install -y nodejs npm

# CentOS/RHEL
sudo dnf install -y nodejs npm

# 安装后往往需要额外配置 npm 权限，版本也非最新

---

npm 镜像源配置

配置 npm 镜像加速 npm install 包下载速度。

配置 npm 全局镜像源

# 查看当前源
npm config get registry

# 设置为淘宝 npm 镜像（推荐）
npm config set registry https://registry.npmmirror.com

# 设置为腾讯云 npm 镜像
# npm config set registry https://mirrors.cloud.tencent.com/npm/

# 设置为华为云 npm 镜像
# npm config set registry https://repo.huaweicloud.com/repository/npm/

# 设置为官方源（恢复默认）
# npm config set registry https://registry.npmjs.org/

使用 cnpm（备选方案）

# 安装 cnpm（淘宝 npm 镜像的客户端）
npm install -g cnpm --registry=https://registry.npmmirror.com

# 使用 cnpm 代替 npm
cnpm install <package>

配置 npm 二进制包镜像

对于 node-sass、sharp、puppeteer 等含有二进制文件的包，还需单独配置下载镜像。

# 常见的二进制包镜像配置
npm config set sass_binary_site https://npmmirror.com/mirrors/node-sass
npm config set sharp_binary_host https://npmmirror.com/mirrors/sharp
npm config set sharp_libvips_binary_host https://npmmirror.com/mirrors/sharp-libvips
npm config set puppeteer_download_host https://npmmirror.com/mirrors
npm config set electron_mirror https://npmmirror.com/mirrors/electron
npm config set python_mirror https://npmmirror.com/mirrors/python

使用 .npmrc 文件

可在项目目录下创建 .npmrc 文件，为单个项目指定镜像源：

registry=https://registry.npmmirror.com
sass_binary_site=https://npmmirror.com/mirrors/node-sass
sharp_binary_host=https://npmmirror.com/mirrors/sharp
puppeteer_download_host=https://npmmirror.com/mirrors

查看所有 npm 配置

npm config list
npm config list -l   # 显示全部默认配置

---

配置全局安装路径

使用 nvm 时无需此操作（nvm 自动管理路径）。
使用 apt 或二进制方式安装时，npm install -g 可能需要 sudo，建议配置用户级全局路径。

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

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

# 3. 在 ~/.bashrc 或 ~/.zshrc 中添加 PATH
# export PATH=~/.npm-global/bin:$PATH

# 或者直接使用以下命令追加
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 4. 之后全局安装无需 sudo
npm install -g yarn pnpm typescript

---

常见问题与排查

1. GPG 密钥验证失败

# 错误信息：gpg: Can't check signature: No public key
# 原因：未导入 Node.js 发布经理的 GPG 公钥

# 解决方案：从官方仓库导入密钥
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 或从 keyserver 导入
gpg --keyserver keyserver.ubuntu.com --recv-keys 4ED778F539E3634C779C87C6D7062848A1AB005C

2. NodeSource 仓库 apt 更新报错

# 错误信息：The repository 'https://deb.nodesource.com/...' does not have a Release file

# 原因：可能是镜像站未同步完成，或仓库 URL 有误

# 检查仓库文件
cat /etc/apt/sources.list.d/nodesource.list

# 重新配置仓库
sudo rm -f /etc/apt/sources.list.d/nodesource.list
# 然后重新按步骤添加

3. npm install 速度慢

# 确认当前 registry
npm config get registry

# 切换到淘宝镜像
npm config set registry https://registry.npmmirror.com

# 或者使用 --registry 临时指定
npm install express --registry=https://registry.npmmirror.com

4. node-sass / sharp 安装失败

# 错误多为二进制文件下载失败，配置镜像源后重试
npm config set sass_binary_site https://npmmirror.com/mirrors/node-sass
npm config set sharp_binary_host https://npmmirror.com/mirrors/sharp

# 清理缓存后重装
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

5. nvm 切换版本后 npm 找不到

# 重新安装 npm（与当前 Node 版本匹配）
nvm install-latest-npm

# 或手动指定 npm 版本
nvm use 22
npm install -g npm@latest

6. "EACCES: permission denied" 全局安装报错

# 解决方案：配置用户级全局路径（如上文 "配置全局安装路径" 章节）
# 或使用 nvm（推荐）

7. 查看 Node.js 的编译方式（确认是否从源码构建）

node -p "process.versions"
node -e "console.log(process.config)" | grep icu

---

安装方式对比总结

方式	GPG 验证	多版本管理	无需 sudo	推荐场景
NodeSource 仓库	✅ 自动	❌ 单一版本	❌	服务器生产环境
nvm	✅ 内置	✅ 灵活切换	✅	开发环境、多项目
官方二进制包	✅ 手动验证	❌ 单一版本	❌	离线安装、CI
包管理器直接安装	❌ 源内验证	❌	❌	❌ 不推荐

---

参考链接

• Node.js 官网
• NodeSource 官方文档
• nvm 官方仓库
• Node.js GPG 发布密钥
• 清华 TUNA Node.js 镜像
• 淘宝 npm 镜像