AutoGPT 前端工程实践：用 toSorted() 替代 sort() 守护 React 状态的不可变性

本文以 AutoGPT 仓库内置的 Vercel React 最佳实践规则 js-tosorted-immutable 为主体，讲清 .sort() 原地修改为何会破坏 React 的 props/state 不可变模型，并展示 .toSorted()、降级 fallback 与仓库中真实的前端源码用例，帮助你在编写、审查或重构 Next.js/React 代码时安全地对数组排序。

规则出处与定位

AutoGPT 仓库在 .claude/skills/vercel-react-best-practices 下内置了一份由 Vercel Engineering 维护的 React/Next.js 性能优化规则集（45 条规则、8 个分类），供 Agent 和开发者在写代码、评审代码时引用。其中规则原文 js-tosorted-immutable.md 归属 "JavaScript Performance" 类别（前缀 js-），元数据标注为：

• impact: MEDIUM-HIGH，影响描述为 "prevents mutation bugs in React state"（防止 React 状态中的突变 bug）；
• 标签：javascript, arrays, immutability, react, state, mutation。

在 SKILL.md 的分类总表中，JavaScript Performance 类别整体优先级为 LOW-MEDIUM，但单条规则文件的元数据将本条规则标为 MEDIUM-HIGH——因为它防的不是性能损失，而是正确性事故。编译版完整文档见 AGENTS.md 的 7.12 节。

核心问题：.sort() 会原地修改原数组

规则的核心论断只有一句话：.sort() 会 原地（in place）修改 传入的数组，这在 React 的 props/state 场景下会引发 bug。

错误写法（修改了 prop 数组）：

function UserList({ users }: { users: User[] }) {
  // Mutates the users prop array!
  const sorted = useMemo(
    () => users.sort((a, b) => a.name.localeCompare(b.name)),
    [users]
  )
  return <div>{sorted.map(renderUser)}</div>
}

这里 users 是父组件传入的 prop，useMemo 的回调直接调用 users.sort(...)，返回的虽然是"排好序的数组"，但实际是 同一个数组引用被原地重排——父组件持有的数据、乃至 zustand/React Query 等 store 里的原始数据都被悄悄改写了。

正确写法（返回新数组）：

function UserList({ users }: { users: User[] }) {
  // Creates new sorted array, original unchanged
  const sorted = useMemo(
    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
    [users]
  )
  return <div>{sorted.map(renderUser)}</div>
}

.toSorted(compareFn) 语义与 .sort() 一致（接受同样的比较函数、同样遵循稳定排序），但它总是 创建一个新数组 并在新数组上排序，原数组的引用与内容保持不变。

为什么这在 React 中尤其危险

原文档给出了两个原因，值得展开：

1. 违反 React 的不可变模型。React 期望 props 和 state 被当作只读数据：父组件的 props 不应被子组件改写，state 的更新应通过产生新值来完成（setX(newArray)），依赖比较（如 useMemo/useEffect 的浅比较、React.memo 的引用比较）都建立在"引用不变即内容不变"的假设上。原地 sort() 会改变内容却保持引用不变，使这些比较全部失真。
2. 闭包中的突变引发 stale/意外行为。数组常出现在回调、effects、事件处理函数的闭包里，在这些闭包中对共享数组执行 sort()，会在意料之外的时机改变所有闭包可见的数据，排查成本极高。

AutoGPT 前端源码中的真实用例

AutoGPT 前端（Next.js 应用，位于 autogpt_platform/frontend）中存在这条规则的直接落地案例。在 NewSaveControl/helpers.ts/build/components/NewControlPanel/NewSaveControl/helpers.ts#L15-L25) 中，graphsEquivalent 用于比较"已保存的 GraphModel"与"当前编辑器中的 Graph"是否等价（用于判断是否有未保存修改）：

const sortNodes = (nodes: NodeModel[] | Node[]) =>
  nodes.toSorted((a, b) => a.id?.localeCompare(b.id ?? "") ?? 0);

const sortLinks = (links: Link[]) =>
  links.toSorted(
    (a, b) =>
      8 * a.source_id.localeCompare(b.source_id) +
      4 * a.sink_id.localeCompare(b.sink_id) +
      2 * a.source_name.localeCompare(b.source_name) +
      a.sink_name.localeCompare(b.sink_name),
  );

从源码结构看，这个函数的输入分别来自数据层的 saved（已持久化模型）与 current（编辑器状态），随后对两份数据做 deepEquals 深度比较（借助 @rjsf/utils）。排序的目的是 消除节点/链接顺序差异带来的误报——只要集合相同、顺序不同就视为等价。这里如果写成 nodes.sort(...)，就会原地重排 store 中保存的图数据，让后续任何依赖该数组顺序或引用的逻辑（例如画布渲染、撤销栈）读到被比较函数"顺手"改坏的数据。这正是规则文档所说的 "mutation bugs in React state" 的典型场景：一个只用于只读比较的函数，却产生了副作用。

对比之下，仓库里对 纯派生的局部数组 使用 .sort() 是安全的，例如 useGraphMenuSearchBar.tsx/build/components/NewControlPanel/NewSearchGraph/GraphMenuSearchBar/useGraphMenuSearchBar.tsx#L40) 中对 .filter(...).map(...) 现产出的新数组排序——原数组并未被触碰。判断标准可以简化为一句话：被排序的数组是否可能是别人（父组件、store、闭包）也持有的引用？是则必须 toSorted() 或先复制。

运行时支持与降级方案

原文档给出的兼容基线：.toSorted() 在 Chrome 110+、Safari 16+、Firefox 115+、Node.js 20+ 可用；对更老的环境，用展开运算符复制后再排序：

// Fallback for older browsers
const sorted = [...items].sort((a, b) => a.value - b.value)

这个 fallback 本质上是手动实现"复制 + 原地排序"，效果与 toSorted() 等价，只是多了一次浅拷贝（toSpliced/toReversed 同理）。

从 AutoGPT 仓库的实际工程配置看，直接启用 toSorted() 没有障碍：

• package.json 声明 "engines": { "node": "24.x" }，Node 24 远高于 20 的基线；
• tsconfig.json 配置了 "target": "ES2022" 与 "lib": ["DOM", "DOM.Iterable", "ESNext"]，ESNext lib 意味着 TypeScript 类型层面可直接调用 toSorted/toReversed 等新方法签名，无需额外垫片；
• 仓库源码中两种写法并存：如上所述的 toSorted() 用例，以及 fallback 风格的 [...sessions].sort(...)（见 ChatSearchModal/helpers.ts/copilot/components/ChatSearchModal/helpers.ts#L32)）和 [...providers].sort().join(",")（见 connectedProvidersStore.ts/copilot/connectedProvidersStore.ts#L42)）。从源码结构看，后者属于"先复制再排序"的安全写法，即使运行环境不支持 toSorted() 也能正常工作，两种模式可以按团队风格统一。

其他配套的不可变数组方法

规则文档同时列出了 ES2023 引入的完整"不可变数组 API"家族，建议在同一代码库中统一使用：

方法	对应原地方法	语义
.toSorted(compareFn)	.sort(compareFn)	不可变排序
.toReversed()	.reverse()	不可变反转
.toSpliced(start, deleteCount, ...items)	.splice(...)	不可变地插入/删除元素
.with(index, value)	（无直接对应）	返回仅替换一个元素的新数组

这四者与 React 的状态更新模式天然契合：任何需要"基于旧数组得到新数组"的 state 更新，都可以优先查这张表，而不是 slice() + 原地方法 + 再赋值的组合拳。

小结：一条可执行的判断流程

1. 排序目标是 props、state、store 数据或任何可能被共享持有的数组 → 用 .toSorted(compareFn)；
2. 目标浏览器/运行时低于 Chrome 110 / Safari 16 / Firefox 115 / Node 20 → 降级为 [...items].sort(compareFn)；
3. 目标数组是本次调用内由 map/filter 等新建的局部派生数组 → .sort() 不会造成共享数据突变，可继续使用，但从一致性角度仍可统一为 toSorted()；
4. 反转、局部增删、单元素替换等场景，对照上表选用 toReversed / toSpliced / with。

遵循这条规则后，排序操作从"可能有副作用的数据写入"变成"纯函数式的数据读取变换"，这正是 React 不可变数据模型所需要的。