深入 `useSyncExternalStore`：解析它的 `getSnapshot` 与 `subscribe` 逻辑如何实现“检查点”同步

各位编程专家、架构师和对React内部机制充满好奇的朋友们，大家好！

今天，我们将一同踏上一段深入React并发渲染核心的旅程，聚焦于一个看似简单却蕴含着深刻同步哲学的Hook：useSyncExternalStore。这个Hook的出现，不仅优雅地解决了React与外部状态系统集成时面临的挑战，更在并发模式下，为我们提供了一个坚不可摧的“检查点”同步机制。

我们将从并发渲染带来的痛点出发，逐步解构useSyncExternalStore的API设计，然后深入探讨其核心逻辑——getSnapshot和subscribe是如何协同工作，构建起一套严密的“检查点”同步策略，从而彻底消除状态撕裂（Tearing）的风险。

---

React 并发渲染的挑战与外部状态管理的痛点

在React 18及以后的版本中，并发渲染（Concurrent Rendering）是其最激动人心的特性之一。它允许React在后台准备新的UI，而不阻塞主线程，从而提升用户体验。这意味着React可以：

1. 中断并恢复渲染： 当有更高优先级的任务（如用户输入）出现时，React可以暂停当前的渲染工作，稍后在合适的时候继续。
2. 同时处理多个渲染： React可以在内存中同时维护多个渲染树的“草稿”，并根据优先级决定最终提交哪一个。
3. 时间切片： 将长任务拆分为小块，在帧之间交错执行，避免长时间占用主线程。

这些强大的能力，为构建流畅、响应迅速的用户界面打开了新的大门。然而，对于那些不直接由React管理，而是存在于外部的状态（例如，Redux、Zustand、MobX、甚至一个简单的全局JavaScript对象），并发渲染带来了新的挑战：状态撕裂 (Tearing)。

什么是状态撕裂 (Tearing)？

想象一下，你正在阅读一本书，而另一个人正在同时修改这本书的某一页。如果你在阅读第10页的时候，另一个人修改了第5页，然后你继续阅读第11页。在你读到第11页时，你脑海中对这本书的理解可能基于一个旧的第5页和新的第10页之后的内容，这导致了你对这本书整体内容的理解是前后不一致的。这种不一致性，在React的术语中，就是“状态撕裂”。

在React中，这意味着：

• 问题： 在同一个并发渲染周期中，组件A读取了外部状态的旧值，而组件B（或组件A的不同部分）读取了外部状态的新值。
• 后果： 用户界面显示出不一致的数据，可能导致UI故障、逻辑错误，甚至难以调试的问题。

传统的外部状态管理方案，通常依赖于 useState 和 useEffect 结合手动订阅/取消订阅。例如：

import React, { useState, useEffect } from 'react';

// 假设这是一个简单的外部计数器 store
const externalCounterStore = {
  _count: 0,
  _listeners: new Set(),

  getCount() {
    return this._count;
  },

  increment() {
    this._count++;
    this._listeners.forEach(listener => listener());
  },

  subscribe(listener) {
    this._listeners.add(listener);
    return () => this._listeners.delete(listener);
  }
};

function MyCounterComponent() {
  // 1. 在组件渲染时获取初始值
  const [count, setCount] = useState(externalCounterStore.getCount());

  useEffect(() => {
    // 2. 在副作用中订阅外部 store
    const unsubscribe = externalCounterStore.subscribe(() => {
      // 3. 当外部 store 更新时，触发组件重新渲染
      setCount(externalCounterStore.getCount());
    });

    // 4. 清理函数：取消订阅
    return () => unsubscribe();
  }, []); // 空依赖数组确保只订阅一次

  return (
    <div>
      <p>Current Count (via useState/useEffect): {count}</p>
      <button onClick={() => externalCounterStore.increment()}>Increment External</button>
    </div>
  );
}

// 模拟一个可能导致撕裂的场景
function App() {
  const [showCounter, setShowCounter] = useState(false);

  useEffect(() => {
    // 模拟一个异步操作，可能在中间触发store更新
    const timer = setTimeout(() => {
      externalCounterStore.increment(); // 外部store更新
    }, 50);

    return () => clearTimeout(timer);
  }, []);

  return (
    <div>
      <h1>传统方案下的撕裂风险</h1>
      <button onClick={() => setShowCounter(!showCounter)}>
        {showCounter ? 'Hide' : 'Show'} Counter
      </button>
      {showCounter && <MyCounterComponent />}
      {/* 另一个可能读取相同store的组件，但可能在不同时间点渲染 */}
      {showCounter && <AnotherComponentReadingStore />}
    </div>
  );
}

function AnotherComponentReadingStore() {
    // 假设这个组件也读取了externalCounterStore，但可能在不同的渲染批次或优先级下
    // 为了简化，我们直接在渲染时读取，没有useState/useEffect
    const count = externalCounterStore.getCount(); // 可能读取到不同的值
    return <p>Another Component Count: {count}</p>;
}

上述 useState/useEffect 模式在非并发模式下工作良好。但在并发模式下，问题就浮现了：

1. 第一次渲染： React开始渲染 MyCounterComponent，它调用 externalCounterStore.getCount() 获取到 count = 0。
2. 渲染中断： 在 useEffect 运行之前（即组件尚未订阅时），一个高优先级更新（例如，externalCounterStore.increment() 被其他地方调用）发生了，或者React决定暂停当前渲染去处理其他任务。此时，_count 变成了 1。
3. 恢复渲染： React恢复渲染 MyCounterComponent。useEffect 执行，订阅了 store，并调用 setCount(externalCounterStore.getCount())。此时 getCount() 返回 1，setCount 触发了一次新的更新。
4. 撕裂发生： MyCounterComponent 在其 useState 内部的 count 值为 0 （来自第一次渲染），但在 useEffect 中它看到了 1。如果 AnotherComponentReadingStore 在第一次渲染中断之后、MyCounterComponent 再次渲染之前被渲染，它直接读取 externalCounterStore.getCount() 可能会得到 1。这样，在同一个“时刻”，两个组件显示了外部状态的不同值，这就是状态撕裂。

为了解决这个问题，React团队引入了 useSyncExternalStore。

---

useSyncExternalStore API 概览

useSyncExternalStore 是一个专门为与外部数据源同步而设计的Hook，它提供了一种在并发模式下安全读取外部状态的机制。它的设计目标是让React能够可靠地知道外部状态何时发生变化，并在必要时重新同步，从而避免状态撕裂。

它的函数签名如下：

function useSyncExternalStore<Snapshot>(
  subscribe: (onStoreChange: () => void) => () => void,
  getSnapshot: () => Snapshot,
  getServerSnapshot?: () => Snapshot
): Snapshot;

它接收三个参数：

1. subscribe: 一个函数，接收一个 onStoreChange 回调函数作为参数。当外部 store 发生变化时，这个回调函数应该被调用。它必须返回一个 unsubscribe 函数，用于清理订阅。
2. getSnapshot: 一个函数，用于从外部 store 读取当前状态的“快照”。这个快照必须是稳定的，也就是说，如果 store 的逻辑状态没有变化，getSnapshot 应该返回一个引用相等的值。
3. getServerSnapshot (可选): 一个函数，用于在服务器端渲染 (SSR) 时获取初始快照。它的作用是在客户端水合 (Hydration) 过程中避免不必要的状态不匹配警告。如果未提供，服务器端将直接使用 getSnapshot，但可能会导致问题（稍后详细讨论）。

它返回当前外部 store 的快照值。

让我们用一个简单的计数器 Store 来演示如何使用它：

import React from 'react';
import { useSyncExternalStore } from 'react'; // 从 'react' 导入

// 1. 定义一个简单的外部 store
const simpleCounterStore = (() => {
  let count = 0;
  const listeners = new Set<() => void>();

  return {
    // 获取当前状态的快照
    getSnapshot() {
      return count;
    },

    // 订阅状态变化
    subscribe(listener: () => void) {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },

    // 修改状态并通知所有订阅者
    increment() {
      count++;
      listeners.forEach(listener => listener());
    },

    decrement() {
      count--;
      listeners.forEach(listener => listener());
    },

    // 仅用于演示SSR，实际中可能更复杂
    getServerSnapshot() {
      // 在SSR时返回一个初始值，例如0
      return 0;
    }
  };
})();

// 2. 使用 useSyncExternalStore 的组件
function MyCounterComponentWithSync() {
  // 使用 useSyncExternalStore 订阅外部 store
  const count = useSyncExternalStore(
    simpleCounterStore.subscribe,
    simpleCounterStore.getSnapshot,
    simpleCounterStore.getServerSnapshot // 提供 getServerSnapshot
  );

  return (
    <div>
      <p>Current Count (via useSyncExternalStore): {count}</p>
      <button onClick={() => simpleCounterStore.increment()}>Increment External</button>
      <button onClick={() => simpleCounterStore.decrement()}>Decrement External</button>
    </div>
  );
}

// 另一个可能读取相同store的组件
function AnotherComponentWithSync() {
  const count = useSyncExternalStore(
    simpleCounterStore.subscribe,
    simpleCounterStore.getSnapshot,
    simpleCounterStore.getServerSnapshot
  );
  return <p>Another Component Count (via useSyncExternalStore): {count}</p>;
}

function AppWithSync() {
    return (
        <div>
            <h1>使用 `useSyncExternalStore` 避免撕裂</h1>
            <MyCounterComponentWithSync />
            <AnotherComponentWithSync />
        </div>
    );
}

export default AppWithSync;

在这个例子中，MyCounterComponentWithSync 和 AnotherComponentWithSync 都安全地从 simpleCounterStore 读取 count。即使在并发渲染中，它们也总能看到一个一致的快照，这就是 useSyncExternalStore 的魔力所在。

---

核心机制：getSnapshot 与 subscribe 如何实现“检查点”同步

现在，让我们深入到 useSyncExternalStore 的核心，理解 getSnapshot 和 subscribe 是如何协同工作，实现“检查点”同步，从而彻底消除状态撕裂的。

“检查点”同步，可以理解为React在渲染过程中，会在关键时刻对外部状态进行“打点”和“验证”，确保所有相关的渲染工作都基于一个统一且最新的状态视图。

1. getSnapshot：状态的“打点”与“视图”

getSnapshot 函数是 useSyncExternalStore 机制的基石。它有两个关键作用：

• 提供初始值： 在组件首次渲染时，React会调用 getSnapshot 来获取初始状态值。
• 提供渲染时的最新值： 在后续的重新渲染周期中，React会在每次渲染开始之前再次调用 getSnapshot，以获取当前外部 store 的最新快照。

这个函数必须是纯函数，并且应该在外部 store 的逻辑状态没有变化时，返回一个引用相等的值。这是至关重要的，因为React会使用 Object.is 来比较前后两次 getSnapshot 返回的值，以判断状态是否发生了实质性变化。如果 getSnapshot 每次都返回一个新的对象引用，即使内部数据没有变化，也会导致不必要的重新渲染。

getSnapshot 的核心理念是提供一个一致的、不可变的状态视图。 无论React在哪个时间点调用它，它都应该返回那个时间点外部store的“真实”状态。

2. subscribe：状态变化的“通知”与“触发器”

subscribe 函数负责监听外部 store 的变化。当外部 store 内部的数据发生改变时，它会调用传递给它的 onStoreChange 回调函数。这个回调函数在 useSyncExternalStore 内部，实际上会触发一次React的更新，告诉React“外部状态可能变了，请重新检查”。

subscribe 的核心理念是建立一个高效的通知机制， 确保React能够及时响应外部状态的变化，从而有机会重新同步其内部组件的状态。它返回的 unsubscribe 函数同样关键，确保在组件卸载时能够清理掉监听器，避免内存泄漏。

3. “检查点”同步的实现流程：读-订阅-再读-验证

现在，让我们把 getSnapshot 和 subscribe 结合起来，看看在React并发渲染的背景下，它们是如何实现“检查点”同步的：

我们将通过一个具体的渲染流程来解析：

场景： 假设一个组件 MyComponent 使用 useSyncExternalStore 订阅了一个外部计数器，初始值为 0。在React开始渲染 MyComponent 之后，但在其完成提交之前，外部计数器被另一个异步操作更新为 1。

useSyncExternalStore 的内部工作流：

1. 第一次渲染阶段 (Render Phase – Initial Checkpoint)

   • React调用 getSnapshot()： 在 MyComponent 首次渲染时，React会调用 simpleCounterStore.getSnapshot()。此时，外部计数器是 0。React将这个值作为 MyComponent 在当前渲染周期中的初始快照 (Initial Snapshot)，并将其作为 count 变量的值传递给组件。
   • React开始渲染 MyComponent： MyComponent 使用 count = 0 进行渲染。
   • 重要： 此时，组件的UI（在内存中）正基于 count = 0 构建。

2. 订阅阶段 (Commit Phase – Establishing Subscription)

   • 当 MyComponent 的渲染工作被提交到DOM之后（useEffect 运行之前），或者在并发模式下，React在决定提交之前，会调用 subscribe 函数。
   • React调用 subscribe()： useSyncExternalStore 内部会调用 simpleCounterStore.subscribe()，并传递一个内部的 onStoreChange 回调函数。这个回调函数的作用是告诉React“外部状态可能已经改变，请安排一次重新渲染”。
   • 异步更新发生： 在这个 subscribe 调用之后，但在 MyComponent 的UI实际显示之前，或者在React并发地处理其他任务时，外部 simpleCounterStore.increment() 被调用了。此时，count 变成了 1。由于我们已经订阅，onStoreChange 回调函数被触发。
   • onStoreChange 触发更新： useSyncExternalStore 内部的 onStoreChange 回调被执行，它会调度一次对 MyComponent 的更新。

3. 重新渲染阶段 (Render Phase – Verification Checkpoint)

   • 由于 onStoreChange 触发了更新，React会再次进入 MyComponent 的渲染阶段。
   • React再次调用 getSnapshot()： 在这次重新渲染开始之前，React会再次调用 simpleCounterStore.getSnapshot()。此时，外部计数器已经是 1。React将这个值作为最新快照 (Latest Snapshot)。
   • 快照比较： React现在有两个快照：
     • Initial Snapshot (来自第一次渲染): 0
     • Latest Snapshot (来自第二次渲染前): 1
   • React使用 Object.is(Initial Snapshot, Latest Snapshot) 进行比较。在这里，Object.is(0, 1) 返回 false。
   • 检查点验证失败，废弃并重试： 由于快照不一致，React会识别到在第一次渲染完成到订阅之间，外部状态发生了变化。为了避免撕裂，React会废弃 (abort) 第一次渲染的结果，并从头开始使用 Latest Snapshot (1) 重新渲染 MyComponent。
   • MyComponent 现在使用 count = 1 进行渲染。

总结表格：

阶段	操作	外部 Store 状态	React 内部快照	目的/结果
1. 初始渲染前	React 首次调用 getSnapshot()	0	0 (Initial)	获取组件初始渲染的基准状态。
2. 初始渲染	MyComponent 使用 0 进行渲染（在内存中构建UI）。	0	0 (Initial)	基于 Initial 快照构建UI。
3. 订阅建立	React 调用 subscribe()，建立监听。	0	0 (Initial)	准备接收外部状态变化通知。
4. 外部状态变更	外部异步操作 simpleCounterStore.increment() 导致 count 变为 1。onStoreChange 被触发。	1	0 (Initial)	外部状态更新，通知React。
5. 重新渲染前	React 再次调用 getSnapshot()	1	1 (Latest)	获取当前外部状态的最新视图。
6. 快照比较	Object.is(Initial Snapshot (0), Latest Snapshot (1)) 为 false。	1	0 vs 1	检测到状态不一致，撕裂风险。
7. 废弃与重试	React 废弃第一次渲染结果，并使用 Latest Snapshot (1) 从头重新渲染 MyComponent。	1	1 (Latest)	消除撕裂，确保UI始终反映最新且一致的状态。
8. 最终渲染	MyComponent 使用 1 进行渲染，并提交到DOM。	1	1 (Latest)	UI显示一致的 1。

通过这种“读-订阅-再读-验证”的机制，useSyncExternalStore 确保了在任何时间点，React内部组件所看到的状态快照都是一致的，即使在并发渲染和外部状态异步更新的复杂交互下，也能保证不会发生撕裂。

核心保障：

useSyncExternalStore 承诺：一旦组件订阅了外部 store，任何后续的 getSnapshot 调用都将反映一个至少与订阅时一样新的值。 更进一步说，它保证了在 React 提交更新到 DOM 之前，所有组件都将看到同一个、最新的外部状态快照。如果在这个提交过程中，外部状态发生了变化，React会重新启动渲染，直到获得一个稳定的快照。

这个机制类似于数据库事务中的“快照隔离”：在一个事务开始时获取一个数据快照，所有操作都基于这个快照进行，直到事务提交。如果期间数据被修改，事务可能会回滚或重试，以保证数据的一致性。

---

一个简单的外部状态管理库实现（示例）

为了更好地理解 useSyncExternalStore，我们来构建一个非常迷你的外部状态管理库。这个库将提供一个 createStore 函数，用于创建可订阅的状态对象。

import { useSyncExternalStore, useMemo, useCallback } from 'react';

// 定义 Store 的类型
interface Store<T> {
  getSnapshot(): T;
  subscribe(listener: () => void): () => void;
  setState(newState: Partial<T> | ((prevState: T) => Partial<T>)): void;
}

// createStore 函数，用于创建可订阅的外部状态
function createStore<T extends object>(initialState: T): Store<T> {
  let state = initialState;
  const listeners = new Set<() => void>();

  return {
    getSnapshot() {
      // 返回当前状态的不可变快照
      // 注意：这里返回的是 state 对象本身，如果 state 内部属性变化，
      // 但 state 引用不变，React 默认的 Object.is 比较会认为没变。
      // 因此，我们确保 setState 总是返回一个新的 state 对象。
      return state;
    },

    subscribe(listener: () => void) {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },

    setState(updater) {
      const oldState = state;
      const newState = typeof updater === 'function'
        ? { ...oldState, ...(updater(oldState) as Partial<T>) }
        : { ...oldState, ...updater };

      // 只有当状态真正改变时才更新并通知
      // 这里使用 JSON.stringify 只是一个简单的深比较，实际生产中可能需要更高效的比较方式
      if (JSON.stringify(oldState) !== JSON.stringify(newState)) {
        state = newState as T; // 确保 state 引用改变
        listeners.forEach(listener => listener());
      }
    }
  };
}

// 创建一个全局的计数器 store
const counterStore = createStore({ count: 0, text: 'Hello' });

// Hook 封装，方便在组件中使用
function useCounterStore<T>(selector: (state: typeof counterStore.getSnapshot()) => T): T {
  // 订阅函数和快照函数应该保持稳定
  const subscribe = useCallback((onStoreChange: () => void) => {
    return counterStore.subscribe(onStoreChange);
  }, []);

  const getSnapshot = useCallback(() => {
    return selector(counterStore.getSnapshot());
  }, [selector]);

  // 因为 selector 可能会返回一个新的对象引用，即使底层状态没变
  // useSyncExternalStore 默认使用 Object.is 比较快照
  // 如果 selector 返回的是一个复杂对象，且每次都返回新引用，会引起不必要的重渲染
  // 但对于原始值或经过 memoization 的对象，这通常不是问题。
  // 更健壮的方案是在 useSyncExternalStore 外部再加一层 useMemo 针对 selector 结果。

  // 直接使用 useSyncExternalStore
  const selectedState = useSyncExternalStore(subscribe, getSnapshot);

  return selectedState;
}

// 使用自定义 Hook 的组件
function MyComplexCounter() {
  const count = useCounterStore(state => state.count);
  const text = useCounterStore(state => state.text);

  console.log('Rendering MyComplexCounter with:', { count, text });

  const increment = () => {
    counterStore.setState(prev => ({ count: prev.count + 1 }));
  };

  const changeText = () => {
    counterStore.setState({ text: `Updated at ${Date.now()}` });
  };

  return (
    <div style={{ border: '1px solid blue', padding: '10px', margin: '10px' }}>
      <h2>My Complex Counter</h2>
      <p>Count: {count}</p>
      <p>Text: {text}</p>
      <button onClick={increment}>Increment Count</button>
      <button onClick={changeText}>Change Text</button>
    </div>
  );
}

function AnotherComplexDisplay() {
  // 只关心 text 属性
  const text = useCounterStore(state => state.text);
  console.log('Rendering AnotherComplexDisplay with text:', text);

  return (
    <div style={{ border: '1px solid green', padding: '10px', margin: '10px' }}>
      <h3>Another Display</h3>
      <p>Text from Store: {text}</p>
    </div>
  );
}

function AppWithCustomStore() {
  return (
    <div>
      <h1>使用自定义 `createStore` 和 `useSyncExternalStore`</h1>
      <MyComplexCounter />
      <AnotherComplexDisplay />
    </div>
  );
}

export default AppWithCustomStore;

在这个例子中：

• createStore 负责维护实际的状态，并提供 getSnapshot 和 subscribe 接口。setState 方法确保了每次状态更新时，state 引用会改变，从而让 getSnapshot 返回的新引用能够被 useSyncExternalStore 捕获到。
• useCounterStore 是一个自定义Hook，它封装了 useSyncExternalStore 的使用，并允许组件通过选择器（selector）只订阅其关心的部分状态，从而优化渲染。
• MyComplexCounter 和 AnotherComplexDisplay 都安全地使用了这个自定义Hook，即使在并发模式下，它们也能看到一致的状态视图。

---

SSR (服务器端渲染) 的考量：getServerSnapshot 的作用

在服务器端渲染 (SSR) 环境中，useSyncExternalStore 引入了第三个可选参数：getServerSnapshot。这个参数对于避免在客户端水合（Hydration）过程中出现不一致性至关重要。

SSR 的挑战

在SSR中，服务器会预渲染应用程序的HTML，然后将它发送到客户端。客户端的React在接收到HTML后，会尝试“水合”它，即将事件监听器和其他React内部状态附加到已存在的DOM上，使其变为交互式的应用程序。

如果没有 getServerSnapshot，当一个组件在服务器端渲染时，useSyncExternalStore 会调用 getSnapshot 来获取初始状态。然而：

1. 服务器端数据可能不同步： 服务器端 getSnapshot 返回的值，可能与客户端首次渲染时 getSnapshot 返回的值不同。例如，服务器在渲染时可能有一个瞬态值，或者客户端在加载JavaScript和水合之间，外部 store 发生了变化。
2. 水合不匹配警告： 如果服务器渲染的HTML中的值与客户端水合时React期望的值不一致，React会发出一个“水合不匹配 (Hydration Mismatch)”的警告，并可能回退到客户端完全重新渲染。这会影响性能和用户体验。

getServerSnapshot 的解决方案

getServerSnapshot 专门用于解决这个问题。

• 仅在服务器端调用： getServerSnapshot 只会在服务器端渲染时被调用。
• 提供客户端水合时的初始值： 它应该返回一个与客户端水合时，useSyncExternalStore 预期读取到的初始值相匹配的快照。通常，这意味着返回一个默认值或者在服务器端渲染时注入的初始状态。
• 客户端忽略： 在客户端，useSyncExternalStore 会忽略 getServerSnapshot。它会在首次渲染时调用 getSnapshot 来获取实际的初始值。

示例：

import { useSyncExternalStore } from 'react';

const ssrSafeStore = (() => {
  let value = 'initial server value'; // 假设这是在服务器端设置的初始值
  const listeners = new Set<() => void>();

  return {
    getSnapshot() {
      return value;
    },
    subscribe(listener: () => void) {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },
    setValue(newValue: string) {
      value = newValue;
      listeners.forEach(l => l());
    },
    // 关键：SSR时提供一个稳定的初始快照
    getServerSnapshot() {
      // 在SSR时，我们希望客户端水合时看到的值是“initial server value”
      // 或者是一个在客户端会被快速覆盖的默认值。
      // 如果客户端在水合前会立即有一个不同的值，这里应该返回那个预期值。
      // 在这个简单的例子中，我们可以直接返回服务器的初始值。
      return 'initial server value';
    }
  };
})();

function SsrComponent() {
  const data = useSyncExternalStore(
    ssrSafeStore.subscribe,
    ssrSafeStore.getSnapshot,
    ssrSafeStore.getServerSnapshot
  );

  return <p>SSR Data: {data}</p>;
}

function AppSsr() {
  // 模拟客户端在水合后立即更新 store
  if (typeof window !== 'undefined') {
    setTimeout(() => {
        ssrSafeStore.setValue('updated client value');
    }, 100);
  }

  return (
      <div>
          <h1>SSR 环境下的 `useSyncExternalStore`</h1>
          <SsrComponent />
      </div>
  );
}

export default AppSsr;

在这个例子中：

• 在服务器端渲染 AppSsr 时，SsrComponent 会调用 ssrSafeStore.getServerSnapshot()，返回 'initial server value'。HTML中将包含 <p>SSR Data: initial server value</p>。
• 在客户端，当React尝试水合这个HTML时，它会使用 getServerSnapshot 提供的值作为水合的预期值。
• 一旦水合完成，SsrComponent 就会在客户端首次渲染时调用 ssrSafeStore.getSnapshot()。如果此时 ssrSafeStore 的 value 仍然是 'initial server value'，则水合成功。如果 value 已经变成了 'updated client value'（比如由于上述 setTimeout），则 useSyncExternalStore 的检查点机制会介入，检测到不匹配，并触发一次客户端的重新渲染，确保UI显示的是 'updated client value'，但不会出现水合警告。

关键点： getServerSnapshot 的存在是为了确保服务器渲染的HTML与客户端水合时的初始预期状态保持一致，从而避免水合不匹配的警告。它不参与客户端的实时状态同步，那是由 getSnapshot 和 subscribe 负责的。

---

深入理解 getSnapshot 的设计哲学

getSnapshot 是 useSyncExternalStore 的核心。它的设计和实现直接影响到状态同步的正确性与性能。

1. 幂等性与纯函数

• 幂等性 (Idempotence): 连续多次调用 getSnapshot，如果外部 store 的逻辑状态没有改变，它应该总是返回相同的值。
• 纯函数 (Pure Function): getSnapshot 不应该有任何副作用（Side Effects），例如修改外部 store 的状态或执行网络请求。它只是一个读取器。

2. 返回值的引用稳定性

React 使用 Object.is 来比较 getSnapshot 两次调用的返回值。这意味着：

• 原始值 (Primitives): 如果 getSnapshot 返回的是数字、字符串、布尔值等原始值，只要值相等，Object.is 就会认为它们是相等的。
• 对象/数组 (Objects/Arrays): 如果 getSnapshot 返回的是对象或数组，Object.is 比较的是它们的引用。这意味着，如果外部 store 的逻辑状态发生变化，getSnapshot 应该返回一个新的对象或数组引用。

错误示范：getSnapshot 总是返回新引用

const badStore = {
  _count: 0,
  _listeners: new Set(),
  getSnapshot() {
    // 每次都返回一个新对象，即使 count 没变
    return { count: this._count };
  },
  increment() {
    this._count++;
    this._listeners.forEach(l => l());
  },
  subscribe(l) { /* ... */ }
};

// 使用 badStore 会导致每次渲染都创建新对象，
// useSyncExternalStore 会认为状态一直发生变化，导致不必要的频繁重渲染。

这种情况下，即使 _count 没有变化，getSnapshot 也会返回一个 { count: 0 } 的新对象。Object.is 会判断这两个对象引用不相等，从而强制React重新渲染，造成性能浪费。

正确实践：确保引用稳定性

你的外部 store 应该设计成：只有当实际状态改变时，才更新 getSnapshot 返回值的引用。这通常通过内部状态的不可变更新来实现。

const goodStore = (() => {
  let state = { count: 0, text: 'Hello' };
  const listeners = new Set<() => void>();

  return {
    getSnapshot() {
      return state; // 返回当前状态对象的引用
    },
    setState(newState: typeof state) {
      // 只有当 newState 实际不同于 state 时，才更新引用并通知
      if (JSON.stringify(state) !== JSON.stringify(newState)) { // 简单的深比较
        state = newState; // 更新引用
        listeners.forEach(l => l());
      }
    },
    subscribe(listener: () => void) { /* ... */ }
  };
})();

在上面的 createStore 示例中，setState 确保了只有当状态逻辑上发生变化时，state 的引用才会被更新，从而 getSnapshot 返回的引用也随之改变。

3. 选择器与快照粒度

在实际应用中，你可能不希望组件每次都拿到整个 store 的快照。而是只关心 store 中的某个特定属性。这时，你可以在 getSnapshot 内部或者通过一个自定义Hook来引入选择器。

在 getSnapshot 内部使用选择器 (不推荐，除非选择器逻辑非常稳定且简单)：

function useCounterValue() {
  const count = useSyncExternalStore(
    counterStore.subscribe,
    () => counterStore.getSnapshot().count // 直接在 getSnapshot 内部选择
  );
  return count;
}

这种方式的缺点是，如果 counterStore.getSnapshot().count 所在的 counterStore.getSnapshot() 返回的对象引用不变，但 count 属性值变了，useSyncExternalStore 无法察觉（因为外部 getSnapshot 的返回值本身没变）。

更好的方式：通过 useMemo 或自定义Hook在外部封装选择器

function useCounterValueOptimized() {
  // 确保 subscribe 函数引用稳定
  const subscribe = useCallback((onStoreChange: () => void) => {
    return counterStore.subscribe(onStoreChange);
  }, []);

  // 获取完整的快照
  const fullSnapshot = useSyncExternalStore(subscribe, counterStore.getSnapshot);

  // 使用 useMemo 缓存选择器结果，避免不必要的重新计算和引用改变
  const count = useMemo(() => fullSnapshot.count, [fullSnapshot]);

  return count;
}

或者像我们 useCounterStore 示例中那样，在自定义 Hook 内部处理选择器：

function useCounterStore<T>(selector: (state: typeof counterStore.getSnapshot()) => T): T {
  const subscribe = useCallback((onStoreChange: () => void) => {
    return counterStore.subscribe(onStoreChange);
  }, []);

  // getSnapshot 返回的是 selector 的结果
  const getSelectedSnapshot = useCallback(() => {
    return selector(counterStore.getSnapshot());
  }, [selector]); // selector 也需要是稳定的

  // useSyncExternalStore 会比较 getSelectedSnapshot 的返回值
  // 如果 selector 每次都返回新对象，即便数据没变，也会触发重渲染
  // 此时，需要确保 selector 返回的也是引用稳定的值
  const selectedState = useSyncExternalStore(subscribe, getSelectedSnapshot);

  return selectedState;
}

这里的关键是：如果你在 getSnapshot 或其包装器（如 getSelectedSnapshot）中使用了选择器，并且这个选择器可能会根据原始快照返回一个新的对象引用（即使它内部的值没有变化），那么你需要确保这个选择器本身是经过优化的，例如使用 reselect 库或 useMemo 来缓存其结果，以避免不必要的渲染。

---

subscribe 的设计与注意事项

subscribe 函数的正确实现对于 useSyncExternalStore 的正常工作同样至关重要。

1. 返回 unsubscribe 函数

subscribe 必须返回一个函数，这个函数会在组件卸载时被调用，用于清理订阅。这是标准的 useEffect 清理模式，确保了资源管理得当，避免内存泄漏。

2. onStoreChange 回调的触发

当外部 store 的状态发生变化时，subscribe 接收的 onStoreChange 回调函数必须被调用。这个回调函数会通知 useSyncExternalStore 外部状态已改变，从而触发其内部的检查点验证流程。

3. subscribe 函数的稳定性

useSyncExternalStore 内部会缓存 subscribe 函数。如果 subscribe 函数的引用频繁变化，可能会导致不必要的重新订阅和取消订阅。因此，如果你的 subscribe 函数依赖于组件的 props 或 state，你需要使用 useCallback 来确保它的稳定性。

// 外部 store 的 subscribe 接口通常是稳定的
const store = {
  // ...
  subscribe(listener) { /* ... */ return () => { /* ... */ }; }
};

function MyComponent() {
  // 这样使用是稳定的，因为 store.subscribe 的引用是稳定的
  const value = useSyncExternalStore(store.subscribe, store.getSnapshot);
  // ...
}

如果你是在组件内部动态构造 subscribe 函数，例如，基于某个 id 订阅不同的频道：

function MyDynamicComponent({ id }: { id: string }) {
  // 确保 subscribe 函数引用稳定
  const subscribe = useCallback((onStoreChange: () => void) => {
    // 假设你的 store 有一个按 id 订阅的方法
    return myComplexStore.subscribeById(id, onStoreChange);
  }, [id]); // 依赖 id，当 id 变化时，subscribe 才会变化，从而重新订阅

  const snapshot = useSyncExternalStore(subscribe, () => myComplexStore.getSnapshotById(id));

  return <p>Data for ID {id}: {snapshot}</p>;
}

这里 subscribe 依赖于 id。当 id 变化时，useCallback 会返回一个新的 subscribe 函数，useSyncExternalStore 会自动取消旧的订阅，并建立新的订阅。

---

性能考量与最佳实践

在使用 useSyncExternalStore 时，除了正确性，性能也是一个重要的考量。

1. getSnapshot 的性能

• 避免昂贵计算： getSnapshot 可能会在渲染周期中被多次调用，尤其是在并发模式下。因此，它应该是一个非常轻量级的函数，避免在其中执行复杂的计算、网络请求或大量数据处理。
• 缓存中间结果： 如果 getSnapshot 确实需要进行一些计算才能生成最终快照，考虑在外部 store 内部缓存这些计算结果，并在状态实际变化时才重新计算。

2. subscribe 的性能

• 高效的通知机制： 你的外部 store 的订阅和通知机制应该高效。当状态变化时，只通知那些真正需要知道变化的组件。使用 Set 来管理监听器通常是一个好的选择。
• 避免不必要的通知： 只有当外部 store 的逻辑状态真正发生改变时，才应该调用 onStoreChange 回调。

3. 快照比较与渲染优化

• Object.is 的默认比较： useSyncExternalStore 默认使用 Object.is 比较 getSnapshot 返回的快照。对于原始值，这是完美的。对于对象，它比较引用。
• 自定义比较器的缺失： useSyncExternalStore 没有提供自定义比较器的选项（不像 useMemo 或 React.memo）。这意味着你必须确保 getSnapshot 返回的快照在逻辑上不变时，引用也保持不变。这是最关键的优化点。
• 选择器与 useMemo： 如果你的组件只关心快照中的一部分数据，并且这部分数据是一个复杂对象，请务必在组件内部使用 useMemo 来缓存选择器结果，或者像之前讨论的那样，在自定义Hook中优化选择器，以防止即使完整快照引用变化，但局部数据未变时，也触发不必要的子组件重新渲染。

4. 保持函数引用稳定

• subscribe 和 getSnapshot： 确保传递给 useSyncExternalStore 的 subscribe、getSnapshot (以及 getServerSnapshot) 函数的引用是稳定的。如果它们是组件内部定义的，请使用 useCallback。外部 store 提供的接口通常本身就是稳定的。
• 选择器： 如果你的自定义Hook接受一个选择器函数，确保这个选择器函数也是稳定的（例如，通过 useCallback 包装）。

---

与传统 useState/useEffect 方案的对比

让我们用一个表格来清晰地对比 useState/useEffect 方案和 useSyncExternalStore 方案。

特性/场景	useState + useEffect 方案	useSyncExternalStore 方案
并发模式下	容易出现状态撕裂 (Tearing) 和不一致的UI。	完全避免状态撕裂，保证UI一致性。
API 复杂性	需要手动管理 useState 和 useEffect 的依赖，以及订阅/取消订阅逻辑，容易出错。	简洁的API，核心是 subscribe 和 getSnapshot，内部处理复杂同步逻辑。
SSR 支持	容易出现水合不匹配警告，需要额外的 useEffect 逻辑处理客户端/服务器差异。	通过 getServerSnapshot 优雅支持SSR，避免水合不匹配。
性能开销	如果处理不当（如 useEffect 依赖不当），可能导致不必要的渲染。	getSnapshot 会在渲染前被调用，需要确保其高性能；快照比较是 Object.is。
状态源	适用于任何外部状态，但需要开发者自行确保同步逻辑。	专为外部可订阅的状态源设计，提供官方支持的同步机制。
学习曲线	对于初学者可能更直观，但理解并发模式下的限制需要经验。	需要理解其核心机制和 getSnapshot 的语义，但一旦理解，使用简单。
适用场景	小型项目、简单同步需求、非并发模式下的应用。	所有与外部状态集成的并发React应用，尤其是大型、复杂的应用。
React 官方推荐	不推荐用于与外部状态的复杂同步，尤其是在并发模式下。	官方推荐与外部状态管理器（如Redux、Zustand等）集成。

---

真实世界的应用场景

useSyncExternalStore 并非仅仅是一个理论上的 Hook，它已经在 React 生态系统中得到了广泛的应用和采纳：

1. 状态管理库：

   • Redux (通过 react-redux v8+): react-redux 内部已经使用 useSyncExternalStore 来订阅 Redux Store，确保在并发模式下组件能够获取到一致的全局状态。
   • Zustand: 这是一个轻量级的状态管理库，它天然地设计了 subscribe 和 getSnapshot 类似的接口，因此与 useSyncExternalStore 集成非常自然。
   • Valtio, Jotai: 这些原子状态管理库也利用 useSyncExternalStore 来实现高效且无撕裂的状态同步。
   • Apollo Client, React Query: 对于数据缓存层，也可以通过 useSyncExternalStore 来订阅缓存的更新。

2. 浏览器 API：

   • 你可以使用它来订阅浏览器提供的全局状态，例如 window.scrollY、navigator.onLine、matchMedia 等。
   • 示例：订阅 window.scrollY

   import { useSyncExternalStore, useState, useEffect } from 'react';
   
   const scrollStore = (() => {
     let scrollY = 0;
     const listeners = new Set<() => void>();
   
     const getSnapshot = () => scrollY;
   
     const subscribe = (listener: () => void) => {
       const handleScroll = () => {
         const newScrollY = window.scrollY;
         if (newScrollY !== scrollY) {
           scrollY = newScrollY;
           listener(); // 通知 React 滚动位置已变化
         }
       };
       window.addEventListener('scroll', handleScroll);
       return () => window.removeEventListener('scroll', handleScroll);
     };
   
     // SSR 时，假设初始滚动位置为 0
     const getServerSnapshot = () => 0;
   
     return { getSnapshot, subscribe, getServerSnapshot };
   })();
   
   function ScrollPositionDisplay() {
     const currentScrollY = useSyncExternalStore(
       scrollStore.subscribe,
       scrollStore.getSnapshot,
       scrollStore.getServerSnapshot
     );
   
     return (
       <div style={{ height: '200vh', paddingTop: '50vh' }}>
         <p style={{ position: 'fixed', top: '10px', left: '10px' }}>
           Current Scroll Y: {currentScrollY}px
         </p>
       </div>
     );
   }
   // 注意：App 中需要足够的内容才能滚动

3. Web Workers / BroadcastChannel：

   • 如果你在 Web Worker 中管理状态，并需要与主线程的 React 组件同步，useSyncExternalStore 可以用来监听 Web Worker 发送的消息，或通过 BroadcastChannel 在多个浏览器标签页之间同步状态。

---

结束语

通过今天的深入探讨，我们全面解析了 useSyncExternalStore 的工作原理，特别是它如何通过 getSnapshot 和 subscribe 的巧妙配合，构建起一套严密的“检查点”同步机制。这个机制不仅仅是解决了并发渲染带来的状态撕裂问题，更提供了一个通用、高效且官方支持的方案，使得React应用程序能够与任何外部状态源安全、无缝地集成。

理解 useSyncExternalStore 的设计哲学，以及如何在实际项目中正确地使用它，对于构建健壮、高性能的React并发应用至关重要。希望这次讲座能帮助大家在React的深层机制上更进一步，成为更好的开发者。