wrangler dev 本地和线上有什么差别？

我在本地给 wrangler dev 的配置里写了一个根本不存在的 KV id top-kv-id，env.CACHE.put/get 照样正常工作。

wrangler dev 默认在本机跑 Worker，所有绑定也由本地模拟，不碰线上数据。所以本地能验证 API 形状和事务语义，验证不了一致性、性能和真实限流。

原因是本地模拟根本不关心那个 id，它的资源一开始是空的，也与线上没有关系。下面讲三种运行模式怎么区分，哪些东西永远在本地，以及本地文件如何悄悄覆盖配置里的变量。

wrangler dev 到底在跑什么？

默认情况下，它在本机用 Miniflare 和 workerd 跑你的 Worker，绑定由本地模拟，这是官方文档的说法。上面的 KV id 实验是我在本地跑的。

本地是单进程模拟，没有跨地区，也没有真实的限流与延迟。D1、Durable Objects 的 API 形状和事务语义可以本地验证，一致性与性能不行。各存储的细节见 D1 和 Durable Objects。

wrangler dev、remote 绑定和 --remote 怎么区分？

三个层级容易混：

  • wrangler dev（默认）：Worker 在本地，绑定也是本地模拟。
  • 绑定上写 "remote": true：Worker 仍在本地，这一个绑定的调用转发到线上真实资源。适合没有完整本地模拟的产品，比如 Workers AI、Vectorize。它会修改真实数据并可能计费，还会增加网络延迟。
  • wrangler dev --remote：旧模式，代码上传到一个临时预览环境运行，所有绑定都用线上资源，每次保存都要上传。--local 则相反，强制关闭所有 remote 绑定。

以上三条是官方文档的说法，我没有逐一跑过。我的做法是节制使用 remote 绑定：它让「本地跑一下」有了副作用，读多写少、资源是专用测试库时才打开。

官方还列出几个永远本地的例外：环境变量、secrets、静态资源始终是本地的；Durable Objects 和 Workflows 始终在本地跑。

.dev.vars 和 .env 谁优先？

本地 secrets 放在与配置文件同目录的 .dev.vars 或 .env（dotenv 语法，二选一），不要提交 git。我在本地跑出的结果，和官方文档一致：

  1. 存在 .dev.vars 时，同目录的 .env 被完全忽略，启动日志写 Using secrets defined in .dev.vars。
  2. 只有 .env 时才读 .env。
  3. 本地文件里的同名变量覆盖配置里的 vars：.dev.vars 里写 GREETING=dev-vars-wins，env.GREETING 就是它，而不是配置里的值。
  4. wrangler dev --var GREETING:from-flag 覆盖配置里的 vars；同时存在的 .dev.vars 不含该键时，flag 值生效。
  5. 指定 --env staging 时，如果存在 .dev.vars.staging，官方说明只读它，.dev.vars 不再加载。我只确认了没有该文件时会回退读 .dev.vars。.env 一族则不同：官方说明匹配的 .env、.env.local、.env.<环境名>、.env.<环境名>.local 会合并，同名变量取最具体的文件。

为什么「本地正常、线上不对」？

同名变量在本地被悄悄覆盖，是常见来源之一：本地 .dev.vars 里的值盖掉了配置里的 vars，线上却没有这个文件。要么让本地文件只放 secret，要么在 CI 里检查两者的键不重叠。

vars 与 secret 的分工见 vars 和 secrets 有什么区别。--env 选出的环境怎么声明绑定，见 环境为什么不继承绑定。

不存在的 KV id 仍可读写、.dev.vars 与 .env 的优先级第 1 到 4 条、同名变量覆盖，我在 wrangler 4.151.3（workerd 2026-10-19）的 wrangler dev --local 上跑过；--env 下 .dev.vars.<环境名> 的行为我只验证了无该文件时的回退。Miniflare 与 workerd 的说明、remote 绑定与 --remote 的行为、永远本地的例外、.env 一族的合并规则，来自 2026-10 的官方文档，我没有复现，行为会变化，以官方文档为准。参考：本地开发与远程绑定。