部署不再打断进行中的活：Cloudflare Durable Objects 默认延迟更新代码

部署新代码的时候，最怕的不是新代码有问题，而是旧代码正在做的事情被半路掐断。2026 年 10 月 30 日，Cloudflare 把 Durable Objects 的默认行为改了：以后部署不再立刻替换正在运行的代码，而是默认延迟更新。一个正在活动的对象可以继续跑旧代码，最长等上 5 分钟，直到它自己休眠为止。这是一个很小、但很实在的改动：它把“部署”从一件会打断用户的操作，变成了一件可以在后台悄悄完成的操作。

理解这个改动，先要理解 Durable Objects 到底是什么。它不是普通的无状态函数。普通的函数跑完一次请求就结束，下一次请求可能跑在另一台机器、另一个版本上。Durable Objects 不一样：每一个对象在全球都是唯一的，而且同一时间只能跑一个版本代码。正是这个“唯一”和“单版本”的特性，让它能干别的服务干不了的活：维持一个长期存在的聊天室，让几十个人在同一个房间里收发消息；保存一场游戏的实时状态，让所有玩家看到同一局棋；跑一个长时间运行的智能体任务，让它一步一步往下推进，中途还能记住自己做到哪一步了。

但这个优点以前也带来一个代价。既然同一时间只能跑一个版本，那么部署新代码的时候，正在运行的旧版本就必须让位。过去的做法是立刻替换：新代码一部署，正在进行中的工作就可能被打断，打开的连接也可能被直接关掉。对用户来说，这表现为聊天突然断线、游戏状态丢失、智能体任务跑到一半没了下文。对开发者来说，这表现为部署时间不敢随便选，深夜发版、周末发版、甚至“等用户都睡了再发版”，成了一种无奈的习惯。

新默认：先让旧代码把活干完

从这次改动开始，默认策略变成了延迟更新。部署之后，正在活动的对象不会立刻换代码，而是继续用旧代码运行，同时等待一个合适的切换时机。这个时机就是“休眠”。所谓休眠，用大白话讲就是：对象暂时没事可做了，进入休息状态；下一次有请求进来的时候，它会醒过来，而醒过来的时候，就可以直接用新代码了。整个过程对用户来说几乎没有感觉，因为切换发生在两次请求之间，而不是某一次请求进行到一半的时候。

具体流程是这样的：你部署了新代码；活动的对象继续跑旧代码；如果它在延迟结束之前休眠了，那么下一个请求就会在新代码上启动；如果延迟先结束了，它还没有休眠，那么它会被重置，并采用新代码。另外还有一条手动通道：如果你在某次部署里明确选择了立即模式，对象也会立刻重置并采用新代码。这条流程图式地看很简单，但它解决的正是过去最痛的那一点：部署不再默认等于中断。

这里有一个细节值得单独说清楚：用 Hibernation API 的 WebSocket 连接，在对象休眠后采用新代码时，会保持连接不断。也就是说，聊天室里的用户不会因为一次部署就掉线，他们的连接还在，只是背后的代码版本悄悄换了。这对实时应用来说意义很大。过去很多团队为了不掉线，不得不在应用层自己做重连、做断线续传、做状态恢复；现在平台把最难的那一环接过去了。当然，这不等于所有 WebSocket 连接都自动不断线，前提是你用了 Hibernation API；如果你没有用这个接口，部署行为还是要按你自己的连接管理方式来评估，不能想当然。

为什么这对 vibe 项目尤其重要

很多 vibe 项目恰恰是最容易被旧行为伤害的那一类。一个人用 AI 搭出来的小产品，往往没有专职的运维，也没有复杂的发布流程，部署就是点一下按钮，或者推一次代码。但它跑的活却一点都不“小”：一个聊天机器人正在帮用户一步一步改简历，一个智能体正在查资料、调工具、写报告，一个小游戏房间里几个人正在对局。这些活都有一个共同点：它们不是一瞬间完成的，它们需要时间，需要连续性，中途断掉就很难无缝接上。

以前，这类项目部署时经常出现一种很尴尬的局面：作者刚修好一个小问题、兴冲冲地发了新版，结果正在用的用户反而先遭了殃——对话断了、任务停了、房间散了。用户不会知道这是部署造成的，他们只会觉得这个产品不稳定。而作者也很难解释：代码明明是越改越好，怎么用户体验反而变差了。延迟更新把这个矛盾缓和了：新代码照样可以发，正在进行的活也有机会先跑完。部署频率因此可以更高，作者不用再为了“别打断人”而把十个小修复攒成一次大发布。

更重要的是，这个改动降低了“不敢部署”的心理成本。对独立开发者和小团队来说，发布节奏本身就是产品迭代速度的一部分。如果每一次部署都要挑时间、看流量、祈祷没人正在用，那么迭代就会越来越慢，越来越保守。默认延迟更新并不能解决所有问题，但它至少把部署从“高风险操作”降级成“常规操作”。这对还在找方向、需要快速试错的 vibe 项目来说，是实实在在的帮助。

诚实地说：5 分钟是宽限期，不是保证

这个改动值得肯定，但不能把它理解成“部署再也不会打断任何事”。Cloudflare 在原文里把话说得很清楚：延迟更新是尽力而为，不保证每一项操作都能完成。对象仍然有可能在达到最长延迟之前就被重置，一个明确的例子是 Cloudflare 自身的运行时更新。也就是说，5 分钟是一个宽限期，不是一张保险单。超过 5 分钟还没休眠的对象会被重置；不到 5 分钟、但遇到平台侧重置的对象，同样会被重置。

这个区别非常关键，因为它决定了你应该怎么设计自己的程序。如果你把延迟更新当成保证，就会写出“反正部署不会打断我，任务跑多久都没关系”的代码，结果在某个深夜的运行时更新面前照样断掉。正确的心态是反过来的：延迟更新让大多数部署变得温和，但你的程序本身仍然要为“随时可能被重置”做好准备。这不是 Cloudflare 独有的问题，而是所有长期运行任务的通用功课。

具体来说，有两件事仍然不能省。第一是幂等处理：同一个操作被执行两次，结果应该和执行一次一样。举个例子，扣费、发消息、写一条记录，这些操作如果因为重置而被重跑一次，不能造成重复扣费、重复发送、重复记账。第二是可恢复的步骤设计：智能体的每一步做完之后，要把进度存下来，而不是只存在内存里。这样即使对象被重置，下一次醒来也能从上一步接着做，而不是从头再来。这两件事做到了，延迟更新带来的好处才能真正落袋；做不到，5 分钟的宽限期只不过是把断掉的时间点往后推了 5 分钟。

还有一个容易被忽略的点：延迟不等于“旧代码可以无限期跑下去”。默认最长延迟是 300 秒，也就是 5 分钟。如果你有一个任务注定要跑半小时，那么它在部署面前依然会被打断，只是断在 5 分钟之后，而不是立刻断。对于这类超长任务，正确的做法不是把延迟调到最大就了事，而是把任务拆成小步骤、把进度落盘、让它本身就能断点续跑。延迟配置是缓冲，不是解决方案。

配置方法：三行就能改，关键是想清楚延迟设多长

改动是默认生效的，也就是说，你不需要做任何事，就能享受到默认 5 分钟的延迟。但如果你想把延迟改长或改短，可以在 Wrangler 配置里通过 code_update_strategy 来设置。JSON 配置的写法如下：

{
	"durable_objects": {
		"bindings": [
			{
				"name": "CHAT_ROOM",
				"class_name": "ChatRoom"
			}
		],
		"code_update_strategy": {
			"mode": "deferred",
			"max_delay": 60
		}
	}
}

如果你用的是 TOML 配置，写法对应如下：

[[durable_objects.bindings]]
name = "CHAT_ROOM"
class_name = "ChatRoom"

[durable_objects.code_update_strategy]
mode = "deferred"
max_delay = 60

这里的 max_delay 单位是秒，范围是 0 到 86400，也就是最长 24 小时，支持毫秒精度。不填这个字段，就用默认的 300 秒。选多长，没有标准答案，要看你的业务：聊天室、游戏房间这类“一次会话通常几分钟”的场景，默认 5 分钟往往就够了；智能体任务如果单步耗时较长，可以适当放宽，但不要一上来就拉到 24 小时——延迟越长，旧代码在外面的存活时间就越长，紧急修复生效的时间也就越晚。这个取舍，下面讲立即模式的时候还会再提到。

除了改配置文件，还可以在某一次部署里单独指定策略。这对“平时延迟、偶尔立即”的团队特别有用，命令如下：

npx wrangler versions deploy <VERSION_ID>@100% --durable-objects-code-update-mode immediate

把 immediate 换成 deferred 加时长，也可以对某一次部署单独用延迟模式。需要注意的是，这里的版本号和百分比要换成你自己的实际值，上面命令里的占位符不能直接复制运行。这个单次覆盖的设计很好：它让默认策略保持温和，同时给特殊情况留了一条快车道，不用为了发一次紧急修复就去改配置文件、发完再改回来。

什么时候应该主动用立即模式

默认延迟很好，但不是所有时候都应该延迟。有三种情况，主动用立即模式是更负责任的选择。第一种是安全事件：如果旧代码里有一个正在被利用的漏洞，或者泄露了不该泄露的数据，那么让旧代码再多跑 5 分钟，就是多 5 分钟的风险窗口。这时候不要犹豫，直接立即更新，哪怕会打断几个正在进行的操作，因为安全风险的代价远大于几次中断。

第二种是坏部署：如果刚发上去的版本本身就是错的，或者你发现上一版有严重问题、必须立刻回到新版本，那么延迟只会拖长错误代码的存活时间。这时候同样应该立即切换，让正确的代码尽快接管。第三种是部署后工具链必须立刻命中新代码的情况。Cloudflare 原文举了一个例子：你的部署工具在部署完成之后会立刻调用 Durable Object，而且这次调用必须跑在新代码上。如果用默认延迟，这次调用可能还落在旧代码上，工具链的判断就会出错。对这种“部署完马上验证、验证必须看到新行为”的流程，单次立即模式是最干净的做法。

判断标准其实可以归结成一句话：延迟保护的是“正在进行的操作”，立即保护的是“尽快生效的新代码”。当新代码生效的紧迫性高于旧操作完成的价值时，就选立即；反过来，平时绝大多数的常规功能迭代，都应该让延迟默认去保护用户。这条标准写下来很简单，但在凌晨两点处理事故的时候，能帮你少纠结几分钟。

切换后要测的四件事

默认改了，不等于你的应用自动就没问题了。下面四件事，建议在切换后的第一次部署里逐一测一遍。第一，测进行中的 WebSocket：打开一个用了 Hibernation API 的聊天连接，在里面发几条消息，然后部署一次，看连接是不是还活着、消息是不是还能正常收发。如果连接断了，先查自己是不是真的用了 Hibernation API，而不是先怀疑平台。

第二，测跑到一半的智能体步骤：启动一个多步骤的任务，让它跑到中间某一步，然后部署，看任务是顺利跑完了，还是被重置了；如果被重置了，看它能不能从上一步接着做，而不是从头重来，或者更糟——重复执行了已经做过的步骤。这一步测的是你自己的幂等和断点续跑设计，不是平台的延迟功能。

第三，测“部署完立刻调用”的场景：部署之后马上发一次请求，看这次请求跑在旧代码上还是新代码上。这个结果决定了你的部署后验证脚本、健康检查、冒烟测试应该怎么写。如果你的验证脚本假设“部署完立刻就是新代码”，而实际用的是默认延迟，那么脚本第一次跑就可能误报，需要把验证逻辑改成“等对象休眠后再验证”，或者对验证那次部署单独用立即模式。

第四，测延迟本身的边界：故意让一个对象在部署后保持活跃、超过默认的 5 分钟，看它是不是如预期那样被重置并采用新代码。这一步看起来有点反直觉——为什么要测“被打断”的情况？因为你需要亲眼确认边界行为，而不是只在顺利的时候相信它。知道它在什么情况下会断，比知道它在什么情况下不断更重要，这样你写给用户的提示、重试逻辑和超时设置才有依据。

在选延迟时长的时候，还有一个很实际的建议：先从默认的 5 分钟用起，不要急着改配置。很多小项目的问题并不出在延迟不够长，而是出在任务本身没有断点续跑的能力。先把上面四项测试跑通，看看自己的对象通常多久会休眠、任务被重置后能不能接着做，再根据实测结果决定要不要放宽到 10 分钟或者更长。如果测试发现大部分对象在两三分钟内就会休眠，那么默认 5 分钟已经绰绰有余，改配置只是多此一举；如果测试发现某个长任务总是顶到 5 分钟边界才被重置，那要修的也不是延迟数字，而是任务拆分方式。配置应该跟着实测走，而不是跟着感觉走。

把这四件事跑通之后，你对这次改动的理解就从“看过新闻”变成了“在自己的项目里验证过”。这也是 vibe 项目最需要的状态：不是追每一个新功能，而是把对自己有用的新功能真正落地、测过、写进自己的发布习惯里。Cloudflare 这次改动没有引入新的概念，没有要求重写代码，它只是把默认值从“立刻打断”换成了“尽量等一等”。但正是这种默认值级别的改动，影响面最大：所有没有特意配置过的项目，都会默认变得更温和一点。而对那些正在用 Durable Objects 跑智能体、聊天室和游戏状态的项目来说，这一点温和，可能就是用户留下来和用户流失之间的区别。