跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

API

最后更新 查看 MarkdownAgent 设置

Wrangler 提供 API,用于以编程方式与 Cloudflare Workers 交互。

  • createTestHarness - 在任意 Node.js 测试运行器中启动一个或多个 Worker,用于集成测试。
  • experimental_generateTypes - 根据 Worker 配置生成 TypeScript 类型定义。
  • unstable_startWorker - 启动服务器,用于针对 Worker 运行集成测试。
  • unstable_dev - 启动服务器,用于针对 Worker 运行端到端(e2e)或集成测试。
  • getPlatformProxy - 获取代理和值,用于在 Node.js 进程中模拟 Cloudflare Workers 平台。

createTestHarness

createTestHarness() 可从任意 Node.js 测试运行器启动一个或多个 Worker 进行集成测试。它运行来自 Wrangler 配置文件、Vite 生成的配置文件或内联 Wrangler 配置对象的生产构建输出。该 API 封装 Miniflare,并提供用于分发请求和 scheduled 事件的方法。

设置指南和示例请参阅集成测试 harness。

语法

import { createTestHarness } from "wrangler";

const server = createTestHarness(options);
import { createTestHarness } from "wrangler";

const server = createTestHarness(options);

参数

  • options objectoptional

    • 测试 harness 选项。如果调用 createTestHarness() 时不传选项,请在 server.listen() 之前调用 server.update(options)。

      • root stringoptional

        用于解析相对 Worker 配置路径的基目录。默认为 process.cwd()。

      • workers WorkerInput[]

        要在测试服务器中运行的 Worker。第一个 Worker 是主 Worker。

每个 WorkerInput 都可以从 Wrangler 配置文件加载 Worker:

const server = createTestHarness({
	workers: [
		{ configPath: "./wrangler.web.jsonc" },
		{ configPath: "./wrangler.api.jsonc" },
	],
});
const server = createTestHarness({
	workers: [
		{ configPath: "./wrangler.web.jsonc" },
		{ configPath: "./wrangler.api.jsonc" },
	],
});

配置文件输入支持这些字段:

  • configPath string | URL
    • Wrangler 配置文件路径。相对路径从 root 解析。
  • env stringoptional
    • 要从配置文件加载的 Wrangler 环境。
  • vars Record<string, Json>optional
    • 仅用于测试的变量,会覆盖 Wrangler 配置文件中的变量。
  • secrets Record<string, string>optional
    • 仅用于测试的密钥,会覆盖从 .dev.vars 和 .env 文件加载的值。
  • bindingOverrides Record<string, string>optional
    • 仅用于测试的 service binding 覆盖。键是此 Worker 环境中的绑定名称。值是此测试 harness 中的 Worker 名称。

每个 WorkerInput 也可以使用 config 提供内联 Wrangler 配置对象:

const server = createTestHarness({
	workers: [
		{
			config: {
				name: "api-worker",
				main: "src/api.ts",
				compatibility_date: "YYYY-MM-DD",
			},
		},
	],
});
const server = createTestHarness({
	workers: [
		{
			config: {
				name: "api-worker",
				main: "src/api.ts",
				compatibility_date: "YYYY-MM-DD",
			},
		},
	],
});

返回类型

createTestHarness() 返回带有以下方法的 TestHarness 对象:

  • listen() Promise<{ url: URL }>
    • 启动服务器并返回其当前 URL。重复调用会返回同一会话,直到服务器关闭或重置。
  • fetch(input, init) Promise<Response>
    • 通过服务器分发 fetch 请求。相对 URL 相对于当前服务器 URL 解析。绝对 URL 遵循配置的 Worker 路由,并回退到主 Worker。
  • getWorker(name?) WorkerHandle
    • 返回用于直接向 Worker 分发事件的句柄。未提供名称时,返回主 Worker。
  • getLogs() WorkerdStructuredLog[]
    • 返回当前服务器会话启动或上次调用 clearLogs() 以来捕获的 Workers 运行时日志。
  • clearLogs() void
    • 清除已捕获的 Workers 运行时日志。
  • debug() void
    • 打印此测试服务器的诊断时间线,包括服务器事件和捕获的 Workers 运行时日志。适合在测试运行器的失败或清理钩子中使用。
  • update(optionsOrUpdater) Promise<void>
    • 使用 TestHarnessOptions 对象或接收当前选项并返回下一组选项的函数更新服务器配置。如果服务器尚未启动,这将配置 listen() 使用的选项。如果服务器正在运行,这将重新加载正在运行的 Worker。不支持在运行中的服务器上更新 Worker 数量。
  • reset() Promise<void>
    • 将服务器恢复到当前会话首次启动时使用的选项。存储会被重建,重置后服务器 URL 可能变化。
  • close() Promise<void>
    • 停止服务器并释放所有运行时资源。

getWorker(name?) 返回带有以下方法的 WorkerHandle 对象:

  • fetch(input, init) Promise<Response>
    • 直接向此 Worker 分发 fetch 事件。
  • scheduled(options) Promise<{ outcome: "ok" | "canceled" | "exception"; noRetry: boolean }>
    • 直接向此 Worker 分发 scheduled 事件。
  • getEnv() Promise<Env>
    • 返回为此 Worker 配置的完整环境对象,包括变量、密钥和绑定。
  • getExport() Promise<Service<Module['default']>>
    • 返回默认 Worker 导出,包括 RPC 方法。
  • applyD1Migrations(bindingName) Promise<void>
    • 将尚未运行的本地 D1 迁移文件应用到此 Worker 上的 D1 绑定。
  • getDurableObjectStorage(classNameOrBindingName, options) Promise<DurableObjectStorageHandle>
    • 返回 Durable Object 实例的 SQL 存储访问。
  • introspectWorkflow(bindingName) Promise<WorkflowIntrospector>
    • 为此方法调用之后创建的 Workflow 实例创建内省器。
  • introspectWorkflowInstance(bindingName, instanceId) Promise<WorkflowInstanceIntrospector>
    • 为特定 Workflow 实例创建内省器。

用法

此示例使用 Node.js 内置测试运行器:

import assert from "node:assert/strict";
import { after, afterEach, before, describe, test } from "node:test";
import { createTestHarness } from "wrangler";

const server = createTestHarness({
	workers: [
		{ configPath: "./wrangler.web.jsonc" },
		{ configPath: "./wrangler.api.jsonc" },
	],
});

const apiWorker = server.getWorker("api-worker");

describe("Worker", () => {
	before(async () => {
		await server.listen();
	});

	afterEach(async () => {
		await server.reset();
	});

	after(async () => {
		await server.close();
	});

	test("dispatches through configured routes", async () => {
		const response = await server.fetch("http://example.com/users/123");
		assert.equal(response.status, 200);
	});

	test("calls a specific Worker directly", async () => {
		const response = await apiWorker.fetch(
			"http://api.example.com/v1/users/123",
		);
		assert.equal(response.status, 200);
	});

	test("triggers a scheduled handler", async () => {
		const result = await apiWorker.scheduled({
			cron: "0 0 * * *",
			scheduledTime: new Date(),
		});
		assert.equal(result.outcome, "ok");
	});
});
import assert from "node:assert/strict";
import { after, afterEach, before, describe, test } from "node:test";
import { createTestHarness } from "wrangler";

const server = createTestHarness({
	workers: [
		{ configPath: "./wrangler.web.jsonc" },
		{ configPath: "./wrangler.api.jsonc" },
	],
});

const apiWorker = server.getWorker("api-worker");

describe("Worker", () => {
	before(async () => {
		await server.listen();
	});

	afterEach(async () => {
		await server.reset();
	});

	after(async () => {
		await server.close();
	});

	test("dispatches through configured routes", async () => {
		const response = await server.fetch("http://example.com/users/123");
		assert.equal(response.status, 200);
	});

	test("calls a specific Worker directly", async () => {
		const response = await apiWorker.fetch(
			"http://api.example.com/v1/users/123",
		);
		assert.equal(response.status, 200);
	});

	test("triggers a scheduled handler", async () => {
		const result = await apiWorker.scheduled({
			cron: "0 0 * * *",
			scheduledTime: new Date(),
		});
		assert.equal(result.outcome, "ok");
	});
});

experimental_generateTypes

根据 Worker 配置生成 TypeScript 类型定义。此 API 使用与 wrangler types CLI 命令相同的核心逻辑,因此 CLI 与程序化 API 的输出保持一致。

与 CLI 命令不同,experimental_generateTypes 不会自动写入磁盘。相反,它将生成的类型内容作为结构化字符串返回,供你按需处理。

语法

import { experimental_generateTypes } from "wrangler";

const result = await experimental_generateTypes(options);

参数

  • options objectoptional

    • 可选的 options 对象,镜像 wrangler types CLI 标志:

      • config string | string[]

        要使用的 Wrangler 配置文件路径。可以是数组,用于多配置类型解析。

      • env string

        要为其生成类型的 Wrangler 环境名称。

      • envFile string[]

        推断本地变量和密钥时加载的 .env 文件路径。

      • envInterface string

        生成的环境接口名称。默认为 Env。

      • includeEnv boolean

        是否在输出中包含环境和绑定(binding)类型。默认为 true。

      • includeRuntime boolean

        是否在输出中包含运行时类型。默认为 true。

      • path string

        生成的类型声明文件路径。默认为 worker-configuration.d.ts。

      • strictVars boolean

        是否为变量生成严格的字面量和联合类型。默认为 true。

返回类型

experimental_generateTypes() 返回一个 Promise,解析为包含以下字段的对象:

  • content string

    • 组合后的格式化输出,包含所有生成的部分,包括头部以及环境和运行时类型。
  • env string | null

    • 生成的环境和绑定类型,或在排除环境类型时为 null。
  • path string

    • 与此生成运行关联的目标声明文件路径。
  • runtime string | null

    • 生成的运行时类型,或在排除运行时类型时为 null。

用法

你可以使用 experimental_generateTypes 以编程方式生成类型并自行写入磁盘,或将其传递给其他工具:

import { experimental_generateTypes } from "wrangler";
import * as fs from "node:fs";

const result = await experimental_generateTypes({
	config: "wrangler.json",
	includeRuntime: true,
	includeEnv: true,
});

// Write the combined content to the path specified in options
fs.writeFileSync(result.path, result.content, "utf-8");

仅生成环境类型而不生成运行时类型:

const result = await experimental_generateTypes({
	includeRuntime: false,
});

为特定环境生成类型并使用自定义接口名称:

const result = await experimental_generateTypes({
	env: "staging",
	envInterface: "StagingEnv",
	path: "./types/staging.d.ts",
});

unstable_startWorker

此 API 暴露 Wrangler 开发服务器的内部机制,允许你自定义其运行方式。例如,你可以使用 unstable_startWorker() 针对 Worker 运行集成测试。此示例使用 node:test,但应适用于任何测试框架:

import assert from "node:assert";
import test, { after, before, describe } from "node:test";
import { unstable_startWorker } from "wrangler";

describe("worker", () => {
	let worker;

	before(async () => {
		worker = await unstable_startWorker({ config: "wrangler.json" });
	});

	test("hello world", async () => {
		assert.strictEqual(
			await (await worker.fetch("http://example.com")).text(),
			"Hello world",
		);
	});

	after(async () => {
		await worker.dispose();
	});
});

unstable_dev

启动 HTTP 服务器以测试 Worker。

调用后,unstable_dev 将返回一个 fetch() 函数,用于调用 Worker 而无需知道地址或端口,以及一个 stop() 函数用于关闭 HTTP 服务器。

默认情况下,unstable_dev 针对本地服务器执行集成测试。如果你希望对预览 Worker 执行 e2e 测试,在调用 unstable_dev() 函数时在 options 对象中传入 local: false。请注意,e2e 测试可能比集成测试慢得多。

构造函数

const worker = await unstable_dev(script, options);

参数

  • script string

    • 包含 Worker 脚本路径的字符串,相对于 Worker 项目根目录。
  • options objectoptional

    • 可选的 options 对象,包含 wrangler dev 配置设置。
    • 在 options 内包含 experimental 对象以访问实验性功能,例如 disableExperimentalWarning。
      • 将 disableExperimentalWarning 设置为 true 以禁用 Wrangler 关于使用 unstable_ 前缀 API 的警告。

返回类型

unstable_dev() 返回包含以下方法的对象:

  • fetch() Promise<Response>

    • 向 Worker 发送请求。返回解析为 Response 对象的 Promise。
    • 请参阅 Fetch。
  • stop() Promise<void>

    • 关闭开发服务器。

用法

启动每个测试套件时,使用 beforeAll() 函数启动 unstable_dev()。beforeAll() 函数用于最小化开销:启动开发服务器需要几百毫秒,为每个单独测试启动和停止会迅速累积,拖慢测试速度。

在每个测试用例中,调用 await worker.fetch(),并检查响应是否符合预期。

要完成测试套件,在 afterAll 函数中调用 await worker.stop()。

单 Worker 示例

const { unstable_dev } = require("wrangler");

describe("Worker", () => {
	let worker;

	beforeAll(async () => {
		worker = await unstable_dev("src/index.js", {
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await worker.stop();
	});

	it("should return Hello World", async () => {
		const resp = await worker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});
});
import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";

describe("Worker", () => {
	let worker: UnstableDevWorker;

	beforeAll(async () => {
		worker = await unstable_dev("src/index.ts", {
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await worker.stop();
	});

	it("should return Hello World", async () => {
		const resp = await worker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});
});

多 Worker 示例

你可以测试调用其他 Worker 的 Worker。在以下示例中,我们将调用其他 Worker 的 Worker 称为父 Worker,被调用的 Worker 称为子 Worker。

如果过早关闭子 Worker,父 Worker 将不知道子 Worker 存在,测试将失败。

import { unstable_dev } from "wrangler";

describe("multi-worker testing", () => {
	let childWorker;
	let parentWorker;

	beforeAll(async () => {
		childWorker = await unstable_dev("src/child-worker.js", {
			config: "src/child-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
		parentWorker = await unstable_dev("src/parent-worker.js", {
			config: "src/parent-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await childWorker.stop();
		await parentWorker.stop();
	});

	it("childWorker should return Hello World itself", async () => {
		const resp = await childWorker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});

	it("parentWorker should return Hello World by invoking the child worker", async () => {
		const resp = await parentWorker.fetch();
		const parsedResp = await resp.text();
		expect(parsedResp).toEqual("Parent worker sees: Hello World!");
	});
});
import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";

describe("multi-worker testing", () => {
	let childWorker: UnstableDevWorker;
	let parentWorker: UnstableDevWorker;

	beforeAll(async () => {
		childWorker = await unstable_dev("src/child-worker.js", {
			config: "src/child-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
		parentWorker = await unstable_dev("src/parent-worker.js", {
			config: "src/parent-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await childWorker.stop();
		await parentWorker.stop();
	});

	it("childWorker should return Hello World itself", async () => {
		const resp = await childWorker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});

	it("parentWorker should return Hello World by invoking the child worker", async () => {
		const resp = await parentWorker.fetch();
		const parsedResp = await resp.text();
		expect(parsedResp).toEqual("Parent worker sees: Hello World!");
	});
});

getPlatformProxy

getPlatformProxy 函数提供一种获取代理(指向本地 workerd 绑定)和 Cloudflare Workers 特定值模拟的方法,允许在 Node.js 进程中模拟这些功能。

获取平台代理的一个常见用例是在面向 Workers 但在 Workers 运行时之外运行的应用程序中模拟绑定(binding)(例如,在 Node.js 中运行的框架本地开发服务器),或用于测试目的(例如,确保代码正确与某种类型的绑定交互)。

语法

const platform = await getPlatformProxy(options);

参数

  • options objectoptional
    • 可选的 options 对象,包含绑定偏好:
      • environment string

        要使用的环境。

      • configPath string

        要使用的配置文件路径。

        如果未指定路径,默认行为是从当前目录沿文件系统向上搜索要使用的 Wrangler 配置文件。

        注意: 此字段是可选的,但如果指定了路径,它必须指向文件系统上的有效文件。

      • persist boolean | { path: string }

        指示是否以及在何处持久化绑定数据。如果为 true 或 undefined,默认使用与 Wrangler 相同的位置,以便数据可以在 Wrangler 和调用方之间共享。如果为 false,不会从文件系统读取或写入数据。

        注意: 如果你使用 wrangler 的 --persist-to 选项,请注意此选项在底层会添加名为 v3 的子目录,而 getPlatformProxy 的 persist 不会。例如,如果你运行 wrangler dev --persist-to ./my-directory,要使用 getPlatformProxy 复用相同位置,必须指定:persist: { path: "./my-directory/v3" }。

      • remoteBindings boolean optional (default: `true`)

        是否启用远程绑定。

返回类型

getPlatformProxy() 返回一个 Promise,解析为包含以下字段的对象。

  • env Record<string, unknown>

    • 包含绑定代理的对象,使用方式与生产绑定相同。这与作为 modules 格式 Worker 第二个参数传递的 env 对象的形状匹配。这些代理指向在 workerd 内运行的绑定实现。
    • TypeScript 提示:getPlatformProxy<Env>() 是泛型函数。你可以将绑定记录的形状作为类型参数传递,以获取没有 unknown 值的正确类型。
  • cf IncomingRequestCfProperties read-only

    • Request 的 cf 属性的模拟,包含与生产环境中类似的数据。
  • ctx object

  • caches object

  • dispose() () => Promise<void>

    • 终止底层 workerd 进程。
    • 在程序不再需要平台代理后调用此函数。如果你运行可以无限期使用代理的长运行进程(例如开发服务器),则无需调用此函数。

用法

getPlatformProxy 函数使用 Wrangler 配置文件 中找到的绑定。例如,如果你在 Wrangler 配置文件中设置了环境变量配置:

{
	"vars": {
		"MY_VARIABLE": "test"
	}
}
[vars]
MY_VARIABLE = "test"

你可以通过如下导入 getPlatformProxy 来访问绑定:

import { getPlatformProxy } from "wrangler";

const { env } = await getPlatformProxy();

要访问 MY_VARIABLE 绑定的值,在代码中添加以下内容:

console.log(`MY_VARIABLE = ${env.MY_VARIABLE}`);

这将打印以下输出:MY_VARIABLE = test。

支持的绑定

Wrangler 配置文件 中找到的所有支持绑定都可通过 env 使用。

getPlatformProxy 不会运行 Worker 代码。它会忽略 Wrangler 配置 exports 字段中声明的 Workflows。

getPlatformProxy 支持的绑定包括:

  • 环境变量

  • Service bindings

  • KV namespace bindings

  • R2 bucket bindings

  • Queue bindings

  • D1 database bindings

  • Hyperdrive bindings

  • Workers AI bindings

  • Durable Object bindings

    • 要将 Durable Object 绑定与 getPlatformProxy 一起使用,请始终指定 script_name。

      例如,getPlatformProxy 读取的 Wrangler 配置文件中可能有以下绑定。

      {
        "durable_objects": {
          "bindings": [
            {
              "name": "MyDurableObject",
              "class_name": "MyDurableObject",
              "script_name": "external-do-worker"
            }
          ]
        }
      }
      [[durable_objects.bindings]]
      name = "MyDurableObject"
      class_name = "MyDurableObject"
      script_name = "external-do-worker"

      你需要在另一个 Worker 中声明 Durable Object "MyDurableObject",本示例中称为 external-do-worker。

      ./external-do-worker/src/index.tsts
      export class MyDurableObject extends DurableObject {
      	// Your DO code goes here
      }
      
      export default {
      	fetch() {
      		// Doesn't have to do anything, but a DO cannot be the default export
      		return new Response("Hello, world!");
      	},
      };

      该 Worker 还需要如下所示的 Wrangler 配置文件:

      {
      	"name": "external-do-worker",
      	"main": "src/index.ts",
          "upload_source_maps": true,
      	"compatibility_date": "XXXX-XX-XX"
      }
      name = "external-do-worker"
      main = "src/index.ts"
      upload_source_maps = true
      compatibility_date = "XXXX-XX-XX"

      如果你未将 Durable Object 与 RPC 一起使用,可以在框架开发服务器旁运行单独的 Wrangler dev 会话。

      否则,你可以构建应用程序并在同一 Wrangler dev 会话中运行两个 Worker。

      如果你使用 Pages,运行:

      npx wrangler pages dev -c path/to/pages/wrangler.jsonc -c path/to/external-do-worker/wrangler.jsonc

      如果你使用带 Assets 的 Workers,运行:

      npx wrangler dev -c path/to/workers-assets/wrangler.jsonc -c path/to/external-do-worker/wrangler.jsonc

这篇文档对您有帮助吗?