📚 课程目录第4章 Node-RED环境搭建

4. Node-RED 环境搭建：安装 Node.js、安装 Node-RED、启动与访问管理界面

Node-RED 是一个基于 Node.js 的流编排工具，其运行环境依赖 Node.js 运行时和 npm 包管理器。本章将指导你完成从零搭建 Node-RED 开发环境的完整流程，包括 Node.js 安装、Node-RED 全局安装、首次启动以及管理界面访问。

4.1 环境依赖概览

在开始安装前，先明确 Node-RED 对运行环境的核心要求：

依赖项	最低版本	推荐版本	说明
Node.js	14.x	18.x LTS 或 20.x LTS	提供 JavaScript 运行时与事件驱动 I/O
npm	6.x	9.x 或 10.x	随 Node.js 自动安装，用于管理 Node-RED 及其扩展包
操作系统	—	Linux / macOS / Windows 10+	Node-RED 跨平台支持，推荐 Linux 或 macOS 用于生产

版本选择建议： 生产环境优先选用 Node.js 18.x LTS 版本，该版本处于长期维护期，兼容性经过广泛验证。避免使用奇数版本（如 19.x、21.x），它们属于非 LTS 实验版本。

4.2 安装 Node.js 与 npm

Node.js 的安装方式因操作系统而异，以下列出三种主流安装路径：

4.2.1 方式一：使用官方安装包（Windows / macOS）

访问 nodejs.org，下载 18.x LTS 版本的 .msi（Windows）或 .pkg（macOS）安装包。
双击运行安装程序，保持默认选项，一路点击 Next 完成安装。
安装完成后，打开终端（cmd 或 Terminal），验证安装：

node --version
npm --version

4.2.2 方式二：使用包管理器（Linux / macOS）

Linux 用户推荐通过发行版包管理器或 NodeSource 仓库安装：

# Ubuntu / Debian 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# macOS 使用 Homebrew
brew install node@18
brew link --overwrite node@18

4.2.3 方式三：使用 nvm 版本管理（推荐）

nvm（Node Version Manager）允许在同一台机器上切换多个 Node.js 版本，适合需要测试不同环境的开发者：

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

# 重新加载终端配置
source ~/.bashrc

# 安装并使用 Node.js 18 LTS
nvm install 18
nvm use 18

  验证清单： 执行 node -v 应输出 v18.xx.x；执行 npm -v 应输出 9.x.x 或 10.x.x。如果版本号低于最低要求，请重新安装或升级。

4.3 安装 Node-RED

Node-RED 以 npm 全局包的形式发布，安装命令极为简洁：

npm install -g node-red

该命令会将 Node-RED 可执行文件安装到系统全局路径（如 /usr/local/bin/node-red），同时下载所有核心依赖。安装过程通常需要 30-60 秒，终端输出类似以下内容：

+ node-red@3.1.9
added 1024 packages in 45s

权限问题： 在 Linux / macOS 上如果遇到 EACCES 权限错误，请勿使用 sudo npm install -g。正确的做法是配置 npm 全局路径到用户目录，或使用 nvm 管理 Node.js 版本以避免权限冲突。

4.4 启动 Node-RED 服务

安装完成后，在终端中直接执行以下命令即可启动：

node-red

启动成功后，终端会显示以下关键信息：

Welcome to Node-RED
===================

30 Jan 2025 14:23:45 - [info] Node-RED version: v3.1.9
30 Jan 2025 14:23:45 - [info] Node.js  version: v18.20.4
30 Jan 2025 14:23:45 - [info] Server now running at http://127.0.0.1:1880/
30 Jan 2025 14:23:45 - [info] Starting flows
30 Jan 2025 14:23:45 - [info] Started flows

默认情况下，Node-RED 监听 127.0.0.1:1880，仅允许本地访问。如需修改端口或允许远程访问，可通过命令行参数指定：

# 修改端口为 3000
node-red -p 3000

# 允许所有网络接口访问（生产环境需配合安全认证）
node-red -u /path/to/userDir -D

4.5 访问管理界面

打开浏览器，在地址栏输入 http://127.0.0.1:1880，即可进入 Node-RED 的流编辑器管理界面。界面主要分为三个区域：

左侧调色板： 包含所有可用的节点（输入、输出、函数、网络、存储等分类），拖拽即可添加到编辑区。
中央编辑区： 用于拖放节点、连接线缆、编排流逻辑的空白画布。
右侧信息/调试面板： 显示节点帮助文档、调试输出消息、流状态信息。

4.6 常见问题与排查

问题现象	可能原因	解决方案
`command not found: node-red`	npm 全局安装路径未加入系统 PATH	执行 `npm config get prefix`，将输出目录添加到 `~/.bashrc` 或 `~/.zshrc` 的 PATH 中
浏览器访问 `127.0.0.1:1880` 无响应	Node-RED 未启动或端口被占用	检查终端是否有报错；执行 `lsof -i :1880` 查看端口占用情况
启动时提示 `Error: listen EADDRINUSE`	端口 1880 已被其他进程占用	使用 `node-red -p 1881` 指定其他端口，或关闭占用进程
安装过程中出现 `gyp ERR!` 编译错误	缺少 C++ 编译工具链	Windows 安装 `windows-build-tools`；Linux 安装 `build-essential`；macOS 安装 Xcode Command Line Tools

4.7 验证环境可用性

完成上述步骤后，建议执行一个快速验证流程，确保 Node-RED 能够正常处理流编排任务：

在浏览器中打开 http://127.0.0.1:1880，确认流编辑器界面完整加载。
从左侧调色板拖入一个 Inject 节点和一个 Debug 节点。
将两个节点用连线连接，点击右上角 Deploy 按钮。
点击 Inject 节点左侧的按钮，观察右侧 Debug 面板是否输出 timestamp 消息。