Cloudflare 中文文档
Workers
Cloudflare 中文文档
Workers
编辑这个页面
跳转官方原文档
Set theme to dark (⇧+D)
  1. Products
  2. Workers
  3. Wrangler
  4. API

Wrangler API

Wrangler 提供 API，以编程方式与 Cloudflare Workers 交互。

  • unstable_dev - 启动服务器，针对 Worker 运行端到端(e2e)测试或集成测试。
  • getPlatformProxy - 在 Node.js 进程中获取用于模拟 Cloudflare Workers 平台的代理和值。

​​ unstable_dev

启动 HTTP 服务器，测试 Worker。

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

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

​​ 构造函数

​​ 参数

  • script string

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

  • options object optional

    • 包含 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()。

​​ 单个Works示例

​​ 多Worker示例

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

如果你过早关闭子 Worker，父 Worker 将不知道子 Worker 的存在，你的测试就会失败。

​​ getPlatformProxy.

getPlatformProxy 函数提供了一种获取对象的方法，该对象包含代理(与本地workerd 绑定)和 Cloudflare Workers 特定值的仿真，允许在 Node.js 进程中进行仿真。

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

​​ 语法

​​ 参数

  • options object optional

    • 包含绑定首选项的可选选项对象：

      • environment string

        使用环境。

      • configPath string

        要使用的配置文件的路径。

        如果未指定路径，默认行为是在文件系统中从当前目录向上搜索要使用的 wrangler.toml。

        **注意：**该字段为可选项，但如果指定了路径，则必须指向文件系统中的有效文件。

      • experimentalJsonConfig boolean

        true，则允许实用程序读取 JSON 配置文件(例如，wrangler.json)。

      • persist boolean | { path: string }

        指示是否持久化绑定数据以及持久化的位置。如果是 true 或 undefined，默认与 Wrangler 使用的位置相同，因此数据可在它和调用者之间共享。如果是 false，则不会将数据持久化到文件系统，也不会从文件系统读取数据。

        **注意：**如果使用 wrangler 的 --persist-to 选项，请注意该选项会在引擎盖下添加一个名为 v3 的子目录，而 getPlatformProxy 的 persist 不会。例如，如果运行 wrangler dev --persist-to ./my-directory，要使用 getPlatformProxy 重用同一位置，则必须指定：persist:"./my-directory/v3"。

​​ 返回类型

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

  • env Record<string, unknown>

    • 包含可与生产绑定以相同方式使用的绑定代理的对象。这与作为模块格式化工作者第二个参数传递的 env 对象的形状相匹配。这些绑定代理实现在 workerd 中运行。
    • Typescript 提示：getPlatformProxy<Env>() 是一个通用函数。你可以将绑定记录的形状作为类型参数传递，以获得不含unknown值的适当类型。

  • cf IncomingRequestCfProperties read-only

    • 模拟 Request 的 cf 属性，包含与生产中类似的数据。

  • ctx object

  • caches object

    • 仿真 Workers caches runtime API。
    • 目前，所有高速缓存操作都不起作用。我们将很快提供更精确的模拟。

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

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

​​ 使用方法

getPlatformProxy 函数使用 wrangler.toml 中的绑定。例如，如果你在wrangler.toml中设置了环境变量配置：

你可以像这样导入 getPlatformProxy 来访问绑定：

要访问 MY_VARIABLE 绑定的值，请在代码中添加以下内容：

这将打印以下输出：MY_VARIABLE = test.

​​ 支持的绑定

你可以通过 env 使用 wrangler.toml 中的所有支持绑定。

getPlatformProxy 支持的绑定包括