从 Version 2 迁移

Miniflare v3 现在使用 workerd ↗， 开源 Cloudflare Workers 运行时。这与 Cloudflare 网络上部署的 运行时相同，提供逐 bug 兼容并几乎 消除了行为差异。更多信息请参阅 Miniflare v3 ↗ 和 Wrangler v3 发布公告 ↗。

Miniflare v3 不再包含独立 CLI。要获得相同功能， 你需要切换到 Wrangler。Wrangler v3 默认使用 Miniflare v3。要启动本地开发服务器，请运行：

$ npx wrangler@3 dev

如果你希望 Wrangler 支持 Miniflare CLI 中的某些功能， 请在 GitHub ↗ 上提交 issue。

我们尽量使 Miniflare v3 的 API 与 Miniflare v2 保持接近， 但切换到开源 workerd 运行时时，许多选项和方法已被移除或更改。请参阅新 API 文档的快速入门指南

• kvNamespaces/r2Buckets/d1Databases

  • 除了 string[] 外，这些选项现在还接受 Record<string, string>，将绑定（binding）名称映射到命名空间 ID/存储桶 名称/数据库 ID。这意味着多个 Worker 可以在不同名称下绑定到同一 命名空间/存储桶/数据库。

• queueBindings

  • 重命名为 queueProducers。它接受将绑定（binding）名称映射到队列名称的 Record<string, string>， 或绑定（binding）名称与同名队列的 string[]。

• queueConsumers

  • 接受将队列名称映射到消费者选项的 Record<string, QueueConsumerOptions>， 或使用默认选项消费的队列名称 string[]。 QueueConsumerOptions 具有以下类型：

    interface QueueConsumerOptions {
    	// /queues/platform/configuration/#consumer
    	maxBatchSize?: number; // default: 5
    	maxBatchTimeout?: number /* seconds */; // default: 1
    	maxRetries?: number; // default: 2
    	deadLetterQueue?: string; // default: none
    }

• cfFetch

  • 重命名为 cf。可接受 boolean、string（与之前相同）或 用作传入请求 cf 对象的对象。

• wranglerConfigPath/wranglerConfigEnv

  • Miniflare 不再处理 Wrangler 的配置。要基于 Wrangler 配置以编程方式 启动 Worker，请使用 unstable_dev() API。

• packagePath

  • Miniflare 不再从 package.json 文件加载脚本路径。请使用 scriptPath 选项指定脚本。

• watch

  • Miniflare 的 API 主要用于测试场景，通常不需要文件 监听。此选项用于启用现已移除的 Miniflare CLI。如果你需要监听文件，请考虑使用独立的文件监听器，如 fs.watch() ↗ 或 chokidar ↗，并在变更时调用 setOptions() 并传入原始配置。

• logUnhandledRejections

  • 可以在 Worker 中使用 addEventListener("unhandledrejection") ↗ 处理未捕获的 rejection。

• globals

  • workerd ↗ 不支持注入任意全局变量。如果你使用 service worker，bindings 将作为全局变量注入，但这些必须是 JSON 可序列化的。

• https/httpsKey(Path)/httpsCert(Path)/httpsPfx(Path)/httpsPassphrase

  • Miniflare 尚不支持启动 HTTPS 服务器。这些选项可能在 未来版本中重新添加。

• crons

  • workerd ↗ 尚不支持 触发 scheduled 事件。此选项可能在 未来版本中重新添加。

• mounts

  • Miniflare 不再有父 Worker 和子 Worker 的概念。相反， 所有 Worker 可以在同一层级定义，使用新的 workers 选项。以下示例使用 service binding 在共享 KV 命名空间中递增一个值：

    import { Miniflare, Response } from "miniflare";
    
    const message = "The count is ";
    const mf = new Miniflare({
    	// Options shared between Workers such as HTTP and persistence configuration
    	// should always be defined at the top level.
    	host: "0.0.0.0",
    	port: 8787,
    	kvPersist: true,
    
    	workers: [
    		{
    			name: "worker",
    			kvNamespaces: { COUNTS: "counts" },
    			serviceBindings: {
    				INCREMENTER: "incrementer",
    				// Service bindings can also be defined as custom functions, with access
    				// to anything defined outside Miniflare.
    				async CUSTOM(request) {
    					// `request` is the incoming `Request` object.
    					return new Response(message);
    				},
    			},
    			modules: true,
    			script: `export default {
            async fetch(request, env, ctx) {
              // Get the message defined outside
              const response = await env.CUSTOM.fetch("http://host/");
              const message = await response.text();
    
              // Increment the count 3 times
              await env.INCREMENTER.fetch("http://host/");
              await env.INCREMENTER.fetch("http://host/");
              await env.INCREMENTER.fetch("http://host/");
              const count = await env.COUNTS.get("count");
    
              return new Response(message + count);
            }
          }`,
    		},
    		{
    			name: "incrementer",
    			// Note we're using the same `COUNTS` namespace as before, but binding it
    			// to `NUMBERS` instead.
    			kvNamespaces: { NUMBERS: "counts" },
    			// Worker formats can be mixed-and-matched
    			script: `addEventListener("fetch", (event) => {
            event.respondWith(handleRequest());
          })
          async function handleRequest() {
            const count = parseInt((await NUMBERS.get("count")) ?? "0") + 1;
            await NUMBERS.put("count", count.toString());
            return new Response(count.toString());
          }`,
    		},
    	],
    });
    const res = await mf.dispatchFetch("http://localhost");
    console.log(await res.text()); // "The count is 3"
    await mf.dispose();

• metaProvider

  • 可以在调用 dispatchFetch() 时指定 cf 对象和 X-Forwarded-Proto/X-Real-IP 标头。 也可以使用新的 cf 选项指定默认 cf 对象。

• durableObjectAlarms

  • Miniflare 现在始终启用 Durable Object alarms。

• globalAsyncIO/globalTimers/globalRandom

  • workerd ↗ 无法在不进行根本性变更的情况下 支持这些选项。

• actualTime

  • Miniflare 现在始终返回当前时间。

• inaccurateCpu

  • 设置 inspectorPort: 9229 选项以启用 V8 inspector。在 Google Chrome 中访问 chrome://inspect 打开 DevTools 并进行 CPU 性能分析。

• setOptions()
  • Miniflare v3 现在需要传入完整的配置对象， 而不是部分补丁。

• reload()
  • 使用原始配置对象调用 setOptions() 以重载 Miniflare。
• createServer()/startServer()
  • Miniflare 现在始终启动在配置的 host 和 port 上监听的 workerd ↗ 服务器，因此这些方法已冗余。
• dispatchScheduled()/startScheduled()
  • dispatchScheduled 的功能现在可以通过 getWorker() 实现。更多信息请参阅 scheduled 事件文档。
• dispatchQueue()
  • 请改用 service bindings 或 queue producer bindings 上的 queue() 方法。
• getGlobalScope()/getBindings()/getModuleExports()
  • 这些方法返回 Workers 沙箱内部的对象。由于 Miniflare 现在使用 workerd ↗，它在 不同进程中运行，因此不再支持这些方法。
• addEventListener()/removeEventListener()
  • Miniflare 不再发出 reload 事件。由于 Miniflare 不再监听 文件，重载仅由初始化或 setOptions() 调用触发。 在这些情况下，可以使用 await mf.ready 或 await mf.setOptions() 等待重载完成。
• Response#waitUntil()
  • workerd ↗ 尚不支持等待 所有 waitUntil() 的 promise。

• @miniflare/*
  • Miniflare 现在包含在单个 miniflare 包中。