为什么setTimeout最多只能等24.8天深度揭秘delay的无限延迟原理【免费下载链接】delayDelay a promise a specified amount of time项目地址: https://gitcode.com/gh_mirrors/de/delaydelay 是一个轻量的 Promise 延迟delay Promise工具一行await delay(1000)即可精准等待 1 秒。本文先讲透 setTimeout 的 24.8 天上限是怎么来的再揭秘 delay 库如何通过分块拆单实现无限时长的延迟最后附上新手快速上手指南。setTimeout 的 24.8 天天花板是怎么来的 这是一道 32 位整数的算术题32 位有符号整数的最大值是2^31 − 1 2147483647。浏览器与 Node.js 的规范中setTimeout的延迟参数就是按 32 位整型处理的由此产生一个隐藏上限你想延迟的时间实际发生的事结果1000 ms正常执行等 1 秒30 天2592000000 ms超出上限被截断为 2147483647 ms只等了约 24.85 天超大数值旧环境整型回绕可能几乎立即执行也就是说setTimeout(fn, 30 * 24 * 3600 * 1000)永远不会等满 30 天——它会被静默截断到 2147483647 ms折合约 24.85 天而且不抛任何错误这是典型的无声陷阱。delay 的无限延迟原理分块递归delay 的秘诀在于它依赖的unlimited-timeout模块。当传入的延迟时长超过 2^31−1 ms 时它会把大计时器递归拆分成多段每一段都不超过 24.8 天的天花板前一段结束时自动再排下一段直到总时长耗尽。整段等待对用户来说浑然一体。在源码 index.js 中默认的 delay 实例注入的就是这对安全计时器import {setTimeout as safeSetTimeout, clearTimeout as safeClearTimeout} from unlimited-timeout; const delay createDelay({setTimeout: safeSetTimeout, clearTimeout: safeClearTimeout});巧妙之处在于短延迟走原生 setTimeout 路径零额外开销只有时长超过天花板时才启用分块逻辑。你甚至感觉不到它的存在 delay 使用指南从一行代码到全套能力一行代码延迟 Promiseimport delay from delay; await delay(1000); // 1 秒后继续执行用 value 让等待有返回值const result await delay(100, {value: done}); // 100 ms 后result done用 AbortSignal 随时取消const controller new AbortController(); await delay(1000, {signal: controller.signal});传入AbortSignal后一旦外部调用abort()Promise 立即以AbortError拒绝。爬虫、队列、重试退避等需要随时可取消的长等待场景都能用。clearDelay提前结束等待把 delay 的 Promise 交给clearDelay(delayPromise)它会取消计时器并立即让 Promise 结算测试里特别好用test.js 中有完整用例。rangeDelay随机时长延迟rangeDelay(min, max)在区间内随机等待一段时间。测试断言与网页抓取的性能往往不稳定给它一个随机阈值比写死固定值更稳。createDelay注入自定义计时器如果你的测试全局 mock 了setTimeoutfake timers可以把自定义的setTimeout/clearTimeout传给createDelay生成一个独立实例让测试计时器和 delay 各玩各的。类型定义见 index.d.ts。快速上手安装与源码阅读安装npm install delay要求 Node.js ≥ 20见 package.json想深入源码克隆仓库阅读git clone https://gitcode.com/gh_mirrors/de/delay官方文档说明见 readme.md覆盖全部 API 与示例 小贴士如果你只面向 Node.js也可以用官方的node:timers/promises里的setTimeoutdelay 的价值在于浏览器支持和 value、signal、随机区间等附加能力。总结setTimeout 受 32 位整型限制延迟上限为 2^31−1 ms ≈24.85 天超时会被静默截断delay 借助 unlimited-timeout 的分块递归实现任意时长的 Promise 延迟短延迟依旧零开销附加能力一应俱全value返回值、AbortSignal取消、clearDelay提前结算、rangeDelay随机延迟、createDelay自定义计时器下次需要等 30 天再执行时别再依赖原生 setTimeout 了——让 delay 替你拆单。【免费下载链接】delayDelay a promise a specified amount of time项目地址: https://gitcode.com/gh_mirrors/de/delay创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考