ES2024 新特性实战：Promise.withResolvers、Object.groupBy、Promise.try 等你需要知道的 JavaScript 新 API

2024 年 6 月正式发布的 ES2024 规范给 JavaScript 带来了多个开发者期待已久的新特性。其中 Promise.withResolvers() 让你能从 Promise 外部控制其状态，Object.groupBy() 终于让原生数据分组成为可能，Promise.try() 解决了异步错误捕获的历史顽疾。截至 2026 年 5 月，这些特性已在 Chrome 121+、Firefox 128+、Safari 17.4+ 和 Node.js 22+ 中全面可用，全球浏览器覆盖率超过 93%。如果你的代码还在用 reduce 做分组、用 hack 方式暴露 Promise resolve 函数，是时候更新了。

🚀 一、Promise.withResolvers()：反向 Promise 控制模式

1.1 为什么需要 Promise.withResolvers？

在实际开发中，你一定遇到过这种场景：需要在 Promise 外部控制何时 resolve 或 reject——比如把 Promise 包装成回调风格的 API，或者在 WebSocket 消息到达时才 resolve 一个等待中的 Promise。

传统做法是用一个「Deferred 模式」的手动包装：

// ❌ 旧方案：手动暴露 resolve/reject，样板代码多
function createDeferred() {
  let resolve, reject;
  const promise = new Promise((res, rej) => {
    resolve = res;
    reject = rej;
  });
  return { promise, resolve, reject };
}

// 使用
const { promise, resolve, reject } = createDeferred();
setTimeout(() => resolve('完成'), 1000);
const result = await promise; // '完成'

每次都要写 5 行样板代码。ES2024 用一行搞定：

// ✅ ES2024：一行搞定
const { promise, resolve, reject } = Promise.withResolvers();

// 完全等价，但代码量减少 80%
setTimeout(() => resolve('完成'), 1000);
const result = await promise; // '完成'

1.2 实战场景：WebSocket 消息等待器

Promise.withResolvers() 最实用的场景之一是将事件驱动的 API 转换为 Promise 风格：

// WebSocket 请求-响应模式：发送消息后等待特定响应
class WSRequestClient {
  #ws;
  #pending = new Map(); // messageId -> { promise, resolve, reject }

  constructor(url) {
    this.#ws = new WebSocket(url);
    this.#ws.addEventListener('message', (event) => {
      const data = JSON.parse(event.data);
      const pending = this.#pending.get(data.id);
      if (pending) {
        this.#pending.delete(data.id);
        if (data.error) {
          pending.reject(new Error(data.error));
        } else {
          pending.resolve(data.result);
        }
      }
    });
  }

  async request(method, params) {
    const id = crypto.randomUUID();
    const { promise, resolve, reject } = Promise.withResolvers();

    this.#pending.set(id, { promise, resolve, reject });

    // 设置 10 秒超时
    const timer = setTimeout(() => {
      this.#pending.delete(id);
      reject(new Error(`请求超时: ${method}`));
    }, 10_000);

    this.#ws.send(JSON.stringify({ id, method, params }));

    // 确保超时定时器被清理
    promise.finally(() => clearTimeout(timer));
    return promise;
  }
}

// 使用
const client = new WSRequestClient('wss://api.example.com');
const user = await client.request('getUser', { id: 123 });

💡 提示：Promise.withResolvers() 返回的 promise、resolve、reject 三者共享同一个闭包，不会出现旧方案中变量提升导致的时序问题。在 TypeScript 中，它还支持泛型：Promise.withResolvers<string>()。

1.3 实战场景：可取消的异步操作

// 构建可取消的 fetch 请求
function cancellableFetch(url, options = {}) {
  const { promise, resolve, reject } = Promise.withResolvers();
  const controller = new AbortController();

  fetch(url, { ...options, signal: controller.signal })
    .then((response) => resolve(response))
    .catch((err) => reject(err));

  return {
    promise,
    cancel: (reason = '用户取消') => {
      controller.abort();
      reject(new DOMException(reason, 'AbortError'));
    },
  };
}

// 使用
const { promise, cancel } = cancellableFetch('/api/data');
setTimeout(() => cancel('超时取消'), 5000);

try {
  const response = await promise;
  console.log(await response.json());
} catch (err) {
  if (err.name === 'AbortError') {
    console.log('请求已被取消');
  }
}

📊 二、Object.groupBy() 与 Map.groupBy()：原生数据分组

2.1 告别 reduce 分组的痛苦

数据分组是前端开发中最常见的操作之一——按状态分类订单、按日期归类日志、按角色分组用户。以前只能用 reduce 实现，代码又长又难读：

// ❌ 旧方案：reduce 分组，需要理解累加器模式
const orders = [
  { id: 1, status: 'pending', amount: 100 },
  { id: 2, status: 'completed', amount: 250 },
  { id: 3, status: 'pending', amount: 50 },
  { id: 4, status: 'cancelled', amount: 300 },
  { id: 5, status: 'completed', amount: 180 },
];

const grouped = orders.reduce((acc, order) => {
  const key = order.status;
  if (!acc[key]) acc[key] = [];
  acc[key].push(order);
  return acc;
}, {});

ES2024 用 Object.groupBy() 一行搞定：

// ✅ ES2024：语义清晰，意图明确
const grouped = Object.groupBy(orders, (order) => order.status);
// {
//   pending: [{ id: 1, ... }, { id: 3, ... }],
//   completed: [{ id: 2, ... }, { id: 5, ... }],
//   cancelled: [{ id: 4, ... }]
// }

2.2 Object.groupBy vs Map.groupBy：如何选择？

ES2024 同时提供了两个方法，区别在于返回类型和键的类型：

⚠️ **警告：**如果分组键可能是 __proto__、constructor 等特殊字符串，务必使用 Map.groupBy()，避免原型链污染！

// ✅ 当键是对象或非字符串时，使用 Map.groupBy
const users = [
  { name: 'Alice', dept: { id: 1, name: 'Engineering' } },
  { name: 'Bob', dept: { id: 2, name: 'Design' } },
  { name: 'Carol', dept: { id: 1, name: 'Engineering' } },
];

// 用对象作为分组键——Object.groupBy 做不到
const byDept = Map.groupBy(users, (user) => user.dept);
// Map {
//   { id: 1, name: 'Engineering' } => [Alice, Carol],
//   { id: 2, name: 'Design' } => [Bob]
// }

2.3 性能对比：groupBy vs reduce vs for 循环

在 10 万元素数组上的分组性能测试（V8/Chrome 125，取 5 次平均值）：

📌 记住：Object.groupBy() 的性能与手写 for 循环几乎相同（V8 内部做了优化），但可读性远超 reduce。在生产代码中，优先选择 Object.groupBy() 而不是手动循环——代码的可维护性比 1-2ms 的性能差异重要得多。

2.4 实战：多维度数据分析

// 电商订单多维度分析
const orders = [
  { id: 1, category: 'electronics', region: 'north', amount: 2500, date: '2026-05-01' },
  { id: 2, category: 'clothing', region: 'south', amount: 350, date: '2026-05-01' },
  { id: 3, category: 'electronics', region: 'north', amount: 1800, date: '2026-05-02' },
  { id: 4, category: 'food', region: 'east', amount: 120, date: '2026-05-02' },
  { id: 5, category: 'clothing', region: 'north', amount: 680, date: '2026-05-03' },
];

// 按品类分组并计算统计信息
const byCategory = Object.groupBy(orders, (o) => o.category);
const stats = Object.fromEntries(
  Object.entries(byCategory).map(([cat, items]) => [cat, {
    count: items.length,
    total: items.reduce((sum, o) => sum + o.amount, 0),
    avg: Math.round(items.reduce((sum, o) => sum + o.amount, 0) / items.length),
  }])
);
// { electronics: { count: 2, total: 4300, avg: 2150 }, clothing: { count: 2, ... }, ... }

// 链式分组：先按区域，再按品类
const byRegionThenCategory = Object.groupBy(orders, (o) => o.region);
for (const [region, regionOrders] of Object.entries(byRegionThenCategory)) {
  byRegionThenCategory[region] = Object.groupBy(regionOrders, (o) => o.category);
}

🔧 三、Promise.try()：同步错误捕获的终极方案

3.1 异步函数中的「同步异常陷阱」

这是一个被大多数开发者忽视的严重问题。当你在 .then() 链中执行同步代码时，如果同步代码抛出异常，它会被 Promise 捕获——但这只在某些情况下成立：

// ⚠️ 陷阱：同步函数在 .then() 中抛出的异常行为不一致
function riskySyncOperation(input) {
  if (!input) throw new Error('输入不能为空');  // 同步异常
  return input.toUpperCase();
}

// ❌ 问题方案：当 fn 是同步函数且在 Promise 链外调用时
async function processData(input) {
  // 如果 riskySyncOperation 抛出同步异常，
  // 这里会产生一个 unhandled rejection（取决于调用方式）
  return Promise.resolve(input).then(riskySyncOperation);
}

Promise.try() 保证无论函数是同步还是异步，返回值都是 Promise，异常都会被捕获：

// ✅ ES2024：统一的异步入口
async function processData(input) {
  return Promise.try(riskySyncOperation, input)
    .then((result) => `处理完成: ${result}`)
    .catch((err) => `捕获错误: ${err.message}`);
}

// 无论是同步异常还是异步异常，都能正确捕获
await processData(null);   // '捕获错误: 输入不能为空'
await processData('hello'); // '处理完成: HELLO'

3.2 为什么不用 async 函数包装？

你可能会问：把函数声明为 async 不就能捕获同步异常了吗？

// 用 async 包装——可行但有代价
async function riskySyncOperation(input) {
  if (!input) throw new Error('输入不能为空');
  return input.toUpperCase();
}

⚠️ **警告：**盲目将同步函数改为 async 会导致不必要的微任务（microtask）调度。每次调用 async 函数，V8 都会创建一个 Promise 并安排一次微任务。在热路径中，这会产生 2-5μs 的额外开销。Promise.try() 的语义更明确：「我知道这个函数可能是同步的，但我想用 Promise 的方式处理它」。

3.3 实战场景：插件系统中的安全调用

// 插件系统：插件可能是同步或异步的
class PluginRunner {
  #plugins = [];

  register(plugin) {
    this.#plugins.push(plugin);
  }

  async runAll(context) {
    const results = [];

    for (const plugin of this.#plugins) {
      try {
        // ✅ 使用 Promise.try 统一处理同步/异步插件
        const result = await Promise.try(plugin.execute, context);
        results.push({ plugin: plugin.name, result, status: 'success' });
      } catch (err) {
        results.push({ plugin: plugin.name, error: err.message, status: 'failed' });
      }
    }

    return results;
  }
}

// 同步插件
const syncPlugin = {
  name: 'validator',
  execute(ctx) {
    if (!ctx.data) throw new Error('数据缺失');
    return { valid: true };
  },
};

// 异步插件
const asyncPlugin = {
  name: 'enricher',
  async execute(ctx) {
    const response = await fetch(`/api/enrich?id=${ctx.id}`);
    return response.json();
  },
};

const runner = new PluginRunner();
runner.register(syncPlugin);
runner.register(asyncPlugin);
const results = await runner.runAll({ id: 1, data: { name: 'test' } });

📦 四、Array.fromAsync()：异步迭代器转数组

4.1 从异步数据源创建数组

Array.from() 只能处理同步可迭代对象。当你需要把一个异步迭代器（AsyncIterator）转成数组时，以前只能手动循环：

// ❌ 旧方案：手动收集异步迭代器
async function collectAsync(asyncIterable) {
  const result = [];
  for await (const item of asyncIterable) {
    result.push(item);
  }
  return result;
}

// ✅ ES2024：一行搞定
const result = await Array.fromAsync(asyncIterable);

4.2 实战场景：分页 API 数据收集

// 自动分页获取所有数据
async function* fetchAllPages(baseUrl) {
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(`${baseUrl}?page=${page}&limit=100`);
    const data = await response.json();

    yield* data.items; // yield 每个元素

    hasMore = data.hasNextPage;
    page++;
  }
}

// 使用 Array.fromAsync 一次性收集所有分页数据
const allUsers = await Array.fromAsync(fetchAllPages('/api/users'));
console.log(`共获取 ${allUsers.length} 条数据`);

4.3 实战场景：并发异步映射

Array.fromAsync 的第二个参数是映射函数，支持异步：

// 并发处理 URL 列表
const urls = [
  'https://api.example.com/user/1',
  'https://api.example.com/user/2',
  'https://api.example.com/user/3',
];

// 对每个 URL 发起请求并收集结果
const users = await Array.fromAsync(urls, async (url) => {
  const response = await fetch(url);
  return response.json();
});

// 等价于 Promise.all(urls.map(async (url) => { ... }))
// 但语义更清晰，且返回的是真正的 Array

💡 提示：Array.fromAsync(iterable, mapFn) 的映射函数可以是异步的，所有映射会并发执行（类似 Promise.all）。如果某个 Promise reject，整个 Array.fromAsync 会 reject。如果你需要容错，建议在 mapFn 内部用 try...catch。

🔤 五、Well-formed Unicode 字符串：告别乱码代理对

5.1 孤立代理对的隐患

JavaScript 字符串使用 UTF-16 编码。对于 BMP（基本多文种平面）之外的字符（如 emoji 🎉、罕见汉字），需要用两个 UTF-16 代码单元（代理对，Surrogate Pair）表示。但如果代理对不完整（孤立代理），会导致各种诡异问题：

// 孤立代理对的常见来源：字符串截断、网络传输损坏
const broken = 'Hello\uD83D World'; // \uD83D 是孤立的高位代理

// ❌ 问题：JSON.stringify 会抛出语法错误
JSON.stringify(broken); // 可能在某些引擎中抛出异常

// ❌ 问题：TextEncoder 会抛出异常
new TextEncoder().encode(broken); // Uncaught TypeError

ES2024 提供了两个方法来检测和修复：

const broken = 'Hello\uD83D World';
const good = 'Hello 🎉 World';

// 检测字符串是否包含孤立代理对
broken.isWellFormed(); // false
good.isWellFormed();   // true

// 修复：将孤立代理对替换为 U+FFFD（替换字符）
const fixed = broken.toWellFormed(); // 'Hello� World'
fixed.isWellFormed(); // true

5.2 实战：API 响应数据净化

// 在处理外部 API 数据时，确保字符串是 well-formed
function sanitizeStrings(obj) {
  if (typeof obj === 'string') {
    return obj.isWellFormed() ? obj : obj.toWellFormed();
  }
  if (Array.isArray(obj)) {
    return obj.map(sanitizeStrings);
  }
  if (obj !== null && typeof obj === 'object') {
    return Object.fromEntries(
      Object.entries(obj).map(([key, value]) => [key, sanitizeStrings(value)])
    );
  }
  return obj;
}

// 在 fetch 响应处理管道中使用
const response = await fetch('/api/data');
const raw = await response.text();

if (!raw.isWellFormed()) {
  console.warn('API 返回了包含孤立代理对的字符串，已自动修复');
}

const data = JSON.parse(raw.toWellFormed());

📌 **记住：**在处理用户输入、网络响应、文件内容等外部数据时，建议先调用 isWellFormed() 检测。如果返回 false，用 toWellFormed() 修复后再传给 TextEncoder、JSON.stringify 等对字符串格式敏感的 API。

⚡ 六、ArrayBuffer.prototype.transfer()：零拷贝二进制数据转移

6.1 ArrayBuffer 的可转移性问题

在 Web Workers 之间传递大型 ArrayBuffer 时，以前必须选择：postMessage 结构化克隆（慢，复制数据）或 Transferable（快，但原 buffer 被「 neutered」不可用）。

ES2024 给 ArrayBuffer 加了三个新方法，让 buffer 操作更灵活：

// 创建一个 1MB 的 buffer
const original = new ArrayBuffer(1024 * 1024);
const view = new Uint8Array(original);
view[0] = 42;

// transfer()：转移所有权（零拷贝），原 buffer 被 detach
const transferred = original.transfer();
console.log(original.detached);  // true
console.log(transferred.detached); // false
console.log(new Uint8Array(transferred)[0]); // 42

// transferToFixedLength()：转移为不可调整大小的 buffer
const fixed = original.transferToFixedLength();

// resize()：动态调整大小（需要 resizable: true）
const resizable = new ArrayBuffer(1024, { maxByteLength: 4096 });
const resizable2 = resizable.transfer();
console.log(resizable2.maxByteLength); // 4096
resizable2.resize(2048); // 动态扩展

6.2 实战：流式数据处理管道

// 处理大型文件上传的分片缓冲区
class ChunkProcessor {
  #buffer;
  #position = 0;

  constructor(initialSize = 64 * 1024) {
    this.#buffer = new ArrayBuffer(initialSize, { maxByteLength: 1024 * 1024 });
  }

  write(chunk) {
    const needed = this.#position + chunk.byteLength;

    // 如果空间不足，扩展 buffer（零拷贝）
    if (needed > this.#buffer.byteLength) {
      const newCapacity = Math.max(needed, this.#buffer.byteLength * 2);
      this.#buffer.resize(Math.min(newCapacity, this.#buffer.maxByteLength));
    }

    new Uint8Array(this.#buffer).set(new Uint8Array(chunk), this.#position);
    this.#position += chunk.byteLength;
  }

  // 提取已写入的数据，保留剩余空间
  flush() {
    const result = this.#buffer.slice(0, this.#position);
    this.#position = 0;
    return result;
  }
}

// 使用示例
const processor = new ChunkProcessor();
const stream = new Response(largeBlob).body;
const reader = stream.getReader();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  processor.write(value.buffer);
}

const completeBuffer = processor.flush();

🎯 七、兼容性矩阵与渐进增强

截至 2026 年 5 月，各特性的浏览器/运行时支持情况：

⚠️ 警告：Promise.try() 是支持最晚的特性（Chrome 128、Safari 18.2）。如果你需要支持旧版浏览器，可以用 polyfill：const promiseTry = (fn, ...args) => Promise.resolve().then(() => fn(...args))。但注意这个 polyfill 会多一次微任务调度。

💡 八、最佳实践总结

1. ✅ 优先使用 Object.groupBy 替代 reduce 分组——代码更简洁，性能几乎相同
2. ✅ 使用 Promise.withResolvers 构建事件转 Promise 的适配器——比 Deferred 模式更安全
3. ✅ 用 Promise.try 统一同步/异步函数的错误处理——特别是在插件系统和中间件中
4. ✅ 处理外部数据时 调用 isWellFormed() 检测——避免 TextEncoder 和 JSON.stringify 的诡异异常
5. ❌ 不要盲目将同步函数改为 async——Promise.try 是更精确的工具
6. ❌ 不要对 Object.groupBy 的结果做 JSON.stringify 当键含 __proto__——用 Map.groupBy 替代

⚡ **关键结论：**ES2024 的这些新特性不是「锦上添花」——它们解决的是开发者每天都在遇到的实际问题。Promise.withResolvers 消除了 Deferred 反模式，Object.groupBy 消除了 reduce 分组的晦涩代码，Promise.try 统一了同步/异步的错误处理。花 30 分钟学完这些 API，你写的每一行 JavaScript 都会更干净。

如果你在使用 jsjson.com 的 JSON 格式化工具处理 API 返回数据时，可以配合 Object.groupBy 快速分析 JSON 结构中的字段分布。更多前端开发技巧，请关注我们的开发者工具箱。