Node-RED:5分钟快速上手：安装与环境配置

Node-RED:5分钟快速上手：安装与环境配置

关键字： Node-RED、 Docker 部署 Node-RED、 npm 权限问题、 Node-RED 用户认证、 Node-RED 配置文件 Node-RED 安装、 flows.json 备份

去年冬天，我帮一位做智慧农业的朋友调试设备。他用的是树莓派 3B+，系统是 Raspbian，网络环境还不太稳定。当时他尝试安装 Node-RED，结果卡在 npm 权限问题上整整一下午。后来我远程连过去，三分钟搞定——不是我多厉害，而是踩过的坑多了，知道哪些地方容易“翻车”。

今天这篇文章，就是想把这份经验毫无保留地分享出来。无论你是用 Windows 写代码的后端工程师，还是在树莓派上折腾传感器的创客，亦或是第一次接触低代码工具的新手，只要跟着一步步操作，你都能在 5 分钟内跑起 Node-RED。

更重要的是，我会告诉你哪些地方容易出错，以及为什么出错。

一、准备工作：你真的需要“最新版”吗？

很多人一上来就执行 npm install -g node-red@latest，结果发现和系统里的 Node.js 版本不兼容。其实，Node-RED 对 Node.js 版本有明确要求。

截至 2025 年 10 月，官方推荐的 Node.js 版本是 18.x 或 20.x（LTS）。Node.js 22 虽然已发布，但部分社区节点尚未完全适配，不建议生产环境使用。

你可以通过以下命令检查当前版本：

node -v
npm -v

如果显示的是 v14 或更早版本（比如 Ubuntu 20.04 默认的 Node.js 10），请先升级。推荐使用 Node Version Manager（nvm） 来管理多个版本，避免污染系统环境。

📌 小贴士：在树莓派或老旧服务器上，尽量使用 LTS 版本。我曾在一台 1GB 内存的设备上强行跑 Node.js 22，结果内存溢出，服务频繁崩溃。

二、三种主流安装方式，总有一款适合你

Node-RED 的安装方式非常灵活。根据你的使用场景，可以选择以下任一方式：

方式1：全局 npm 安装（最常用）

这是官方推荐的方式，适合大多数开发者。

# 全局安装
npm install -g node-red# 启动
node-red

启动后，浏览器访问 http://localhost:1880，就能看到熟悉的编辑器界面。

但这里有个经典陷阱：如果你用的是 Linux 或 macOS，且 Node.js 是通过系统包管理器（如 apt、yum）安装的，可能会遇到权限问题，提示：

Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

解决方法：不要用 sudo！而是配置 npm 的全局目录到用户目录下：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

然后再执行 npm install -g node-red，就再也不会有权限问题了。

方式2：Docker 一键部署（适合服务器）

如果你习惯用容器化部署，Node-RED 官方提供了 Docker 镜像，支持 ARM（树莓派）和 x86 架构。

docker run -it -p 1880:1880 --name mynodered nodered/node-red

但要注意：容器内的流程默认不会持久化！重启容器后所有配置都会丢失。

正确的做法是挂载数据卷：

mkdir ~/nodered-data
docker run -it -p 1880:1880 \-v ~/nodered-data:/data \--name mynodered nodered/node-red

这样，你的流程、节点配置、用户凭证都会保存在本地 ~/nodered-data 目录中。

方式3：直接运行源码（适合开发者）

如果你想贡献代码或调试节点，可以直接克隆 GitHub 仓库：

git clone https://github.com/node-red/node-red.git
cd node-red
npm install
npm start

这种方式会启用开发模式，支持热重载，但不适合生产环境。

三、首次启动：别急着写流程，先看懂目录结构

当你第一次运行 node-red，它会在用户目录下创建一个隐藏文件夹：~/.node-red（Windows 是 %USERPROFILE%\.node-red）。

这个目录非常重要，它的结构如下：

graph TD
A[.node-red] --> B[flows.json]
A --> C[package.json]
A --> D[node_modules]
A --> E[settings.js]
A --> F[lib/]

• flows.json：你所有流程的定义文件（JSON 格式），相当于“项目源码”
• package.json：记录你安装的第三方节点（如 dashboard、mqtt 等）
• node_modules：第三方节点的实际代码
• settings.js：核心配置文件，可修改端口、用户认证、日志级别等
• lib/：自定义函数库或子流程模板

💡 建议：定期备份 flows.json 和 package.json。我曾因误操作清空流程，幸好有 Git 提交记录才没重做。

四、配置优化：让 Node-RED 更好用

默认配置虽然能跑，但离“好用”还有距离。以下是几个必改项。

1. 修改默认端口

如果你的 1880 端口被占用（比如另一个 Node-RED 实例），可以修改 settings.js：

module.exports = {uiPort: process.env.PORT || 1881, // 改成 1881// ... 其他配置
}

或者通过环境变量启动：

PORT=1881 node-red

2. 启用用户认证（安全第一！）

Node-RED 默认没有密码！这意味着只要能访问 IP:1880，就能控制你的所有流程——包括发送 HTTP 请求、读取文件、控制硬件。

在 settings.js 中取消注释以下部分：

adminAuth: {type: "credentials",users: [{username: "admin",password: "$2a$08$zZW4a...（加密后的密码）",permissions: "*"}]
}

密码不能明文写！要用 bcrypt 加密。官方提供了一个在线工具（或用命令行）：

node-red admin hash-pw

输入密码后，它会输出加密字符串，粘贴到配置文件即可。

3. 调整日志级别

默认日志太多，调试时容易淹没关键信息。可在 settings.js 中设置：

logging: {console: {level: "info" // 可选: fatal, error, warn, info, debug, trace}
}

生产环境建议用 info，开发时可临时改为 debug。

五、常见问题排查：这些坑我都替你踩过了

❌ 问题1：启动后浏览器打不开，提示“连接被拒绝”

• 检查是否绑定了 127.0.0.1（默认只允许本地访问）

• 如果是远程服务器，需在 settings.js 中设置：

  uiHost: "0.0.0.0"
  

• 同时确保防火墙开放 1880 端口（云服务器需配置安全组）

❌ 问题2：安装节点时卡在“正在安装…”

• 很可能是 npm 源太慢。建议切换为国内镜像：

  npm config set registry https://registry.npmmirror.com
  

• 或者手动安装：进入 ~/.node-red 目录，执行

  npm install node-red-dashboard
  

❌ 问题3：树莓派上启动慢、内存不足

• 关闭不必要的服务（如蓝牙、GUI）

• 使用轻量系统（如 Raspberry Pi OS Lite）

• 在 settings.js 中限制最大消息队列：

  flowFilePretty: true,
  nodeMaxQueueSize: 10  // 默认是 1000，降低可省内存
  

---

六、验证安装：创建你的第一个流程

一切就绪后，让我们做个简单测试：

1. 打开 http://localhost:1880
2. 从左侧调色板拖一个 Inject 节点 到画布
3. 再拖一个 Debug 节点
4. 用鼠标从 Inject 连到 Debug
5. 点击右上角 部署（Deploy）
6. 点击 Inject 节点左侧的按钮

如果右侧调试面板出现 timestamp 信息，恭喜你——Node-RED 已成功运行！

这个流程虽然简单，但它验证了：

• 编辑器能正常加载
• 节点能被实例化
• 消息能正确传递
• 调试面板能输出结果

---

七、下一步：别急着深入，先备份！

在你兴奋地开始构建复杂流程前，请做一件事：备份当前环境。

# 备份流程和依赖
cp ~/.node-red/flows.json ~/backup/
cp ~/.node-red/package.json ~/backup/

或者直接用 Git：

cd ~/.node-red
git init
git add .
git commit -m "Initial setup"

我见过太多人因为一次误操作，导致几天的工作付诸东流。而一个简单的备份，就能让你高枕无忧。

---

写在最后

安装 Node-RED 本身可能只需 1 分钟，但配置一个稳定、安全、可维护的环境，才是真正的开始。这篇文章没有堆砌命令，而是聚焦于“为什么这么做”和“哪里会出错”——因为技术的价值，不在于知道怎么做，而在于知道为什么这么做。

延伸提示

• 官方安装文档：https://nodered.org/docs/getting-started
• 国内镜像加速：https://npmmirror.com
• 树莓派优化指南：搜索 “Node-RED Raspberry Pi performance”

---