尧图网站建设 
Cloudflare Workers 兼容性标志解析将unhandledrejection处理推迟到微任务检查点之后【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs导读本文深入解析 Cloudflare Docs 仓库中登记的一项 Workers 运行时兼容性标志unhandled_rejection_after_microtask_checkpoint以及其反相标志no_unhandled_rejection_after_microtask_checkpoint。该标志修正了多跳multi-tickPromise 链中unhandledrejection事件过早触发、从而对实际已被处理的 Promise 产生误报的问题。读完本文你将掌握该标志的行为差异、适用场景、在wrangler.jsonc中的配置方法并了解其与 Workers 运行时unhandledrejection/rejectionhandled事件机制之间的关联。该标志的技术说明源自 unhandled-rejection-after-microtask-checkpoint.md结合仓库中的 Web 标准运行时文档与兼容性标志配置文档进行补充讲解。一、标志速览启用、默认与配套反相标志根据 unhandled-rejection-after-microtask-checkpoint.md 的 frontmatter该标志的关键元数据如下元数据字段值说明nameDefer unhandled rejection processing to after microtask checkpoint标志的人类可读名称sort_date/enable_date2026-03-03标志开始生效并成为默认行为的日期enable_flagunhandled_rejection_after_microtask_checkpoint显式启用该行为时使用的标志名disable_flagno_unhandled_rejection_after_microtask_checkpoint需要回退到旧行为时使用的标志名这些字段与仓库中 compatibility-flags.ts 模式 定义的compatibilityFlagsSchema结构一一对应每个兼容性标志都至少声明name、enable_date、enable_flag与disable_flag或sort_dateenable_date即该标志在默认情况下开始生效的日期。与兼容性日期机制的关系兼容性标志通常对应一个默认启用日期。如 compatibility-flags.mdx 所述Compatibility flags will often have a date in which they are enabled by default, and so, by specifying acompatibility_datefor your Worker, you can quickly enable all of these various compatibility flags up to, and including, that date.也就是说enable_date为2026-03-03意味着凡是将compatibility_date设置为2026-03-03或更晚的 Worker都会自动获得推迟到微任务检查点之后处理 unhandled rejection这一新行为无需显式声明任何标志。二、核心语义什么是在微任务检查点之后处理标志的官方描述unhandled-rejection-after-microtask-checkpoint.md给出了两层含义新行为启用标志后unhandledrejection事件的处理被推迟到微任务检查点microtask checkpoint完成之后再执行。这样一来在多跳 Promise 链中如果拒绝处理器是在后续的某个微任务里才被添加的就不会再被误判为未处理。旧行为未启用时unhandledrejection的处理可能在当前检查点内所有微任务处理完毕之前过早触发从而对实际上已被处理的 Promise 产生误报false positive。底层机制背景微任务与 Promise 拒绝JavaScript 的事件循环在每次脚本执行完成后都会执行一次微任务检查点依次运行当前队列中的全部微任务Promise.then/.catch/.finally回调、queueMicrotask回调、MutationObserver回调等直到队列清空才会继续处理下一个宏任务或触发诸如unhandledrejection之类的清理性检查。问题在于 Promise 的拒绝可能在多个微任务之间传递。典型场景如下// 旧行为下的误报示例 function createRejectionChain() { const p Promise.reject(new Error(boom)); // 拒绝处理器不是立刻附加而是延迟到一个微任务之后 queueMicrotask(() { p.catch((err) { console.log(handled:, err.message); }); }); return p; } addEventListener(unhandledrejection, (event) { // 旧行为这里可能在 p.catch(...) 注册之前就被调用 → 误报 // 新行为微任务检查点全部完成后才评估不会误报 console.log(unhandledrejection fired for, event.promise p); });如果运行时在第一个微任务执行完但queueMicrotask中附加的.catch尚未执行的间隙就评估该 Promise 是否未处理unhandledrejection就会对p误触发一次。启用unhandled_rejection_after_microtask_checkpoint后运行时等待整个微任务检查点完成再判断是否存在仍无拒绝处理器的 Promise从而消除这类误报。为什么这属于兼容性变更该行为变化对既有代码存在可见影响unhandledrejection事件的触发时机与是否触发都变了因此被作为兼容性标志提供而不是直接静默修改运行时。这与仓库中其他同类标志的思路一致例如dont-throw-from-async-functions.md控制异步函数抛错时是同步抛出还是以 Promise rejection 形式呈现handle-cross-request-promise-resolution.md修正 Promise 续延被调度到错误请求上下文的问题。三者共同说明Promise 调度与拒绝处理的时机语义是 Workers 运行时兼容性治理中反复出现的一类主题。三、在 Workers 中观测unhandledrejection事件要验证或使用该标志的行为需要先了解 Workers 运行时如何暴露未处理拒绝事件。相关说明见 web-standards.mdxTheunhandledrejectionevent is emitted by the global scope when a JavaScript promise is rejected without a rejection handler attached.Therejectionhandledevent is emitted by the global scope when a JavaScript promise rejection is handled late (after a rejection handler is attached to the promise after anunhandledrejectionevent has already been emitted).unhandledrejection与rejectionhandled两个事件配合使用可以完整追踪 Promise 拒绝的未处理与迟处理生命周期addEventListener(unhandledrejection, (event) { console.log(event.promise); // 被拒绝且尚未附加处理器的 Promise console.log(event.reason); // 拒绝原因值或 Error 对象 }); addEventListener(rejectionhandled, (event) { console.log(event.promise); // 被拒绝的 Promise console.log(event.reason); // 拒绝原因值或 Error 对象 });两个事件都从全局作用域派发事件对象包含promise被拒绝的 Promise与reason拒绝原因两个关键属性。当启用unhandled_rejection_after_microtask_checkpoint后上述unhandledrejection监听器触发的前提将变为整个微任务检查点结束后该 Promise 仍无拒绝处理器。此前那种微任务内部迟一点才.catch()却被误报的情况将不再出现相应地如果确实在检查点结束后仍未处理事件仍会照常触发你依然可以借此发现真实泄漏的未处理拒绝。值得注意的是异步上下文AsyncLocalStorage文档还展示了unhandledrejection事件处理器中的异步上下文传播行为Promise 拒绝未被处理时异步上下文会传播到unhandledrejection事件处理器因此在该事件处理器内部可以借助异步上下文关联到触发拒绝的调用链路。四、配置方法Wrangler 与 Dashboard该标志属于既可以显式启用、也可以显式禁用的类型。需要手动控制时在 Worker 的 Wrangler 配置文件的compatibility_flags数组中声明即可。配置写法遵循 compatibility-flags.mdx 展示的通用格式。显式启用新行为{ // 早于 2026-03-03 的兼容性日期时需要显式启用 compatibility_date: 2025-12-01, compatibility_flags: [ unhandled_rejection_after_microtask_checkpoint ] }显式回退到旧行为拒绝新行为{ // 兼容性日期已越过 2026-03-03新行为默认开启 // 但若你的代码依赖旧的触发时机可用反相标志关闭 compatibility_date: 2026-05-01, compatibility_flags: [ no_unhandled_rejection_after_microtask_checkpoint ] }其他配置入口Cloudflare Dashboard可在 Worker 的设置页面中修改compatibility_flagscompatibility-flags.mdx。Cloudflare API通过 Workers Script API 或 Workers Versions API 上传 Worker 时在请求体metadata字段的compatibility_flags中指定compatibility-flags.mdx。建议除非确有代码依赖旧的unhandledrejection触发时机例如依赖误报行为做兜底日志、或在微任务内异步注册处理器且无法调整否则应优先跟随默认行为不手动声明no_unhandled_rejection_after_microtask_checkpoint让新行为在2026-03-03及之后的兼容性日期下自动生效。五、适用场景与迁移建议适合启用该标志的场景代码中存在多跳 Promise 链拒绝在若干微任务间传播处理器在后续微任务才附加依赖unhandledrejection做告警或指标统计但被旧行为下的误报污染希望行为与浏览器/标准 Web 平台中对 Promise 拒绝的延迟评估语义保持一致。升级到新行为时的检查清单检查代码中所有addEventListener(unhandledrejection, ...)监听器确认它们不依赖微任务中途即触发这一旧时机在兼容性日期跨过2026-03-03前后分别运行一次包含延迟附加拒绝处理器的测试用例对比unhandledrejection的触发次数如需灰度验证可先在compatibility_flags中显式添加unhandled_rejection_after_microtask_checkpoint在早于2026-03-03的兼容性日期上先行试跑确认无误后再提升compatibility_date若确有依赖旧行为且短期无法重构的代码显式声明no_unhandled_rejection_after_microtask_checkpoint并持续跟踪该标志在后续兼容性日期中的变化。配套事件rejectionhandled当启用新行为后原本可能被误报为unhandledrejection的 Promise 不再触发该事件但如果某些拒绝确实在事件已派发之后才被处理rejectionhandled仍会按既有语义触发见 web-standards.mdx可用于衡量未处理持续时间或补偿式日志。两者配合使用能更准确地刻画拒绝处理的全过程。六、小结unhandled_rejection_after_microtask_checkpoint是 Cloudflare Workers 在 Promise 拒绝语义上的一次精确修正它将unhandledrejection的评估时机推迟到微任务检查点结束之后消除了多跳 Promise 链中因处理器注册稍晚而产生的误报。核心要点回顾默认启用日期2026-03-03参见 unhandled-rejection-after-microtask-checkpoint.md启用标志unhandled_rejection_after_microtask_checkpoint禁用标志no_unhandled_rejection_after_microtask_checkpoint配置入口wrangler.jsonc的compatibility_flags数组、Cloudflare Dashboard 或 Cloudflare API 的metadata.compatibility_flags观测手段全局unhandledrejection/rejectionhandled事件事件对象含promise与reason参见 web-standards.mdx。在升级兼容性日期时建议对依赖unhandledrejection的观测与告警代码做一次针对延迟附加拒绝处理器场景的回归测试确保新语义下事件触发时机符合预期。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Workers 兼容性标志解析：将 `unhandledrejection` 处理推迟到微任务检查点之后
Cloudflare Workers 兼容性标志解析将unhandledrejection处理推迟到微任务检查点之后【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs导读本文深入解析 Cloudflare Docs 仓库中登记的一项 Workers 运行时兼容性标志unhandled_rejection_after_microtask_checkpoint以及其反相标志no_unhandled_rejection_after_microtask_checkpoint。该标志修正了多跳multi-tickPromise 链中unhandledrejection事件过早触发、从而对实际已被处理的 Promise 产生误报的问题。读完本文你将掌握该标志的行为差异、适用场景、在wrangler.jsonc中的配置方法并了解其与 Workers 运行时unhandledrejection/rejectionhandled事件机制之间的关联。该标志的技术说明源自 unhandled-rejection-after-microtask-checkpoint.md结合仓库中的 Web 标准运行时文档与兼容性标志配置文档进行补充讲解。一、标志速览启用、默认与配套反相标志根据 unhandled-rejection-after-microtask-checkpoint.md 的 frontmatter该标志的关键元数据如下元数据字段值说明nameDefer unhandled rejection processing to after microtask checkpoint标志的人类可读名称sort_date/enable_date2026-03-03标志开始生效并成为默认行为的日期enable_flagunhandled_rejection_after_microtask_checkpoint显式启用该行为时使用的标志名disable_flagno_unhandled_rejection_after_microtask_checkpoint需要回退到旧行为时使用的标志名这些字段与仓库中 compatibility-flags.ts 模式 定义的compatibilityFlagsSchema结构一一对应每个兼容性标志都至少声明name、enable_date、enable_flag与disable_flag或sort_dateenable_date即该标志在默认情况下开始生效的日期。与兼容性日期机制的关系兼容性标志通常对应一个默认启用日期。如 compatibility-flags.mdx 所述Compatibility flags will often have a date in which they are enabled by default, and so, by specifying acompatibility_datefor your Worker, you can quickly enable all of these various compatibility flags up to, and including, that date.也就是说enable_date为2026-03-03意味着凡是将compatibility_date设置为2026-03-03或更晚的 Worker都会自动获得推迟到微任务检查点之后处理 unhandled rejection这一新行为无需显式声明任何标志。二、核心语义什么是在微任务检查点之后处理标志的官方描述unhandled-rejection-after-microtask-checkpoint.md给出了两层含义新行为启用标志后unhandledrejection事件的处理被推迟到微任务检查点microtask checkpoint完成之后再执行。这样一来在多跳 Promise 链中如果拒绝处理器是在后续的某个微任务里才被添加的就不会再被误判为未处理。旧行为未启用时unhandledrejection的处理可能在当前检查点内所有微任务处理完毕之前过早触发从而对实际上已被处理的 Promise 产生误报false positive。底层机制背景微任务与 Promise 拒绝JavaScript 的事件循环在每次脚本执行完成后都会执行一次微任务检查点依次运行当前队列中的全部微任务Promise.then/.catch/.finally回调、queueMicrotask回调、MutationObserver回调等直到队列清空才会继续处理下一个宏任务或触发诸如unhandledrejection之类的清理性检查。问题在于 Promise 的拒绝可能在多个微任务之间传递。典型场景如下// 旧行为下的误报示例 function createRejectionChain() { const p Promise.reject(new Error(boom)); // 拒绝处理器不是立刻附加而是延迟到一个微任务之后 queueMicrotask(() { p.catch((err) { console.log(handled:, err.message); }); }); return p; } addEventListener(unhandledrejection, (event) { // 旧行为这里可能在 p.catch(...) 注册之前就被调用 → 误报 // 新行为微任务检查点全部完成后才评估不会误报 console.log(unhandledrejection fired for, event.promise p); });如果运行时在第一个微任务执行完但queueMicrotask中附加的.catch尚未执行的间隙就评估该 Promise 是否未处理unhandledrejection就会对p误触发一次。启用unhandled_rejection_after_microtask_checkpoint后运行时等待整个微任务检查点完成再判断是否存在仍无拒绝处理器的 Promise从而消除这类误报。为什么这属于兼容性变更该行为变化对既有代码存在可见影响unhandledrejection事件的触发时机与是否触发都变了因此被作为兼容性标志提供而不是直接静默修改运行时。这与仓库中其他同类标志的思路一致例如dont-throw-from-async-functions.md控制异步函数抛错时是同步抛出还是以 Promise rejection 形式呈现handle-cross-request-promise-resolution.md修正 Promise 续延被调度到错误请求上下文的问题。三者共同说明Promise 调度与拒绝处理的时机语义是 Workers 运行时兼容性治理中反复出现的一类主题。三、在 Workers 中观测unhandledrejection事件要验证或使用该标志的行为需要先了解 Workers 运行时如何暴露未处理拒绝事件。相关说明见 web-standards.mdxTheunhandledrejectionevent is emitted by the global scope when a JavaScript promise is rejected without a rejection handler attached.Therejectionhandledevent is emitted by the global scope when a JavaScript promise rejection is handled late (after a rejection handler is attached to the promise after anunhandledrejectionevent has already been emitted).unhandledrejection与rejectionhandled两个事件配合使用可以完整追踪 Promise 拒绝的未处理与迟处理生命周期addEventListener(unhandledrejection, (event) { console.log(event.promise); // 被拒绝且尚未附加处理器的 Promise console.log(event.reason); // 拒绝原因值或 Error 对象 }); addEventListener(rejectionhandled, (event) { console.log(event.promise); // 被拒绝的 Promise console.log(event.reason); // 拒绝原因值或 Error 对象 });两个事件都从全局作用域派发事件对象包含promise被拒绝的 Promise与reason拒绝原因两个关键属性。当启用unhandled_rejection_after_microtask_checkpoint后上述unhandledrejection监听器触发的前提将变为整个微任务检查点结束后该 Promise 仍无拒绝处理器。此前那种微任务内部迟一点才.catch()却被误报的情况将不再出现相应地如果确实在检查点结束后仍未处理事件仍会照常触发你依然可以借此发现真实泄漏的未处理拒绝。值得注意的是异步上下文AsyncLocalStorage文档还展示了unhandledrejection事件处理器中的异步上下文传播行为Promise 拒绝未被处理时异步上下文会传播到unhandledrejection事件处理器因此在该事件处理器内部可以借助异步上下文关联到触发拒绝的调用链路。四、配置方法Wrangler 与 Dashboard该标志属于既可以显式启用、也可以显式禁用的类型。需要手动控制时在 Worker 的 Wrangler 配置文件的compatibility_flags数组中声明即可。配置写法遵循 compatibility-flags.mdx 展示的通用格式。显式启用新行为{ // 早于 2026-03-03 的兼容性日期时需要显式启用 compatibility_date: 2025-12-01, compatibility_flags: [ unhandled_rejection_after_microtask_checkpoint ] }显式回退到旧行为拒绝新行为{ // 兼容性日期已越过 2026-03-03新行为默认开启 // 但若你的代码依赖旧的触发时机可用反相标志关闭 compatibility_date: 2026-05-01, compatibility_flags: [ no_unhandled_rejection_after_microtask_checkpoint ] }其他配置入口Cloudflare Dashboard可在 Worker 的设置页面中修改compatibility_flagscompatibility-flags.mdx。Cloudflare API通过 Workers Script API 或 Workers Versions API 上传 Worker 时在请求体metadata字段的compatibility_flags中指定compatibility-flags.mdx。建议除非确有代码依赖旧的unhandledrejection触发时机例如依赖误报行为做兜底日志、或在微任务内异步注册处理器且无法调整否则应优先跟随默认行为不手动声明no_unhandled_rejection_after_microtask_checkpoint让新行为在2026-03-03及之后的兼容性日期下自动生效。五、适用场景与迁移建议适合启用该标志的场景代码中存在多跳 Promise 链拒绝在若干微任务间传播处理器在后续微任务才附加依赖unhandledrejection做告警或指标统计但被旧行为下的误报污染希望行为与浏览器/标准 Web 平台中对 Promise 拒绝的延迟评估语义保持一致。升级到新行为时的检查清单检查代码中所有addEventListener(unhandledrejection, ...)监听器确认它们不依赖微任务中途即触发这一旧时机在兼容性日期跨过2026-03-03前后分别运行一次包含延迟附加拒绝处理器的测试用例对比unhandledrejection的触发次数如需灰度验证可先在compatibility_flags中显式添加unhandled_rejection_after_microtask_checkpoint在早于2026-03-03的兼容性日期上先行试跑确认无误后再提升compatibility_date若确有依赖旧行为且短期无法重构的代码显式声明no_unhandled_rejection_after_microtask_checkpoint并持续跟踪该标志在后续兼容性日期中的变化。配套事件rejectionhandled当启用新行为后原本可能被误报为unhandledrejection的 Promise 不再触发该事件但如果某些拒绝确实在事件已派发之后才被处理rejectionhandled仍会按既有语义触发见 web-standards.mdx可用于衡量未处理持续时间或补偿式日志。两者配合使用能更准确地刻画拒绝处理的全过程。六、小结unhandled_rejection_after_microtask_checkpoint是 Cloudflare Workers 在 Promise 拒绝语义上的一次精确修正它将unhandledrejection的评估时机推迟到微任务检查点结束之后消除了多跳 Promise 链中因处理器注册稍晚而产生的误报。核心要点回顾默认启用日期2026-03-03参见 unhandled-rejection-after-microtask-checkpoint.md启用标志unhandled_rejection_after_microtask_checkpoint禁用标志no_unhandled_rejection_after_microtask_checkpoint配置入口wrangler.jsonc的compatibility_flags数组、Cloudflare Dashboard 或 Cloudflare API 的metadata.compatibility_flags观测手段全局unhandledrejection/rejectionhandled事件事件对象含promise与reason参见 web-standards.mdx。在升级兼容性日期时建议对依赖unhandledrejection的观测与告警代码做一次针对延迟附加拒绝处理器场景的回归测试确保新语义下事件触发时机符合预期。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考