Node.js 安装 + React Flow 快速入门：环境安装与项目搭建

 本文为《React Agent：从零开始构建 AI 智能体》专栏系列文章。 专栏地址：https://blog.csdn.net/suiyingy/category_12933485.html。项目地址：https://gitee.com/fgai/react-agent（含完整代码示​例与实战源）。完整介绍：https://blog.csdn.net/suiyingy/article/details/146983582。

1 Node.js 安装

        Node.js 是 React Flow 开发的基石，因为 React 应用依赖于 Node.js 的包管理工具 npm（或 yarn）来安装和管理项目依赖。首先，访问 Node.js 官方网站（https://nodejs.org/），在下载页面中，你会看到长期支持（LTS）版本和最新版本。对于大多数开发场景，建议下载并安装 LTS 版本，以确保稳定性和广泛的兼容性。下载完成后，运行安装程序，按照默认设置逐步完成安装。

图1 Node.js 下载页面

        我们也可以使用命令行进行安装，Ubuntu安装命令如下：

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

        安装成功后，打开命令行工具（Windows 下为命令提示符或 PowerShell，MacOS 和 Linux 下为终端），输入以下命令检查 Node.js 是否安装成功。如果安装正确，你将看到类似于v23.11.0这样的版本号输出，这表明 Node.js 已经成功安装在系统中。npm 也会随 Node.js 一同安装。

node -v
npm -v

        输出结果如下图所示。

图2 Node.js 安装版本

        一个高效的代码编辑器对于 React Flow 开发至关重要。常见的选择有 Visual Studio Code（VS Code）、WebStorm 等。这里以 VS Code 为例进行介绍。访问 VS Code 官方网站（https://code.visualstudio.com/），下载适合你操作系统的安装包。安装完成后打开 VS Code，它提供了丰富的插件生态系统，能极大提升开发体验。在 VS Code 的扩展商店中，推荐安装以下插件：

1. ESLint：用于检查和规范 JavaScript 代码风格，遵循行业最佳实践，减少代码错误。
2. Prettier：代码格式化工具，自动格式化代码，使代码风格统一、整洁
3. Reactjs code snippets：提供一系列 React 代码片段，方便快速编写常见的 React 代码结构，如组件定义、生命周期方法等。

2 创建 React Flow 项目

        Create React App 是 Facebook 官方提供的用于快速搭建 React 项目的工具，它能自动配置好开发环境，让开发者专注于业务逻辑实现。在命令行中运行以下命令创建一个新的 React 项目：

npx create-react-app exp01
cd exp01

        或者使用 Vite 创建更轻量的项目：

npm create vite@latest exp01 --template react
cd exp01
npm install

或者手动初始化 React 项目：

mkdir exp01
cd exp01
npm init -y
npm install react react-dom

        这里 exp01 是项目名称，用户可以根据实际情况进行修改。create-react-app命令会在当前目录下创建一个名为 exp01 的文件夹，并自动安装 React、React DOM 以及其他必要的开发依赖。等待安装过程完成，这可能需要一些时间，取决于你的网络速度。执行命令后命令行提示信息如下图所示。

图3 创建 React 项目

        React 的 create-react-app 工具会在当前目录下创建一个名为 exp01 的文件夹，并初始化一个完整的 React 项目结构。以下是生成的目录结构以及各文件和文件夹的主要作用，开发过程中需要重点关注 src 目录下的文件。

exp01/
├── node_modules/            # 项目的依赖库目录，由 npm/yarn 安装生成
│                             # 不需要手动修改，包含项目运行所需的所有第三方包
├── public/                  # 存放静态资源文件，直接被复制到最终构建中
│   ├── favicon.ico          # 网站图标，显示在浏览器标签上
│   ├── index.html          # 应用的主 HTML 文件
│   ├── logo192.png         # PWA（渐进式 Web 应用）使用的小图标
│   ├── logo512.png         # PWA 使用的大图标
│   ├── manifest.json        # PWA 的配置文件，定义元数据（如名称、图标等）
│   ├── robots.txt           # 用于搜索引擎爬虫的配置文件
├── src/                     # 项目的源代码目录，主要用于开发
│   ├── App.css            # 应用主组件 App 的样式文件
│   ├── App.js             # 应用主组件文件，定义了应用的结构
│   ├── App.test.js          # 包含对 App.js 的单元测试代码（使用 Jest 编写）
│   ├── index.css           # 全局样式文件，定义基础的 CSS 样式
│   ├── index.js            # 应用的入口文件，将 React 组件挂载到 DOM
│   ├── logo.svg           # 项目中的默认 SVG 示例图标
│   ├── reportWebVitals.js   # 性能报告工具文件，用于记录和报告应用性能指标
│   ├── setupTests.js        # 配置 Jest 测试环境的初始化文件
├── .gitignore               # 配置 Git 忽略的文件列表，如 node_modules/ 等
├── package.json            # 项目描述文件，包含项目名称、版本、依赖等信息
├── README.md           # 项目的 README 文件，提供项目说明和快速启动指南
├── yarn.lock 或 package-lock.json # 锁定依赖版本的文件，确保团队使用相同依赖版本

        此时我们即可启动项目，命令为

npm start

        命令行提示信息如下图所示。

图4 React 项目启动

        此时，我们在浏览器页面输入“http://localhost:3000/”即可查看默认页面。示例项目地址为“https://gitee.com/fgai/react-agent”，程序目录为“project/chapter_02/exp01”。

图6 React 默认页面

        在已经创建好的 React 项目中，无论是使用 Create React App 初始化的还是手动初始化的，都可以通过 npm 来安装 React Flow 库。在项目根目录的命令行中运行以下命令：

npm install reactflow react-flow-renderer

        react-flow-renderer 是 React Flow 的核心库，它包含了构建流程图所需的各种组件和功能。安装完成后，项目的node_modules文件夹中会增加 React Flow 相关的文件和依赖。

        安装 React Flow 及其相关依赖时可能会遇到依赖冲突问题。例如，不同库对同一依赖的版本要求不一致。当遇到这种情况时，首先检查npm install命令的输出日志，通常会提示哪些依赖之间存在冲突。解决方法之一是尝试更新或降级相关依赖的版本，使其相互兼容。npm install <package - name>@<version> 命令可以用于指定安装特定版本的依赖。如果冲突问题仍然存在，使用npm - dedupe 命令尝试通过合并重复的依赖来解决冲突。但需要注意的是，npm - dedupe可能并不总是能完全解决复杂的依赖冲突问题，在某些情况下，可能需要手动调整项目的依赖结构。例如，react-flow-renderer 通常与 React 18 版本兼容较好，而默认安装的版本可能是 19 版本，需要使用以下命令进行降级。

cd exp01
npm install react@18 react-dom@18

        使用 React Flow 组件时可能会遇到组件渲染异常的情况，如节点或边显示不完整、样式错乱等。这可能是由于组件的属性设置不正确或者 CSS 样式冲突导致的。这时需要仔细检查传递给ReactFlow、Node和Edge等组件的属性是否符合文档要求，例如节点的id、type、data和position属性，边的id、source和target属性等。对于样式问题，检查项目中是否存在全局 CSS 样式影响了组件的显示。组件内部使用内联样式或者 CSS Modules 来可确保样式的局部性，避免全局样式冲突。另外，React Flow 库及其依赖的版本与项目的 React 版本确保兼容，不兼容的版本也可能会导致渲染问题。

        下面是一个简单的示例程序。

import React from 'react';
import { ReactFlow } from 'reactflow';
import 'reactflow/dist/style.css';

const initialNodes = [
  { id: '1', position: { x: 0, y: 0 }, data: { label: '1' } },
  { id: '2', position: { x: 0, y: 100 }, data: { label: '2' } },
];
const initialEdges = [{ id: 'e1-2', source: '1', target: '2' }];

export default function App() {
  return (
    <div style={{ height: '500px' }}>
      <ReactFlow nodes={initialNodes} edges={initialEdges} fitView/>
    </div>
  );
}

        React Flow 整体架构由节点、边以及用于管理和呈现它们的容器组成。节点是这个架构中的核心数据载体，边则用于连接节点，展示它们之间的关系。容器负责管理节点和边的布局、渲染以及交互逻辑。上面示例程序主要包括以下四个部分。

        （1）引入必要的依赖

        首先，程序需要引入 React 和 React Flow 相关的依赖。在代码里，import React from 'react'; 引入了 React 库，而 import { ReactFlow } from 'reactflow'; 引入了 React Flow 组件，import 'reactflow/dist/style.css'; 则引入了 React Flow 的样式文件，以保证图形界面能正常显示样式。

        （2）定义初始节点和边

        在代码中，initialNodes 数组用来定义初始节点，每个节点都有唯一的 id、position（节点在流程图中的位置）和 data（节点包含的数据，像 label 这种可用于显示节点标签的信息）。initialEdges 数组则用于定义节点间的连接关系，每条边都有唯一的 id，同时要指定 source（起始节点的 id）和 target（目标节点的 id）。

        （3）创建 React 组件

        代码中创建了一个名为 App 的 React 组件。在该组件的返回值里，要创建一个具有指定高度的 div 元素，这是 React Flow 组件的容器。然后将 ReactFlow 组件放置在这个 div 内，同时把之前定义好的 initialNodes 和 initialEdges 分别作为 nodes 和 edges 属性传递给 ReactFlow 组件，并且使用 fitView 属性让初始视图能适配容器。

        （4）导出组件

        最后，将创建好的 App 组件导出，这样就能在其他地方使用它了。通过上述步骤，你就可以快速搭建一个包含初始节点和边的简单流程图。

        将上面程序复制到App.js文件，然后启动项目后可在浏览器中得到如下页面。示例项目地址为“https://gitee.com/fgai/react-agent”，程序目录为“project/chapter_02/exp02”。

图7 React Flow 基本示例效果

        按下键盘的删除键（Backspace、退格）可直接删除所选中的节点或边。

立即关注获取最新动态

 点击订阅《React Agent 开发专栏》，每周获取智能体开发深度教程。项目代码持续更新至React Agent 开源仓库，欢迎 Star 获取实时更新通知！FGAI 人工智能平台：FGAI 人工智能平台