故障排除

¥Troubleshooting

本指南包含使用 React Flow 时可能出现的警告和错误。我们还添加了从 Discord 服务器、Github 问题和 Github 讨论中收集的常见问题和陷阱。

¥This guide contains warnings and errors that can occur when using React Flow. We are also adding common questions and pitfalls that we collect from our Discord Server , Github Issues and Github Discussions .

警告：似乎你没有使用 zustand 提供程序作为祖级。

¥Warning: Seems like you have not used zustand provider as an ancestor.

这通常发生在以下情况下：

¥This usually happens when:

A：你安装了两个不同版本的 @reactflow/core。
B：你正在尝试在 React Flow 上下文之外访问内部 React Flow 状态。

¥A: You have two different versions of @reactflow/core installed.
B: You are trying to access the internal React Flow state outside of the React Flow context.

A 的解决方案

¥Solution for A

更新 reactflow 和 @reactflow/node-resizer（如果你正在使用它），删除 node_modules 和 package-lock.json 并重新安装依赖。

¥Update reactflow and @reactflow/node-resizer (in case you are using it), remove node_modules and package-lock.json and reinstall the dependencies.

B 的解决方案

¥Solution for B

一种可能的解决方案是使用 <ReactFlowProvider /> 封装你的组件或将访问状态的代码移动到 React Flow 实例的子实例内。

¥A possible solution is to wrap your component with a <ReactFlowProvider /> or move the code that is accessing the state inside a child of your React Flow instance.

🚫

This will cause an error:


import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
function FlowWithoutProvider(props) {
  // cannot access the state here
  const reactFlowInstance = useReactFlow();
 
  return <ReactFlow {...props} />;
}
 
export default FlowWithoutProvider;

🚫

This will cause an error, too:


import { ReactFlow, ReactFlowProvider } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
function Flow(props) {
  // still cannot access the state here
  // only child components of this component can access the state
  const reactFlowInstance = useReactFlow();
 
  return (
    <ReactFlowProvider>
      <ReactFlow {...props} />
    </ReactFlowProvider>
  );
}
 
export default FlowWithProvider;

This works:

一旦你想要访问 React Flow 的内部状态（例如通过使用 useReactFlow 钩子），你需要用 <ReactFlowProvider /> 封装你的组件。这里的封装是在组件外部完成的：

¥As soon as you want to access the internal state of React Flow (for example by using the useReactFlow hook), you need to wrap your component with a <ReactFlowProvider />. Here the wrapping is done outside of the component:


import { ReactFlow, ReactFlowProvider } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
function Flow(props) {
  // you can access the internal state here
  const reactFlowInstance = useReactFlow();
 
  return <ReactFlow {...props} />;
}
 
// wrapping with ReactFlowProvider is done outside of the component
function FlowWithProvider(props) {
  return (
    <ReactFlowProvider>
      <Flow {...props} />
    </ReactFlowProvider>
  );
}
 
export default FlowWithProvider;

看起来你已经创建了一个新的 nodeTypes 或 edgeTypes 对象。

¥It looks like you have created a new nodeTypes or edgeTypes object.

如果这不是故意的，请在组件外部定义节点类型/边缘类型或记住它们。

¥If this wasn’t on purpose please define the nodeTypes/edgeTypes outside of the component or memoize them.

当 nodeTypes 或 edgeTypes 属性在初始渲染后发生变化时，会出现此警告。nodeTypes 或 edgeTypes 只应在极少数情况下动态更改。通常，它们与你在应用中使用的所有类型一起定义一次。很容易发生这种情况，即你在组件渲染函数内部定义 nodeTypes 或 edgeTypes 对象，这将导致 React Flow 在每次组件重新渲染时重新渲染。

¥This warning appears when the nodeTypes or edgeTypes properties change after the initial render. The nodeTypes or edgeTypes should only be changed dynamically in very rare cases. Usually, they are defined once, along with all the types you use in your application. It can happen easily that you are defining the nodeTypes or edgeTypes object inside of your component render function, which will cause React Flow to re-render every time your component re-renders.

🚫

Causes a warning:


import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
import MyCustomNode from './MyCustomNode';
 
function Flow(props) {
  // new object being created on every render
  // causing unnecessary re-renders
  const nodeTypes = {
    myCustomNode: MyCustomNode,
  };
 
  return <ReactFlow nodeTypes={nodeTypes} />;
}
 
export default Flow;

Recommended implementation:


import { ReactFlow } from '@xyflow/react';
import MyCustomNode from './MyCustomNode';
 
// defined outside of the component
const nodeTypes = {
  myCustomNode: MyCustomNode,
};
 
function Flow(props) {
  return <ReactFlow nodeTypes={nodeTypes} />;
}
 
export default Flow;

Alternative implementation:

如果你想动态更改节点类型而不导致不必要的重新渲染，可以使用此功能。

¥You can use this if you want to change your nodeTypes dynamically without causing unnecessary re-renders.


import { useMemo } from 'react';
import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
import MyCustomNode from './MyCustomNode';
 
function Flow(props) {
  const nodeTypes = useMemo(
    () => ({
      myCustomNode: MyCustomNode,
    }),
    [],
  );
 
  return <ReactFlow nodeTypes={nodeTypes} />;
}
 
export default Flow;

未找到节点类型。使用后备类型 “default”。

¥Node type not found. Using fallback type “default”.

这通常发生在你为某个节点指定自定义节点类型但未将正确的 nodeTypes 属性传递给 React Flow 时。自定义节点的类型选项的字符串需要与 nodeTypes 对象的键完全相同。

¥This usually happens when you specify a custom node type for one of your nodes but do not pass the correct nodeTypes property to React Flow. The string for the type option of your custom node needs to be exactly the same as the key of the nodeTypes object.

🚫

Doesn’t work:


import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
import MyCustomNode from './MyCustomNode';
 
const nodes = [
  {
    id: 'mycustomnode',
    type: 'custom',
    // ...
  },
];
 
function Flow(props) {
  // nodeTypes property is missing, so React Flow cannot find the custom node component to render
  return <ReactFlow nodes={nodes} />;
}

🚫

Doesn’t work either:


import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
import MyCustomNode from './MyCustomNode';
 
const nodes = [
  {
    id: 'mycustomnode',
    type: 'custom',
    // ...
  },
];
 
const nodeTypes = {
  Custom: MyCustomNode,
};
 
function Flow(props) {
  // node.type and key in nodeTypes object are not exactly the same (capitalized)
  return <ReactFlow nodes={nodes} nodeTypes={nodeTypes} />;
}

This does work:


import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
import MyCustomNode from './MyCustomNode';
 
const nodes = [
  {
    id: 'mycustomnode',
    type: 'custom',
    // ...
  },
];
 
const nodeTypes = {
  custom: MyCustomNode,
};
 
function Flow(props) {
  return <ReactFlow nodes={nodes} nodeTypes={nodeTypes} />;
}

React Flow 父容器需要宽度和高度来渲染图形。

¥The React Flow parent container needs a width and a height to render the graph.

在底层，React Flow 测量父 DOM 元素以调整渲染器。如果你尝试在没有高度的常规 div 中渲染 React Flow，我们将无法显示图表。如果遇到此警告，你需要确保你的封装器组件附加了一些 CSS，以便它获得固定高度或继承其父级的高度。

¥Under the hood, React Flow measures the parent DOM element to adjust the renderer. If you try to render React Flow in a regular div without a height, we cannot display the graph. If you encounter this warning, you need to make sure that your wrapper component has some CSS attached to it so that it gets a fixed height or inherits the height of its parent.

🚫

This will cause the warning:


import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
function Flow(props) {
  return (
    <div>
      <ReactFlow {...props} />
    </div>
  );
}

Working example:


import { ReactFlow } from '@xyflow/react';
 
function Flow(props) {
  return (
    <div style={{ height: 800 }}>
      <ReactFlow {...props} />
    </div>
  );
}

只有子节点可以使用父范围。

¥Only child nodes can use a parent extent.

当你尝试将 extent 选项添加到没有父节点的节点时，会出现此警告。根据你要执行的操作，你可以删除 extent 选项或指定 parentNode。

¥This warning appears when you are trying to add the extent option to a node that does not have a parent node. Depending on what you are trying to do, you can remove the extent option or specify a parentNode.

🚫

Does show a warning:


import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
const nodes = [
  {
    id: 'mycustomnode',
    extent: 'parent',
    // ...
  },
];
 
function Flow(props) {
  return <ReactFlow nodes={nodes} />;
}

Warning resolved:


const nodes = [
  {
    id: 'mycustomnode',
    parentNode: 'someothernode',
    extent: 'parent',
    // ...
  },
];
 
function Flow(props) {
  return <ReactFlow nodes={nodes} />;
}

无法创建边。边需要源和目标。

¥Can’t create edge. An edge needs a source and a target.

当你没有将 source 和 target 选项传递给边缘对象时，就会发生这种情况。如果没有源和目标，则无法渲染边缘。

¥This happens when you do not pass a source and a target option to the edge object. Without the source and target, the edge cannot be rendered.

🚫

Will show a warning:


import { ReactFlow } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
const nodes = [
  /* ... */
];
 
const edges = [
  {
    nosource: '1',
    notarget: '2',
  },
];
 
function Flow(props) {
  return <ReactFlow nodes={nodes} edges={edges} />;
}

This works:


import { ReactFlow } from '@xyflow/react';
 
const nodes = [
  /* ... */
];
 
const edges = [
  {
    source: '1',
    target: '2',
  },
];
 
function Flow(props) {
  return <ReactFlow nodes={nodes} edges={edges} />;
}

id=“some-id” 的旧边不存在。

¥The old edge with id=“some-id” does not exist.

当你尝试重新连接边缘但要更新的边缘已从状态中删除时，可能会发生这种情况。这是一个非常罕见的情况。请参阅重新连接边缘示例了解实现细节。

¥This can happen when you are trying to reconnect an edge but the edge you want to update is already removed from the state. This is a very rare case. Please see the Reconnect Edge example for implementation details.

无法为源/目标句柄 ID 创建边：“some-id”；边缘 ID：“some-id”。

¥Couldn’t create edge for source/target handle id: “some-id”; edge id: “some-id”.

如果你使用多个句柄并且句柄的 id 属性未找到句柄，或者你没有以编程方式在添加或删除句柄后更新节点内部，则可能会发生这种情况。有关使用多个句柄的示例，请参阅自定义节点示例。

¥This can happen if you are working with multiple handles and a handle is not found by its id property or if you haven’t updated the node internals after adding or removing handles programmatically. Please see the Custom Node Example for an example of working with multiple handles.

标记类型不存在。

¥Marker type doesn’t exist.

当你尝试指定未内置于 React Flow 中的标记类型时，会出现此警告。现有的标记类型已记录在此处中。

¥This warning occurs when you are trying to specify a marker type that is not built into React Flow. The existing marker types are documented here.

句柄：未找到节点 ID。

¥Handle: No node id found.

当你尝试在自定义节点组件之外使用 <Handle /> 组件时，会出现此警告。

¥This warning occurs when you try to use a <Handle /> component outside of a custom node component.

使用 webpack 4 构建应用时出现错误。

¥I get an error when building my app with webpack 4.

如果你使用的是 webpack 4，则可能会遇到如下错误：

¥If you’re using webpack 4, you’ll likely run into an error like this:


ERROR in /node_modules/@reactflow/core/dist/esm/index.js 16:19
Module parse failed: Unexpected token (16:19)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders

React Flow 是一个现代 JavaScript 代码库，使用了许多较新的 JavaScript 功能。默认情况下，webpack 4 不会转译你的代码，也不知道如何处理 React Flow。

¥React Flow is a modern JavaScript code base and makes use of lots of newer JavaScript features. By default, webpack 4 does not transpile your code and it doesn’t know how to handle React Flow.

你需要在你的 webpack 配置中添加一些 babel 插件才能使其工作：

¥You need to add a number of babel plugins to your webpack config to make it work:


npm i --save-dev babel-loader@8.2.5 @babel/preset-env @babel/preset-react @babel/plugin-proposal-optional-chaining @babel/plugin-proposal-nullish-coalescing-operator


pnpm add --save-dev babel-loader@8.2.5 @babel/preset-env @babel/preset-react @babel/plugin-proposal-optional-chaining @babel/plugin-proposal-nullish-coalescing-operator


yarn add --dev babel-loader@8.2.5 @babel/preset-env @babel/preset-react @babel/plugin-proposal-optional-chaining @babel/plugin-proposal-nullish-coalescing-operator


bun add --dev babel-loader@8.2.5 @babel/preset-env @babel/preset-react @babel/plugin-proposal-optional-chaining @babel/plugin-proposal-nullish-coalescing-operator

并像这样配置加载器：

¥and configure the loader like this:


{
  test: /node_modules[\/\\]@?reactflow[\/\\].*.js$/,
  use: {
    loader: 'babel-loader',
    options: {
      presets: ['@babel/preset-env', "@babel/preset-react"],
      plugins: [
        "@babel/plugin-proposal-optional-chaining",
        "@babel/plugin-proposal-nullish-coalescing-operator",
      ]
    }
  }
}

如果你使用的是 webpack 5，则无需执行任何操作！React Flow 开箱即用。

¥If you’re using webpack 5, you don’t need to do anything! React Flow will work out of the box.

当我的节点包含 `<canvas />` 元素时，鼠标事件无法持续工作。

¥Mouse events aren’t working consistently when my nodes contain a <canvas /> element.

如果你在自定义节点内使用 <canvas /> 元素，则可能会遇到画布中鼠标事件中坐标看似不正确的问题。

¥If you’re using a <canvas /> element inside your custom node, you might run into problems with seemingly incorrect coordinates in mouse events from the canvas.

React Flow 使用 CSS 转换在你放大和缩小时缩放节点。但是，从 DOM 的角度来看，元素仍然是相同的大小。如果你有想要计算鼠标相对于画布元素的位置的事件监听器，这可能会导致问题。

¥React Flow uses CSS transforms to scale nodes as you zoom in and out. However, from the DOM’s perspective, the element is still the same size. This can cause problems if you have event listeners that want to calculate the mouse position relative to the canvas element.

为了在你控制的事件处理程序中解决这个问题，你可以通过 1 / zoom 缩放计算出的相对位置，其中 zoom 是流的当前缩放级别。要获取当前缩放级别，你可以使用 useReactFlow 钩子中的 getZoom 方法。

¥To remedy this in event handlers you control, you can scale your computed relative position by 1 / zoom where zoom is the current zoom level of the flow. To get the current zoom level, you can use the getZoom method from the useReactFlow hook.

边缘未显示。

¥Edges are not displaying.

如果你的边未显示在 React Flow 中，则可能是由于以下原因之一：

¥If your edges are not displaying in React Flow, this might be due to one of the following reasons:

你尚未导入 React Flow 样式表。如果你尚未导入它，你可以像 import '@xyflow/react/dist/style.css'; 一样导入它。

¥You have not imported the React Flow stylesheet. If you haven’t imported it, you can import it like import '@xyflow/react/dist/style.css';.
如果你已用自定义节点替换了默认节点，请检查该自定义节点在自定义节点组件中是否具有适当的 source/target 句柄。没有句柄就无法创建边缘。

¥If you have replaced your default nodes with a custom node, check if that custom node has appropriate source/target handles in the custom node component. An edge cannot be made without a handle.
如果你使用外部样式库（如 Tailwind 或 Bulma），请确保它不会覆盖边缘样式。例如，有时样式库会用 overflow: hidden 覆盖 .react-flow__edges SVG 选择器，从而隐藏边缘。

¥If you use an external styling library like Tailwind or Bulma, ensure it doesn’t override the edge styles. For example, sometimes styling libraries override the .react-flow__edges SVG selector with overflow: hidden, which hides the edges.
如果你正在使用异步操作（例如向后端发出请求），请确保在异步操作之后调用 useUpdateNodeInternal 钩子返回的 updateNodeInternals 函数，以便 React Flow 在内部更新句柄位置。

¥If you are using an async operation like a request to the backend, make sure to call the updateNodeInternals function returned by the useUpdateNodeInternal hook after the async operation so React Flow updates the handle position internally.

边缘显示不正确。

¥Edges are not displaying correctly.

如果你的边未按应有的方式渲染，则可能是由于以下原因之一：

¥If your edges are not rendering as they should, this could be due to one of the following reasons:

如果你想隐藏句柄，请不要使用 display: none 来隐藏它们。使用 opacity: 0 或 visibility: hidden。

¥If you want to hide your handles, do not use display: none to hide them. Use either opacity: 0 or visibility: hidden.
如果边未连接到正确的句柄，请检查你是否在自定义节点组件中添加了多个相同类型（source 或 target）的句柄。如果是这种情况，请为它们分配 ID。节点上相同类型的多个句柄需要具有可区分的 ID，以便 React Flow 知道边缘对应的句柄。

¥If edges are not connected to the correct handle, check if you have added more than one handle of the same type(source or target) in your custom node component. If that is the case, assign IDs to them. Multiple handles of the same kind on a node need to have distinguishable IDs so that React Flow knows which handle an edge corresponds to.
如果你正在更改句柄的位置（通过重新排序等），请确保在之后调用 useUpdateNodeInternals 钩子返回的 updateNodeInternals 函数，以便 React Flow 知道在内部更新句柄位置。

¥If you are changing the position of the handles (via reordering, etc.), make sure to call the updateNodeInternals function returned by the useUpdateNodeInternals hook after so React Flow knows to update the handle position internally.
如果你使用自定义边缘并希望边缘从源句柄转到目标句柄，请确保在边缘路径创建函数中正确传递从自定义边缘组件获取的 sourceX, sourceY, targetX, and targetY 属性（例如 getBezierPath 等）。sourceX, sourceY 和 targetX, targetY 分别代表源和目标句柄的 x,y 坐标。

¥If you are using a custom edge and want your edge to go from the source handle to a target handle, make sure to correctly pass the sourceX, sourceY, targetX, and targetY props you get from the custom edge component in the edge path creation function(e.g., getBezierPath, etc.). sourceX, sourceY, and targetX, targetY represent the x,y coordinates for the source and target handle, respectively.
如果来自源端或目标端的自定义边缘没有按预期朝向句柄（以奇怪的角度进入或退出句柄），请确保在边缘路径创建函数（例如 getBezierPath）中传递从自定义边缘组件获得的 sourcePosition 和 targetPosition 属性。在路径创建函数中传递源/目标句柄位置对于边缘在句柄处正确开始或结束是必要的。

¥If the custom edge from the source or target side is not going towards the handle as expected (entering or exiting from a handle at a weird angle), make sure to pass the sourcePosition and targetPosition props you get from the custom edge component in the edge path creation function(e.g., getBezierPath). Passing the source/target handle position in the path creation function is necessary for the edge to start or end properly at a handle.