Cloudflare 已给出 Workers KV 旧 API 路由的停用时间，真正危险的不是不会改路径，而是你以为已经改完，结果还有 cron 或 CI 在偷用旧路由。
- 01先读摘要，判断是否与你的场景相关。
- 02再看来源，保留继续查证的路径。
- 03最后看步骤、风险和可复用动作。
Cloudflare 已经把 Workers KV 旧 API 路由的退场时间写得很明确：2026 年 7 月 15 日废弃，2026 年 10 月 15 日停止支持。好消息是，新旧路由的请求参数和响应格式保持兼容，迁移动作看起来只像“改一段 URL 路径”；坏消息是，很多团队在脚本、CI、旧版内部工具和第三方集成里把旧路径写死了。真正危险的不是不会改，而是你以为改完了，结果还有一处 cron 或运维脚本在 10 月后悄悄报错。
适用场景
这篇清单适合所有通过 REST API 操作 Workers KV 的人，尤其是这几类：自己写脚本批量读写 KV 的开发者、把 KV 当配置存储或边缘缓存目录用的小团队、在 CI/CD 中通过 API 管理 namespace 的运维、以及维护老旧工具链的人。只要你的系统里出现过 /accounts/{account_id}/workers/namespaces/ 这段路径，就该做一次盘点。
不适用场景
如果你只通过 Worker binding 在运行时读写 KV，从没碰过 REST API，这次迁移对你影响很小。再一种情况是你完全依赖最新的 Wrangler 命令，没有自写 API 客户端或老脚本，那也通常不需要手工改很多东西。可一旦你们有 shell 脚本、Node/Python 运维脚本、旧版监控探针，或者把 Cloudflare API 路径写进了 GitHub Actions secret、Terraform external data、Zapier/Make webhook，这篇文章就很 relevant。
这次弃用到底改了什么
Cloudflare 在 API deprecations 文档里写得很直接：旧的 KV 路由 /accounts/{account_id}/workers/namespaces/* 被弃用，建议改到文档化的新路由 /accounts/{account_id}/storage/kv/namespaces/*。更关键的一句是：新旧路由在迁移期是可互换的，接受相同的请求参数，返回相同的响应 payload。对大部分团队来说，这意味着迁移不是协议级重写，而是“路径替换 + 全链路回归”。
但别因为这句话就轻视排查。真正难点从来不是 API 语义，而是你是否知道所有旧路径藏在哪里。一个手工维护的备份脚本、一个没人再看的 GitHub Action、一个第三方集成回调，都可能在 10 月 15 日后成为故障点。
准备材料
- Cloudflare account_id 和当前使用的 API token 说明，确认谁有改脚本权限。
- 仓库全文检索能力，至少能搜出
/workers/namespaces/、workers/namespaces、kv/namespaces等关键词。 - 一张路径替换表，记录旧 endpoint、替换后的新 endpoint、脚本位置和责任人。
- 一套验证命令，能对 list、read、write、delete 这几类典型动作各跑一遍。
- 一个冻结窗口，避免你一边改 API 路径，一边又有人在旧分支继续复制旧调用。
步骤一：先做全量搜路径，不要直接开改
最稳的顺序不是“看到一处改一处”，而是先建清单。建议按四个层面查：
- 代码仓库里搜字面路径：
/workers/namespaces/。 - 搜拼接型写法，例如把
workers、namespaces分成常量的代码。 - 查 CI 配置、运维脚本、cron、serverless job 和第三方自动化平台里的 HTTP 请求模板。
- 查内部文档和 runbook，避免以后新同事再把旧路径抄回去。
做完这一步，你应该得到一张“旧路由资产表”，而不是几段零散 commit。迁移最怕的是只改了你看得见的代码，没改那些长期无人值守的辅助脚本。
步骤二：按 Cloudflare 给出的映射表逐条替换
Cloudflare 已经把主要 endpoint 的替换关系列得很清楚。核心规律只有一条：把 URL 路径里的 /workers/namespaces/ 改成 /storage/kv/namespaces/。常见映射包括：
- 列出或创建 namespace：
GET/POST /accounts/{account_id}/workers/namespaces改成GET/POST /accounts/{account_id}/storage/kv/namespaces。 - 获取、重命名、删除 namespace：
.../workers/namespaces/{namespace_id}改成.../storage/kv/namespaces/{namespace_id}。 - 列出 keys：
.../workers/namespaces/{namespace_id}/keys改成.../storage/kv/namespaces/{namespace_id}/keys。 - 读 metadata：
.../workers/namespaces/{namespace_id}/metadata/{key_name}改成.../storage/kv/namespaces/{namespace_id}/metadata/{key_name}。 - 读写删 value：
.../workers/namespaces/{namespace_id}/values/{key_name}改成.../storage/kv/namespaces/{namespace_id}/values/{key_name}。
如果你的客户端把路径模板抽成常量，最好只改一处公共常量，再跑全链路测试。若路径散落多处，先统一成一个 helper，再做替换，后续维护会轻松很多。
步骤三：把迁移分成“读路径”和“写路径”两类验收
看上去只是改 URL，但生产风险并不一样。读路径失败通常是功能降级，写路径失败可能直接让配置不同步、缓存目录失真、灰度规则失效。验收建议分两组：
- 读路径：list namespaces、list keys、read value、read metadata。
- 写路径：create namespace、rename namespace、put value、delete value、delete namespace。
这样分的好处是你能很快知道问题是在“权限/认证”还是“状态变更”。很多团队只测 list 成功就认为迁移结束，结果真正出事的是写路径里某个低频脚本。
步骤四：用并行双跑窗口找漏网之鱼
因为新旧路径在过渡期内可互换，最适合做一次短周期双跑。做法可以很简单：
- 先把主脚本切到新路径。
- 保留一个只读巡检脚本，专门在日志或代码仓里继续搜旧路径调用。
- 连续观察 3 到 7 天，看是否还有来自旧路径的请求日志、失败告警或第三方回调。
- 确认没有旧调用后，再删除兼容代码和旧路径注释。
双跑窗口的价值不在于兼容更久，而在于把“你以为已经迁完”变成“你有证据知道自己迁完了”。
步骤五：把 runbook、模板和 SDK 示例一起改掉
很多 API 迁移在代码上完成了，却又因为内部文档没更新而反复复发。建议同步改三样：
- 内部运维文档里的 curl 示例。
- 给新同事复制的 Postman / Bruno / Insomnia 请求模板。
- 自动化项目里的 README、环境检查脚本和 smoke test。
只要这些地方还写着旧路径，下一个人做新集成时就会把问题重新带回来。
可直接复用的迁移检查清单
- 搜全仓和 CI 配置，列出所有旧路径调用点。
- 按 endpoint 映射表逐条替换到
/storage/kv/namespaces/。 - 把路径模板收口成公共常量或 helper。
- 分开验证读路径和写路径。
- 在过渡期做 3 到 7 天双跑巡检。
- 更新文档、请求模板和示例命令。
- 把 2026-10-15 写进团队日历或升级看板。
- 在最后一次复查里确认没有任何旧路径残留。
实际例子：一个内容站怎样改它的 KV 发布目录脚本
假设你有一个内容站，把栏目路由、A/B 开关和站点小配置存在 KV 里，每次发布后会用 Node 脚本批量写入。这个场景最容易漏掉的是“发布脚本改了，但回滚脚本没改”。更稳的做法是：
- 先搜出发布脚本、回滚脚本、夜间巡检脚本三处调用。
- 把公共 API base path 改成新路径常量。
- 跑一次 staging 写入、读取、删除验证。
- 第二天再手动执行一次回滚脚本，确认旧路径没有残留。
- 最后在 README 里把所有 curl 示例替换掉。
这样做，真正解决的是整条运维链，而不是某一个 happy path。
常见坑
- 只改主代码，不改 CI、cron 和内部工具。
- 只测 list keys，不测 put/delete 这类低频写操作。
- 路径硬编码散落多处，后来有人在旧分支继续复制旧写法。
- 以为 Wrangler 用户不受影响，就忽略了团队里其他 REST API 客户端。
- 文档不更新，三个月后又从 README 抄出旧路径。
排错路径
- 替换后全量失败：先查 API token 权限，而不是默认怀疑新路径本身。
- 读成功写失败：检查写路径有没有漏改到
/values/或 namespace 级 endpoint。 - 主仓已改但告警仍出现：去查第三方自动化平台、内部定时脚本和历史分支。
- 日志里偶发旧路径请求：保留双跑巡检，定位调用来源，再删除残留任务。
- 团队继续提交旧写法：把路径 helper 收口，并在 review checklist 里加入旧路由检查。
后续维护建议
更新日期：2026-07-18。API 路由迁移最值钱的产出，不是把这次 Cloudflare Workers KV 改完，而是顺手建立一套“外部 API 退场时的资产盘点流程”。以后再遇到 API deprecation，直接沿用这次的路径资产表、双跑观察窗和文档同步清单，会比每次临时救火稳得多。尤其别忘了在 2026-10-15 前做一次最终复查，确认旧路径已经彻底退出生产链路。