useEffect和useLayoutEffect有什么区别？该用哪个？

在绝大多数开发场景中，你应该毫不犹豫地选择 useEffect。两者拥有完全一致的函数签名与依赖项语法，核心区别仅在于执行时机与是否阻塞浏览器绘制：useEffect 是在浏览器完成页面绘制（Paint）后异步执行的，不会阻塞画面的展示；而 useLayoutEffect 则是在 React 变更真实 DOM 后、浏览器绘制到屏幕前同步执行的，会直接阻塞屏幕渲染。只有当你的副作用需要读取 DOM 几何尺寸并立即同步更新状态，以避免用户肉眼看到界面跳跃或闪烁时，才需要使用 useLayoutEffect。

一、执行时机：浏览器渲染流水线中的位置差异

要透彻理解两者的差异，必须将其放进从“组件状态更新”到“像素呈现在屏幕上”的完整流水线中审视。React 的更新分为计算差异的 Render 阶段和提交变更的 Commit 阶段。而在 Commit 阶段，浏览器的渲染引擎也会同步参与协同。

当组件触发更新时，整个过程可以细化为以下步骤：

1. Render 阶段：React 调用函数组件，生成新的虚拟 DOM 树，并与旧的虚拟 DOM 进行 diff 对比。
2. DOM Mutation（提交阶段）：React 将计算出的 DOM 操作指令应用到浏览器的真实 DOM 节点上。此时内存中的 DOM 结构已经更新，但浏览器还没有将这些变化绘制到物理像素上。
3. useLayoutEffect 触发：紧接着 DOM 更新，React 会在此时同步执行所有的 useLayoutEffect 清理函数与回调函数。如果在其内部更新了 state，React 会在浏览器重绘之前立即进行同步再次渲染。
4. 浏览器绘制（Paint）：主线程从同步任务中释放，浏览器执行计算布局（Layout）并绘制位图（Paint），用户屏幕上出现最新的视觉内容。
5. useEffect 触发：绘制完成后，React 通过调度机制异步执行 useEffect。即便内部耗费了一定计算时间，也不会阻碍前一步屏幕内容的展示。

二、深度剖析：为什么 useEffect 会导致“视觉闪烁”？

很多开发者初次遇到 useLayoutEffect，往往是因为遇到了界面“肉眼可见的跳动”或“文字先显示在角落又瞬间弹回中间”的现象，也就是视觉闪烁（Visual Flicker）。

假定我们有一个悬浮提示框（Tooltip）组件，它的位置需要根据目标元素的高度进行动态计算。如果目标元素的高度只有在渲染到 DOM 后才能通过 getBoundingClientRect() 测量得到：

正如上图所示：

• 如果使用 useEffect，浏览器先将提示框按初始默认坐标（比如 top: 0）绘制上屏；随后 useEffect 异步触发，测量真实高度后通过 setState 重新将位置调整到 top: 120px 并触发第二轮重绘。用户在 16ms 或数帧之间就会看到元素从上方猛然跳下来，体验十分突兀。
• 如果使用 useLayoutEffect，在第一次 DOM 变更完成后，浏览器准备绘制前被立即拦截。Hook 同步测量尺寸，并把新的位置应用到 DOM 节点上。浏览器主线程在全部计算定型后才进行唯一一次绘制，用户直接看到处于正确位置的元素。

三、实战操作：DOM 测量与无缝定位标准范式

下面是一个标准的实际操作示例：实现一个能够自适应内容尺寸、居中对齐在目标节点上方的 Popover 弹窗。通过 useLayoutEffect 测量真实高度并更新坐标。

完整代码示例

import React, { useState, useRef, useLayoutEffect } from 'react';

function AutoPositionTooltip({ targetRect, text }) {
  const tooltipRef = useRef(null);
  const [position, setPosition] = useState({ top: 0, left: 0 });

  useLayoutEffect(() => {
    // 步骤 1 & 2：在浏览器绘制前，获取当前真实 DOM 尺寸
    if (!tooltipRef.current) return;
    
    const { height, width } = tooltipRef.current.getBoundingClientRect();
    
    // 步骤 3：根据内容实际高度动态计算定位坐标
    const calculatedTop = targetRect.top - height - 8; // 位于目标上方 8px
    const calculatedLeft = targetRect.left + (targetRect.width / 2) - (width / 2);

    // 步骤 4：同步更新状态，React 会在重绘前再次完成 DOM 属性提交
    setPosition({
      top: calculatedTop,
      left: calculatedLeft
    });
  }, [targetRect]);

  return (
    <div
      ref={tooltipRef}
      style={{
        position: 'fixed',
        top: `${position.top}px`,
        left: `${position.left}px`,
        padding: '8px 12px',
        background: '#2D3748',
        color: '#FFFFFF',
        borderRadius: '6px',
        pointerEvents: 'none'
      }}
    >
      {text}
    </div>
  );
}

export default AutoPositionTooltip;

四、为什么不能所有地方都使用 useLayoutEffect？

既然 useLayoutEffect 能防止视觉闪烁，为什么 React 官方强烈建议默认使用 useEffect？主要原因在于性能阻塞与服务端渲染兼容性。

1. 主线程性能与掉帧风险

useLayoutEffect 内部的所有逻辑都会强行占用浏览器主线程。如果你的副作用包含耗时计算、复杂的循环或者频繁触发的 DOM 查询，浏览器将无法进行任何绘制和响应用户输入。这会导致页面呈现卡死、按键无响应、滑动掉帧或白屏时间延长。而 useEffect 延迟执行，绝不会妨碍界面的快速加载和交互响应。

2. 服务端渲染（SSR）警告与不兼容

在 Next.js 或其它 SSR 环境中，服务端根本没有实际的 DOM 树或浏览器引擎，因此 useLayoutEffect 无法在服务端发挥任何测量作用。在组件服务端渲染阶段，React 会直接抛出警告：

Warning: useLayoutEffect does nothing on the server, because its code cannot be run. 
Did you mean to use useEffect, or to only render this component on the client?

如果项目在服务端渲染，且必须进行客户端 DOM 测量，推荐通过判断客户端挂载状态或者封装安全 Hook（仅在客户端使用 useLayoutEffect，服务端降级为 useEffect）来消除警告。

五、该用哪个？选型决策指南与速查表

在面对具体的业务需求时，你可以按照下方清晰的决策树进行判断：

对比维度	useEffect	useLayoutEffect
执行时机	组件挂载并完成浏览器屏幕绘制之后异步执行	React 提交真实 DOM 变更后、屏幕绘制之前同步执行
是否阻塞渲染	否，绝不影响浏览器画面的快速呈现	是，霸占主线程，直到代码执行完成才允许屏幕绘制
视觉体验影响	如果在其中测量并修改状态，会导致肉眼可见的二次跳动闪烁	将测量与修改合并在同一次物理绘制中，彻底消除闪烁
类组件对应生命周期	无严格对应（设计上类似异步挂载调度）	等价于 componentDidMount / componentDidUpdate 的同步时序
适用场景	API 请求、事件监听绑定、定时器、全局 Context 订阅、打点分析	Tooltip/气泡定位计算、动画首帧初始坐标设定、滚动位置同步纠偏
服务端渲染 (SSR)	完全支持，服务端安全静默跳过	直接报错警告，必须做客户端环境判定或封装隔离

总结

记住一个简单而稳妥的原则：默认永远选择 useEffect。只有当你明确发现界面的布局或样式在初次渲染时出现了闪烁、跳变，或者你必须在用户看到界面之前精确测量元素的真实尺寸并同步调整位置时，再将该特定位置的 Hook 换成 useLayoutEffect。遵循这一规则，既能保障你的页面拥有流畅快速的首屏响应能力，又能在关键的局部交互上保持细腻无瑕的视觉体验。