配置 - Wrangler v1（已弃用） · Cloudflare Workers docs

背景

你的项目在发布 Worker 之前需要一些配置。配置通过修改 Wrangler 文件根目录中存储的键和值来完成。你必须手动编辑此文件以编辑键和值，然后才能发布。

环境

顶层配置是你在 Wrangler 文件顶部指定的值集合。这些值将被所有环境继承，除非在环境中另有定义。

Wrangler 文件中顶层配置的布局如下所示：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "your-worker",
	"type": "javascript",
	"account_id": "your-account-id",
	// This field specifies that the Worker
	// will be deployed to a *.workers.dev domain
	"workers_dev": true,
	// -- OR --
	// These fields specify that the Worker
	// will deploy to a custom domain
	"zone_id": "your-zone-id",
	"routes": [
		"example.com/*"
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "your-worker"
type = "javascript"
account_id = "your-account-id"
workers_dev = true
zone_id = "your-zone-id"
routes = [ "example.com/*" ]

环境配置（可选）：Wrangler 文件中 [env.name] 下指定的配置值。

环境允许你将同一项目部署到多个位置并使用多个名称。这些环境与 --env 或 -e 标志一起用于部署线上 Worker 的命令：

build
dev
preview
publish
secret

一些环境属性可以从顶层配置继承，但如果在环境中定义了新值，它们将始终覆盖顶层值。

[env.name] 配置示例如下：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"type": "javascript",
	"name": "your-worker",
	"account_id": "your-account-id",
	"vars": {
		"FOO": "default FOO value",
		"BAR": "default BAR value"
	},
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "1a...",
			"preview_id": "1b..."
		}
	],
	"env": {
		"helloworld": {
			// Now adding configuration keys for the "helloworld" environment.
			// These new values will override the top-level configuration.
			"name": "your-worker-helloworld",
			"account_id": "your-other-account-id",
			"vars": {
				"FOO": "env-helloworld FOO value",
				"BAR": "env-helloworld BAR value"
			},
			"kv_namespaces": [
				{
					// Redeclare kv namespace bindings for each environment
					// NOTE: In this case, passing new IDs because new `account_id` value.
					"binding": "FOO",
					"id": "888...",
					"preview_id": "999..."
				}
			]
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
type = "javascript"
name = "your-worker"
account_id = "your-account-id"

[vars]
FOO = "default FOO value"
BAR = "default BAR value"

[[kv_namespaces]]
binding = "FOO"
id = "1a..."
preview_id = "1b..."

[env.helloworld]
name = "your-worker-helloworld"
account_id = "your-other-account-id"

  [env.helloworld.vars]
  FOO = "env-helloworld FOO value"
  BAR = "env-helloworld BAR value"

  [[env.helloworld.kv_namespaces]]
  binding = "FOO"
  id = "888..."
  preview_id = "999..."

要将此示例 Worker 部署到 helloworld 环境，运行 wrangler deploy --env helloworld。

键

Wrangler 文件中有三种类型的键：

仅顶层键必须在 Wrangler 文件顶层配置；同一项目的多个环境必须共享此键的值。
可继承键可以在顶层和/或环境中配置。如果键仅在顶层定义，环境将使用顶层的键值。如果在环境中定义了键，环境值将覆盖顶层值。
不可继承键必须为每个环境单独定义。
name 可继承必填
- Worker 脚本名称。如果继承，环境名称将附加到顶层名称。
type 仅顶层必填
- 指定 wrangler build 如何构建项目。有三个选项：javascript、webpack 和 rust。javascript 检查 [build] 部分中指定的构建命令，webpack 使用 webpack v4 构建项目，rust 将项目中的 Rust 编译为 WebAssembly。

account_id 可继承必填
- 这是与你的 zone 关联的账户 ID。你可能有多个账户，因此如果提供了 zone_id，请确保使用与提供的 zone/route 关联的账户 ID。也可以通过 CF_ACCOUNT_ID 环境变量指定。
zone_id 可继承可选
- 这是你要运行 Worker 的 zone 或域的 ID。也可以通过 CF_ZONE_ID 环境变量指定。如果只使用 *.workers.dev 子域，此键是可选的。
workers_dev 可继承可选
- 这是一个布尔标志，指定 Worker 是否部署到你的 *.workers.dev ↗ 子域。如果省略，默认为 false。
route 不可继承可选
- 在 zone 上运行 Worker 的路由，由 URL 模式指定。
  route = "http://example.com/*"。如果不使用 *.workers.dev ↗ 子域，则只需要 route 或 routes 键。
routes 不可继承可选
- 要在其上使用 Worker 的路由列表。这些规则与 route 完全相同，但可以指定列表。
  routes = ["http://example.com/hello", "http://example.com/goodbye"]。如果不使用 *.workers.dev 子域，则只需要 route 或 routes 键。
webpack_config 可继承可选
- 这是 Worker 的自定义 webpack 配置文件的路径。必须使用此字段才能使用自定义 webpack 配置，否则 Wrangler 将使用默认配置。有关更多信息，请参阅 Wrangler webpack 页面。
vars 不可继承可选
- 包含 Worker 脚本可直接访问的文本变量的对象。
kv_namespaces 不可继承可选
- 这些指定 Worker 内部要访问的任何 Workers KV Namespace。
site 可继承可选
- 确定要从 Worker 上传和提供的本地文件夹。
dev 不可继承可选
- 用于 wrangler dev 的参数，配置本地服务器。
triggers 可继承可选
- 配置 cron 触发器，按计划运行 Worker。
usage_model 可继承可选
- 指定 Worker 的使用模型。有两个选项 - bundled 和 unbound。对于新创建的 Workers，如果省略使用模型，将设置为账户上设置的默认使用模型 ↗。对于现有 Workers，如果省略使用模型，将设置为仪表板中为该 Worker 配置的使用模型。
build 仅顶层可选
- 配置 Wrangler 在构建 Worker 时运行的自定义构建步骤。有关更多详情，请参阅自定义构建文档。

vars

vars 键定义提供给 Worker 脚本的环境变量表。所有值都是明文值。

用法：

{
	"vars": {
		"FOO": "some value",
		"BAR": "some other string"
	}
}

[vars]
FOO = "some value"
BAR = "some other string"

表键作为全局变量提供给 Worker，将包含其关联值。

// Worker code:
console.log(FOO);
//=> "some value"

console.log(BAR);
//=> "some other string"

或者，你可以使用内联表格式定义 vars。此样式不应包含任何新行，才能被视为有效的 TOML 配置：

{
	"vars": {
		"FOO": "some value",
		"BAR": "some other string"
	}
}

[vars]
FOO = "some value"
BAR = "some other string"

kv_namespaces

kv_namespaces 定义 Worker 的 KV namespace 绑定列表。

用法：

{
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "0f2ac74b498b48028cb68387c421e279",
			"preview_id": "6a1ddb03f3ec250963f0a1e46820076f"
		},
		{
			"binding": "BAR",
			"id": "068c101e168d03c65bddf4ba75150fb0",
			"preview_id": "fb69528dbc7336525313f2e8c3b17db0"
		}
	]
}

[[kv_namespaces]]
binding = "FOO"
id = "0f2ac74b498b48028cb68387c421e279"
preview_id = "6a1ddb03f3ec250963f0a1e46820076f"

[[kv_namespaces]]
binding = "BAR"
id = "068c101e168d03c65bddf4ba75150fb0"
preview_id = "fb69528dbc7336525313f2e8c3b17db0"

或者，你可以这样定义 kv namespaces：

{
	"kv_namespaces": [
		{
			"binding": "FOO",
			"preview_id": "abc456",
			"id": "abc123"
		},
		{
			"binding": "BAR",
			"preview_id": "xyz456",
			"id": "xyz123"
		}
	]
}

[[kv_namespaces]]
binding = "FOO"
preview_id = "abc456"
id = "abc123"

[[kv_namespaces]]
binding = "BAR"
preview_id = "xyz456"
id = "xyz123"

与环境变量和密钥类似，绑定（binding）名称作为全局变量提供给 Worker。

// Worker script:

let value = await FOO.get("keyname");
//=> gets the value for "keyname" from
//=> the FOO variable, which points to
//=> the "0f2ac...e279" KV namespace

binding 必填
- 代码将引用的全局变量名称。它将作为 KV 运行时实例提供。
id 必填
- 绑定应代表的 KV namespace 的 ID。wrangler publish 需要。
preview_id 必填
- 在 wrangler dev 或 wrangler preview 期间绑定应代表的 KV namespace 的 ID。wrangler dev 和 wrangler preview 需要。

site

使用 wrangler generate --site 或 wrangler init --site 生成的 Workers Site。

用法：

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site"
	}
}

[site]
bucket = "./public"
entry-point = "workers-site"

bucket 必填
- 包含静态资源的目录。必须是相对于 Wrangler 文件的路径。示例：bucket = "./public"
entry-point 可选
- Worker 脚本的位置。默认位置是 workers-site。示例：entry-point = "./workers-site"
include 可选
- 匹配 bucket 位置中文件或目录名称的 .gitignore 风格模式的独占列表。仅上传匹配项。示例：include = ["upload_dir"]
exclude 可选
- 匹配 bucket 中应排除上传的文件或目录的 .gitignore 风格模式列表。示例：exclude = ["ignore_dir"]

你还可以使用替代 TOML 语法 ↗定义 site。

存储限制

对于异常大的页面，Workers Sites 可能不是理想选择。每个页面或文件有 25 MiB 限制。此外，Wrangler 将为文件创建资源清单，计入脚本的 size 限制。如果文件太多，可能无法使用 Workers Sites。

仅包含文件/目录

如果只想在 bucket 中包含特定文件或目录集，在 Wrangler 文件的 [site] 部分添加 include 字段：

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site",
		"include": [ // must be an array.
			"included_dir"
		]
	}
}

[site]
bucket = "./public"
entry-point = "workers-site"
include = [ "included_dir" ]

Wrangler 将仅上传匹配 include 数组中模式的文件或目录。

排除文件/目录

如果要排除 bucket 中的文件或目录，在 Wrangler 文件的 [site] 部分添加 exclude 字段：

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site",
		"exclude": [ // must be an array.
			"excluded_dir"
		]
	}
}

[site]
bucket = "./public"
entry-point = "workers-site"
exclude = [ "excluded_dir" ]

Wrangler 在上传资源到 Workers KV 时将忽略匹配 exclude 数组中模式的文件或目录。

Include > Exclude

如果同时提供 include 和 exclude 字段，将使用 include 字段，exclude 字段将被忽略。

默认忽略项

Wrangler 将始终忽略：

node_modules
隐藏文件和目录
符号链接

关于 include/exclude 模式的更多信息

请参阅 gitignore 文档 ↗了解更多标准匹配模式。

自定义 Sites 构建

Workers Sites 项目默认使用 webpack。虽然你可以自带 webpack 配置，但请注意 entry 和 context 设置。

你还可以将 [build] 部分与 Workers Sites 一起使用，只要构建步骤会解析 node_modules 中的依赖项。有关更多信息，请参阅自定义构建部分。

triggers

用于按计划调用 Worker 的一组 cron 触发器。

用法：

{
	"triggers": {
		"crons": [
			"0 0 * JAN-JUN FRI",
			"0 0 LW JUL-DEC *"
		]
	}
}

[triggers]
crons = [ "0 0 * JAN-JUN FRI", "0 0 LW JUL-DEC *" ]

crons 可选
- 一组 cron 表达式 ↗，每个表达式是运行 Worker 的单独计划。

dev

wrangler dev 的参数可以在此配置，这样你就不必重复传递它们。

用法：

{
	"dev": {
		"port": 9000,
		"local_protocol": "https"
	}
}

[dev]
port = 9_000
local_protocol = "https"

ip 可选
- 本地 wrangler dev 服务器监听的 IP 地址，默认为 127.0.0.1。
port 可选
- 本地 wrangler dev 服务器监听的端口，默认为 8787。
local_protocol 可选
- 本地 wrangler dev 服务器监听请求的协议，默认为 http。
upstream_protocol 可选
- wrangler dev 转发请求的协议，默认为 https。

build

项目的自定义构建命令。根据 Worker 格式有两种配置：service-worker 和 modules。

Service Workers

此部分用于自定义 service-worker 格式的 Workers。这些 Worker 使用 addEventListener，如下所示：

addEventListener("fetch", (event) => {
	event.respondWith(new Response("I'm a service Worker!"));
});

用法：

{
	"build": {
		"command": "npm install && npm run build",
		"upload": {
			"format": "service-worker"
		}
	}
}

[build]
command = "npm install && npm run build"

  [build.upload]
  format = "service-worker"

`[build]`

command 可选
- 用于构建 Worker 的命令。在 Linux 和 macOS 上，命令在 sh shell 中执行，Windows 上在 cmd shell 中执行。可以使用 && 和 || shell 运算符。
cwd 可选
- 命令的工作目录，默认为项目根目录。
watch_dir 可选
- 使用 wrangler dev 时监视更改的目录，默认为相对于项目根目录的 src。

`[build.upload]`

format 必填
- Worker 脚本的格式，必须为 "service-worker"。

Modules

Workers 现在支持 ES Modules 语法。此格式允许你导出文件和/或模块集合，与需要上传单个文件的 Service Worker 格式不同。

Module Workers export 其事件处理程序，而不是使用 addEventListener 调用。

Modules 将所有绑定（KV Namespaces、环境变量和 Secrets）作为导出处理程序的参数接收。使用 Service Worker 格式时，这些绑定作为全局变量可用。

上传的模块可以 import 其他上传的 ES Modules。如果使用 CommonJS 格式，可以 require 其他上传的 CommonJS 模块。

import html from "./index.html";

export default {
	// * request is the same as `event.request` from the service worker format
	// * waitUntil() and passThroughOnException() are accessible from `ctx` instead of `event` from the service worker format
	// * env is where bindings like KV namespaces, Durable Object namespaces, Config variables, and Secrets
	// are exposed, instead of them being placed in global scope.
	async fetch(request, env, ctx) {
		const headers = { "Content-Type": "text/html;charset=UTF-8" };
		return new Response(html, { headers });
	},
};

要使用 Wrangler 和 Modules 创建 Workers 项目，添加 [build] 部分：

{
	"build": {
		"command": "npm install && npm run build",
		"upload": {
			"format": "modules",
			"main": "./worker.mjs"
		}
	}
}

[build]
command = "npm install && npm run build"

  [build.upload]
  format = "modules"
  main = "./worker.mjs"

`[build]`

command 可选
- 用于构建 Worker 的命令。在 Linux 和 macOS 系统上，命令在 sh shell 中执行，Windows 上在 cmd shell 中执行。可以使用 && 和 || shell 运算符。
cwd 可选
- 命令的工作目录，默认为项目根目录。
watch_dir 可选
- 使用 wrangler dev 时监视更改的目录，默认为相对于项目根目录的 src。

`[build.upload]`

format 必填
- Workers 脚本的格式，必须为 "modules"。
dir 可选
- 要从中上传模块的目录，默认为相对于项目根目录的 dist。
main 必填
- 从 dir 开始的主模块相对路径，包括 ./ 前缀。主模块必须是 ES 模块。对于有构建脚本的项目，这通常指 JavaScript bundler 的输出。

rules 可选
- 定义要导入哪些模块以及导入类型的有序规则列表。你需要指定规则才能使用 Text、Data 和 CompiledWasm 模块，或者当你希望 .js 文件被视为 ESModule 而不是 CommonJS 时。

默认值：

{
	// You do not need to include these default rules in your [Wrangler configuration file](/workers/wrangler/configuration/), they are implicit.
	// The default rules are treated as the last two rules in the list.
	"build": {
		"upload": {
			"format": "modules",
			"main": "./worker.mjs",
			"rules": [
				{
					"type": "ESModule",
					"globs": [
						"**/*.mjs"
					]
				},
				{
					"type": "CommonJS",
					"globs": [
						"**/*.js",
						"**/*.cjs"
					]
				}
			]
		}
	}
}

[build.upload]
format = "modules"
main = "./worker.mjs"

  [[build.upload.rules]]
  type = "ESModule"
  globs = [ "**/*.mjs" ]

  [[build.upload.rules]]
  type = "CommonJS"
  globs = [ "**/*.js", "**/*.cjs" ]

type 必填
- 模块类型，请参阅下表了解可接受的选项：
globs 必填
- UNIX 风格的 glob 规则 ↗，用于确定 dir 中给定文件使用的模块类型。Glob 与模块从 build.upload.dir 开始的相对路径匹配，不带 ./ 前缀。规则按顺序从上到下评估。
fallthrough 可选
- 如果设置为 true，此选项允许进一步考虑此模块类型的规则。如果未指定或设置为 false，将忽略此模块类型的进一步规则。

示例

为了说明这些级别如何应用，以下是使用多个环境的 Wrangler 文件：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	// top level configuration
	"type": "javascript",
	"name": "my-worker-dev",
	"account_id": "12345678901234567890",
	"zone_id": "09876543210987654321",
	"route": "dev.example.com/*",
	"usage_model": "unbound",
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "b941aabb520e61dcaaeaa64b4d8f8358",
			"preview_id": "03c8c8dd3b032b0528f6547d0e1a83f3"
		},
		{
			"binding": "BAR",
			"id": "90e6f6abd5b4f981c748c532844461ae",
			"preview_id": "e5011a026c5032c09af62c55ecc3f438"
		}
	],
	"build": {
		"command": "webpack",
		"upload": {
			"format": "service-worker"
		}
	},
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site"
	},
	"dev": {
		"ip": "0.0.0.0",
		"port": 9000,
		"local_protocol": "http",
		"upstream_protocol": "https"
	},
	"env": {
		// environment configuration
		"staging": {
			"name": "my-worker-staging",
			"route": "staging.example.com/*",
			"kv_namespaces": [
				{
					"binding": "FOO",
					"id": "0f2ac74b498b48028cb68387c421e279"
				},
				{
					"binding": "BAR",
					"id": "068c101e168d03c65bddf4ba75150fb0"
				}
			]
		},
		// environment configuration
		"production": {
			"workers_dev": true,
			"kv_namespaces": [
				{
					"binding": "FOO",
					"id": "0d2ac74b498b48028cb68387c421e233"
				},
				{
					"binding": "BAR",
					"id": "0d8c101e168d03c65bddf4ba75150f33"
				}
			]
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
type = "javascript"
name = "my-worker-dev"
account_id = "12345678901234567890"
zone_id = "09876543210987654321"
route = "dev.example.com/*"
usage_model = "unbound"

[[kv_namespaces]]
binding = "FOO"
id = "b941aabb520e61dcaaeaa64b4d8f8358"
preview_id = "03c8c8dd3b032b0528f6547d0e1a83f3"

[[kv_namespaces]]
binding = "BAR"
id = "90e6f6abd5b4f981c748c532844461ae"
preview_id = "e5011a026c5032c09af62c55ecc3f438"

[build]
command = "webpack"

  [build.upload]
  format = "service-worker"

[site]
bucket = "./public"
entry-point = "workers-site"

[dev]
ip = "0.0.0.0"
port = 9_000
local_protocol = "http"
upstream_protocol = "https"

[env.staging]
name = "my-worker-staging"
route = "staging.example.com/*"

  [[env.staging.kv_namespaces]]
  binding = "FOO"
  id = "0f2ac74b498b48028cb68387c421e279"

  [[env.staging.kv_namespaces]]
  binding = "BAR"
  id = "068c101e168d03c65bddf4ba75150fb0"

[env.production]
workers_dev = true

  [[env.production.kv_namespaces]]
  binding = "FOO"
  id = "0d2ac74b498b48028cb68387c421e233"

  [[env.production.kv_namespaces]]
  binding = "BAR"
  id = "0d8c101e168d03c65bddf4ba75150f33"