Node.js 安装指南

安装方法

macOS 安装

# 使用 Homebrew（推荐）
brew install node

# 或者从官网下载安装包
# 访问 https://nodejs.org/zh-cn 下载 LTS 版本

Ubuntu/Debian 安装

# 使用 NodeSource 官方脚本
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 或者使用包管理器
sudo apt update
sudo apt install nodejs npm

CentOS/RHEL 安装

# 使用 NodeSource 官方脚本
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs

# 或者使用 EPEL 仓库
sudo yum install epel-release
sudo yum install nodejs npm

Windows 安装

# 使用 Chocolatey
choco install nodejs

# 或者从官网下载安装包
# 访问 https://nodejs.org/zh-cn 下载 LTS 版本

环境配置

PATH 配置

如果安装后 openclaw 命令找不到，需要添加全局 bin 到 PATH：

# 查找 npm 全局安装路径
npm config get prefix

# 添加到 PATH（临时）
export PATH="$(npm config get prefix)/bin:$PATH"

# 添加到 PATH（永久）
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

版本管理

# 检查当前版本
node --version
npm --version

# 使用 nvm 管理多个版本
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装特定版本
nvm install 18.17.0
nvm use 18.17.0
nvm alias default 18.17.0

验证安装

基础验证

# 验证 Node.js 安装
node --version  # 应显示 v18.x.x 或更高版本

# 验证 npm 安装
npm --version   # 应显示 9.x.x 或更高版本

# 验证基本功能
node -e "console.log('Node.js 安装成功！')"

功能测试

# 创建测试项目
mkdir node-test && cd node-test
npm init -y

# 安装测试包
npm install express

# 创建简单服务器
echo "
const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(\`Server running at http://localhost:\${port}\`);
});
" > server.js

# 运行测试
node server.js

常见问题解决

权限问题

# 修复 npm 权限（macOS/Linux）
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# 或配置 npm 全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

网络问题

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

# 或使用 cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g openclaw

版本兼容性

# 检查 OpenClaw 兼容性
# OpenClaw 需要 Node.js 18+ 版本

# 升级 Node.js
# macOS
brew upgrade node

# Ubuntu
sudo apt update
sudo apt install nodejs

# 使用 nvm 升级
nvm install node  # 安装最新版本
nvm use node      # 使用最新版本

性能优化

npm 配置优化

# 设置缓存目录
npm config set cache ~/.npm

# 启用并行安装
npm config set maxsockets 20

# 设置超时时间
npm config set timeout 300000

系统级优化

# 增加文件描述符限制
echo "fs.file-max = 65536" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# 增加用户限制
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

开发环境配置

IDE 集成

// VS Code 推荐配置 .vscode/settings.json
{
  "typescript.preferences.includePackageJsonAutoImports": "on",
  "npm.enableScriptExplorer": true,
  "editor.formatOnSave": true,
  "eslint.validate": ["javascript", "typescript"]
}

开发工具

# 安装常用开发工具
npm install -g nodemon          # 自动重启工具
npm install -g pm2             # 进程管理器
npm install -g typescript      # TypeScript 编译器
npm install -g ts-node         # TypeScript 运行时

安全建议

定期更新

# 检查过期包
npm outdated

# 安全更新
npm audit
npm audit fix

# 全局包更新
npm update -g

依赖管理

# 锁定依赖版本
npm shrinkwrap

# 检查依赖安全
npm install -g nsp
nsp check

故障排除

安装失败

# 清理缓存
npm cache clean --force

# 重新安装
rm -rf node_modules package-lock.json
npm install

# 使用详细日志
npm install --verbose

运行时错误

# 检查环境变量
printenv | grep NODE

# 检查进程
ps aux | grep node

# 查看系统资源
htop
free -h

更多详情请参考官方文档: https://docs.openclaw.ai/install/node.md