配置

Wrangler 可选择使用配置文件来自定义 Worker 的开发和部署设置。

最佳实践是将 Wrangler 配置文件视为配置 Worker 的真实来源。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	// Top-level configuration
	"name": "my-worker",
	"main": "src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"workers_dev": false,
	"route": {
		"pattern": "example.org/*",
		"zone_name": "example.org",
	},
	"kv_namespaces": [
		{
			"binding": "<MY_NAMESPACE>",
			"id": "<KV_ID>",
		},
	],
	"env": {
		"staging": {
			"name": "my-worker-staging",
			"route": {
				"pattern": "staging.example.org/*",
				"zone_name": "example.org",
			},
			"kv_namespaces": [
				{
					"binding": "<MY_NAMESPACE>",
					"id": "<STAGING_KV_ID>",
				},
			],
		},
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-08-17"
workers_dev = false

[route]
pattern = "example.org/*"
zone_name = "example.org"

[[kv_namespaces]]
binding = "<MY_NAMESPACE>"
id = "<KV_ID>"

[env.staging]
name = "my-worker-staging"

  [env.staging.route]
  pattern = "staging.example.org/*"
  zone_name = "example.org"

  [[env.staging.kv_namespaces]]
  binding = "<MY_NAMESPACE>"
  id = "<STAGING_KV_ID>"

你可以使用 Wrangler 环境 为 Worker 定义不同的配置。 有一个默认（顶层）环境，你可以创建提供环境特定配置的命名环境。

这些定义在 [env.<name>] 键下，例如 [env.staging]，然后可以使用 wrangler 命令中的 -e / --env 标志预览或部署，如 npx wrangler deploy --env staging。

大多数键是可继承的，意味着顶层配置可以在环境中使用。绑定（binding）（如 vars 或 kv_namespaces）不可继承，需要显式定义。

此外，有一些键_只能_出现在顶层。

Wrangler 可以在你部署 Worker 时自动为你预配资源，无需提前创建。

目前适用于 KV、R2 和 D1 绑定。

要使用此功能，在配置文件中添加绑定，_不_添加资源 ID，对于 R2 则不添加 bucket 名称。资源将以 Worker 名称作为前缀创建。

{
	"kv_namespaces": [
		{
			"binding": "<MY_KV_NAMESPACE>",
		},
	],
}

[[kv_namespaces]]
binding = "<MY_KV_NAMESPACE>"

运行 wrangler dev 时，将自动创建在运行之间持久化的本地资源。运行 wrangler deploy 时，将为你创建资源，其 ID 将写回配置文件。

如果你从仪表板（例如通过 GitHub）部署带有资源但没有资源 ID 的 Worker，将创建资源，但其 ID 只能通过仪表板访问。目前，这些资源 ID 不会写回你的仓库。

顶层键适用于 Worker 整体（因此适用于所有环境）。不能在命名环境中定义。

• keep_vars booleanoptional

  • Wrangler 是否应在部署时保留在仪表板中配置的变量。请参阅真实来源。

• send_metrics booleanoptional

  • Wrangler 是否应为此项目向 Cloudflare 发送使用数据。默认为 true。你可以在数据政策 ↗中了解更多。

• dependencies_instrumentation objectoptional

  • 在部署或上传 Worker 版本时配置 npm 包依赖项检测。默认启用。
  • enabled boolean — Wrangler 是否应收集并发送 npm 包依赖项元数据（包名称和版本）。默认为 true。

• site objectoptional deprecated

  • 请参阅下面的 Workers Sites 部分了解更多信息。建议使用 Cloudflare Pages 和 Workers Assets 而非此方法。
  • Cloudflare Vite 插件 不支持此功能。

可继承键可在顶层配置，并可以被环境特定配置继承（或覆盖）。

• name stringrequired

  • Worker 的名称。仅允许字母数字字符（a、b、c 等）和短划线（-）。不要使用下划线（_）。Worker 名称最多 255 个字符。如果计划使用 workers.dev 子域，名称必须不超过 63 个字符，且不能以短划线开头或结尾。

• main stringrequired

  • 将执行的 Worker 入口点路径。例如：./src/index.ts。

• compatibility_date stringrequired

  • yyyy-mm-dd 格式的日期，用于确定使用哪个版本的 Workers 运行时。请参阅兼容性日期。

• account_id stringoptional

  • 与你的 zone 关联的账户 ID。你可能有多个账户，因此如果提供了 zone/route，请确保使用与其关联的账户 ID。也可以通过 CLOUDFLARE_ACCOUNT_ID 环境变量指定。

• compatibility_flags string[]optional

  • 启用 Workers 运行时即将推出功能的标志列表，通常与 compatibility_date 一起使用。请参阅兼容性日期。

• workers_dev booleanoptional

  • 启用使用 *.workers.dev 子域部署 Worker。如果 Worker 仅用于 scheduled 事件，可以设置为 false。默认为 true。请参阅路由类型。

• preview_urls booleanoptional

  • 启用 Preview URL 以测试 Worker。默认为 workers_dev 的值。请参阅 Preview URL。

• route Routeoptional

  • Worker 应部署到的路由。只需要 routes 或 route 之一。请参阅路由类型。

• routes Route[]optional

  • Worker 应部署到的路由数组。只需要 routes 或 route 之一。请参阅路由类型。

• tsconfig stringoptional

  • 自定义 tsconfig 的路径。
  • 如果使用 Cloudflare Vite 插件，则不适用。

• triggers objectoptional

  • 触发 Worker scheduled 函数的 Cron 定义。请参阅触发器。

• rules Ruleoptional

  • 定义要导入哪些模块以及导入类型的有序规则列表。需要使用 Text、Data 和 CompiledWasm 模块，或希望 .js 文件被视为 ESModule 而不是 CommonJS 时，需要指定规则。
  • 如果使用 Cloudflare Vite 插件，则不适用。

• build Buildoptional

  • 配置 Wrangler 在构建 Worker 时运行的自定义构建步骤。请参阅自定义构建。
  • 如果使用 Cloudflare Vite 插件，则不适用。

• no_bundle booleanoptional

  • 跳过内部构建步骤，直接部署 Worker 脚本。必须是没有依赖项的纯 JavaScript Worker。
  • 如果使用 Cloudflare Vite 插件，则不适用。

• find_additional_modules booleanoptional

  • 如果为 true，Wrangler 将遍历 base_dir 下的文件树。 匹配 rules 的任何文件都将包含在已部署的 Worker 中。 如果 no_bundle 为 true，默认为 true，否则为 false。 只能用于 Module 格式的 Workers（不能用于 Service Worker 格式）。
  • 如果使用 Cloudflare Vite 插件，则不适用。

• base_dir stringoptional

  • 将其他文件（通过 find_additional_modules）包含到 Worker 部署中时，应评估模块 "rules" 的目录。如果未指定，默认为包含 Worker main 入口点的目录。
  • 如果使用 Cloudflare Vite 插件，则不适用。

• preserve_file_names booleanoptional

  • 确定 Wrangler 是否保留与 Worker 打包的其他模块的文件名。 默认在文件名前添加内容哈希。 例如 34de60b44167af5c5a709e62a4e20c4f18c9e3b6-favicon.ico。
  • 如果使用 Cloudflare Vite 插件，则不适用。

• minify booleanoptional

  • 上传前压缩 Worker 脚本。
  • 如果使用 Cloudflare Vite 插件，minify 由 Vite 的 build.minify ↗ 取代。

• keep_names booleanoptional

  • Wrangler 使用 esbuild 处理开发和部署的 Worker 代码。此选项允许 你指定 esbuild 是否对其 keepNames ↗ 逻辑应用于代码。默认为 true。

• logpush booleanoptional

  • 为 Worker 启用 Workers Trace Events Logpush。具有此属性的任何脚本将自动被为你的账户配置的 Workers Logpush 作业捕获。默认为 false。请参阅 Workers Logpush。

• limits Limitsoptional

  • 配置在运行时对执行施加的限制。请参阅限制。

• observability objectoptional

  • 配置 Worker 发出的遥测数据的自动可观测性设置。请参阅可观测性。

• assets Assetsoptional

  • 配置将要提供的静态资源。有关更多详情，请参阅资源（Assets）。

• exports objectoptional

  • 声明此 Worker 导出的 Durable Object 类及其生命周期状态（created、deleted、renamed、transferred、expecting-transfer）。请参阅 Durable Object 类导出。与 migrations 互斥。

• migrations objectoptional

  • 将 Durable Object 从类名映射到运行时状态的旧版命令式配置。对于新 Worker，首选 exports。请参阅 Durable Object 类迁移（旧版）。

• placement objectoptional

  • 配置 Worker 运行位置以最小化与后端服务的延迟。请参阅 Placement。
  • mode string — 设置为 "smart" 以根据观察到的延迟自动将 Worker 放置在后端服务附近。
  • region string — 指定云区域（例如 "aws:us-east-1"、"gcp:europe-west1" 或 "azure:westeurope"），将 Worker 放置在该区域的基础设施附近。
  • host string — 为单宿主第 4 层服务指定主机名和端口（例如 "my_database_host.com:5432"），将 Worker 放置在该服务附近。
  • hostname string — 为单宿主第 7 层服务指定主机名（例如 "my_api_server.com"），将 Worker 放置在该服务附近。

不可继承键可在顶层配置，但不能被环境继承，必须为每个环境单独指定。

• define Record<string, string>optional

  • 部署 Worker 时要替换的值映射。
  • 如果使用 Cloudflare Vite 插件，define 由 Vite 的 define ↗ 取代。

• vars objectoptional

  • 部署 Worker 时要设置的环境变量映射。请参阅环境变量。

• durable_objects objectoptional

  • Worker 应绑定到的 Durable Objects 列表。请参阅 Durable Objects。

• kv_namespaces objectoptional

  • Worker 应绑定到的 KV namespace 列表。请参阅 KV namespace。

• r2_buckets objectoptional

  • Worker 应绑定到的 R2 bucket 列表。请参阅 R2 bucket。

• ai_search_namespaces objectoptional

  • Worker 应绑定到的 AI Search namespace 列表。请参阅 AI Search namespace。

• ai_search objectoptional

  • 直接绑定到默认 namespace 中预先存在实例的 AI Search 实例绑定列表。请参阅 AI Search 实例。

• vectorize objectoptional

  • Worker 应绑定到的 Vectorize 索引列表。请参阅 Vectorize 索引。

• services objectoptional

  • Worker 应绑定到的 service binding 列表。请参阅 service binding。

• queues objectoptional

  • Worker 应绑定到的 Queue 生产者和消费者列表。请参阅 Queues。

• workflows objectoptional

  • Worker 应绑定到的 Workflows 列表。请参阅 Workflows。

• tail_consumers objectoptional

  • Worker 发送数据的 Tail Worker 列表。请参阅 Tail Workers。

• secrets objectoptional

  • 声明 Worker 所需的密钥名称。用于本地开发和部署期间的验证，以及作为类型生成的真实来源。请参阅密钥。
  • required string[]optional — 部署 Worker 必须设置的密钥名称列表。

• secrets_store_secrets objectoptional

  • Worker 应绑定到的 Secrets Store 绑定列表。请参阅 Secrets Store。

有三种 路由 类型：Custom Domains、routes 和 workers.dev。

Custom Domains 允许你将 Worker 连接到域或子域，而无需更改 DNS 设置或执行任何证书管理。

• pattern stringrequired

  • Worker 应运行的模式，例如 "example.com"。

• custom_domain booleanoptional

  • Worker 是否应使用 Custom Domain 而不是路由。默认为 false。

示例：

{
	"routes": [
		{
			"pattern": "shop.example.com",
			"custom_domain": true,
		},
	],
}

[[routes]]
pattern = "shop.example.com"
custom_domain = true

Routes 允许用户将 URL 模式映射到 Worker。路由可以配置为 zone ID 路由、zone 名称路由或简单路由。

• pattern stringrequired

  • Worker 可以运行的模式，例如 "example.com/*"。

• zone_id stringrequired

  • pattern 关联的 zone ID。请参阅查找 zone 和账户 ID。

示例：

{
	"routes": [
		{
			"pattern": "subdomain.example.com/*",
			"zone_id": "<YOUR_ZONE_ID>",
		},
	],
}

[[routes]]
pattern = "subdomain.example.com/*"
zone_id = "<YOUR_ZONE_ID>"

• pattern stringrequired

  • Worker 应运行的模式，例如 "example.com/*"。

• zone_name stringrequired

  • pattern 关联的 zone 名称。如果使用 API 令牌，这需要 Account 作用域。

示例：

{
	"routes": [
		{
			"pattern": "subdomain.example.com/*",
			"zone_name": "example.com",
		},
	],
}

[[routes]]
pattern = "subdomain.example.com/*"
zone_name = "example.com"

这是只需要模式的简单路由。

示例：

{
	"route": "example.com/*",
}

route = "example.com/*"

Cloudflare Workers 账户附带可在 Cloudflare 仪表板中配置的 workers.dev 子域。

• workers_dev booleanoptional
  • Worker 是否在自定义 workers.dev 账户子域上运行。默认为 true。

{
	"workers_dev": false,
}

workers_dev = false

触发器允许你定义 cron 表达式以调用 Worker 的 scheduled 函数。请参阅支持的 cron 表达式。

• crons string[]required
  • cron 表达式数组。
  • 要禁用 Cron Trigger，设置 crons = []。注释掉 crons 键不会禁用 Cron Trigger。

示例：

{
	"triggers": {
		"crons": ["* * * * *"],
	},
}

[triggers]
crons = [ "* * * * *" ]

可观测性 设置允许你直接从 Cloudflare Worker 的仪表板自动摄取、存储、过滤和分析 Cloudflare Workers 发出的日志数据。

• enabled booleanrequired

  • 在 Worker 上设置为 true 时，Worker 的日志将被持久化。所有新 Worker 默认为 true。

• head_sampling_rate numberoptional

  • 0 到 1 之间的数字，0 表示一百个请求中零个被记录，1 表示每个请求都被记录。如果未指定 head_sampling_rate，默认配置为 1（100%）。阅读更多关于基于头部的采样的信息。

示例：

{
	"observability": {
		"enabled": true,
		"head_sampling_rate": 0.1, // 10% of requests are logged
	},
}

[observability]
enabled = true
head_sampling_rate = 0.1

你可以配置在 Worker 部署前运行的自定义构建步骤。请参阅自定义构建。

• command stringoptional

  • 用于构建 Worker 的命令。在 Linux 和 macOS 上，命令在 sh shell 中执行，Windows 上在 cmd shell 中执行。可以使用 && 和 || shell 运算符。

• cwd stringoptional

  • 执行命令的目录。

• watch_dir string | string[]optional

  • 使用 wrangler dev 时监视更改的目录。默认为当前工作目录。

示例：

{
	"build": {
		"command": "npm run build",
		"cwd": "build_cwd",
		"watch_dir": "build_watch_dir",
	},
}

[build]
command = "npm run build"
cwd = "build_cwd"
watch_dir = "build_watch_dir"

你可以在运行时对 Worker 的行为施加限制。限制仅支持标准使用模型。 限制仅在部署到 Cloudflare 网络时强制执行，不在本地开发中强制执行。CPU 限制 最多可设置为 300,000 毫秒（5 分钟）。

每个 isolate 都有一些内置灵活性，以应对 Worker 偶尔超过配置限制的情况。如果你的 Worker 开始持续达到限制，其执行将根据配置的限制被终止。

• cpu_ms numberoptional

  • 每次调用允许的最大 CPU 时间，以毫秒为单位。

• subrequests numberoptional

  • 每次调用允许的最大子请求数。免费账户默认为 50，付费账户默认为 10,000。免费账户最大值为 50，付费账户最大值为 10,000,000。有关更多信息，请参阅子请求限制。

示例：

{
	"limits": {
		"cpu_ms": 100,
		"subrequests": 150,
	},
}

[limits]
cpu_ms = 100
subrequests = 150

Workers Browser Run API 允许开发者以编程方式控制无头浏览器实例并与其交互，为应用程序和产品创建自动化流程。

browser 绑定（binding） 将为 Worker 提供经过身份验证的端点，以与专用 Chromium 浏览器实例交互。

• binding stringrequired
  • 用于引用 browser 绑定的绑定名称。你设置的值（字符串）将用于在 Worker 中引用此无头浏览器。绑定必须是有效的 JavaScript 变量名 ↗。例如，binding = "HEAD_LESS" 或 binding = "simulatedBrowser" 都是有效的绑定名称。

示例：

{
	"browser": {
		"binding": "<BINDING_NAME>",
	},
}

[browser]
binding = "<BINDING_NAME>"

D1 是 Cloudflare 的无服务器 SQL 数据库。Worker 可以通过为每个数据库创建绑定（binding）以使用 D1 Workers Binding API 来查询 D1 数据库。

要将 D1 数据库绑定到 Worker，将以下对象数组分配给 [[d1_databases]] 键。

• binding stringrequired

  • 用于引用 D1 数据库的绑定名称。你设置的值（字符串）将用于在 Worker 中引用此数据库。绑定必须是有效的 JavaScript 变量名 ↗。例如，binding = "MY_DB" 或 binding = "productionDB" 都是有效的绑定名称。

• database_name stringrequired

  • 数据库名称。这是人类可读的名称，用于区分不同数据库，在首次创建数据库时设置。

• database_id stringrequired

  • 数据库 ID。首次使用 wrangler d1 create 或调用 wrangler d1 list 时可获取数据库 ID，它唯一标识你的数据库。

• preview_database_id stringoptional

  • 此 D1 数据库的预览 ID。如果提供，wrangler dev 使用此 ID。否则使用 database_id。使用 wrangler dev --remote 时需要此选项。

• migrations_dir stringoptional

  • 包含迁移文件的迁移目录。默认情况下，wrangler d1 migrations create 创建名为 migrations 的文件夹。可以使用 migrations_dir 指定包含迁移文件的不同文件夹（例如，如果你有 mono-repo 设置，并希望在 apps/packages 之间使用单个 D1 实例）。
  • 有关更多信息，请参阅 D1 Wrangler migrations 命令和 D1 迁移。

• migrations_pattern stringoptional

  • 用于发现迁移文件的 glob 模式（相对于 Wrangler 配置文件）。默认为 migrations/*.sql。
  • 使用此选项选择 ORM（如 Drizzle）产生的嵌套布局（例如 migrations/*/migration.sql）。
  • 设置 migrations_pattern 时，还必须设置 migrations_dir，且 migrations_pattern 必须以 migrations_dir 设置的值为前缀。每个迁移在 migrations 表中记录为相对于 migrations_dir 的路径。

示例：

{
	"d1_databases": [
		{
			"binding": "<BINDING_NAME>",
			"database_name": "<DATABASE_NAME>",
			"database_id": "<DATABASE_ID>",
		},
	],
}

[[d1_databases]]
binding = "<BINDING_NAME>"
database_name = "<DATABASE_NAME>"
database_id = "<DATABASE_ID>"

Dispatch namespace 绑定允许 dynamic dispatch Worker 与 dispatch namespace 之间通信。Dispatch namespace 绑定用于 Workers for Platforms。Workers for Platforms 帮助你代表客户以编程方式部署无服务器函数。

• binding stringrequired

  • 绑定名称。你设置的值（字符串）将用于在 Worker 中引用此数据库。绑定必须是有效的 JavaScript 变量名 ↗。例如，binding = "MY_NAMESPACE" 或 binding = "productionNamespace" 都是有效的绑定名称。

• namespace stringrequired

  • dispatch namespace 的名称。

• outbound objectoptional

  • service stringrequired 要绑定到的 outbound Worker 的名称。
  • parameters array optional 从 dynamic dispatch Worker 向 outbound Worker 传递数据的参数列表。

{
	"dispatch_namespaces": [
		{
			"binding": "<BINDING_NAME>",
			"namespace": "<NAMESPACE_NAME>",
			"outbound": {
				"service": "<WORKER_NAME>",
				"parameters": ["params_object"],
			},
		},
	],
}

[[dispatch_namespaces]]
binding = "<BINDING_NAME>"
namespace = "<NAMESPACE_NAME>"

  [dispatch_namespaces.outbound]
  service = "<WORKER_NAME>"
  parameters = [ "params_object" ]

Durable Objects 为 Workers 平台提供低延迟协调和一致存储。

要将 Durable Objects 绑定到 Worker，将以下对象数组分配给 durable_objects.bindings 键。

• name stringrequired

  • 用于引用 Durable Object 的绑定名称。

• class_name stringrequired

  • Durable Object 的导出类名。

• script_name stringoptional

  • 定义 Durable Object 的 Worker 名称（如果它在此 Worker 外部）。此选项可用于本地和远程开发。在本地开发中，必须在单独进程中运行外部 Worker（通过 wrangler dev）。在远程开发中，必须使用适当的远程绑定。

• environment stringoptional

  • 要绑定到的 script_name 的环境。

示例：

{
	"durable_objects": {
		"bindings": [
			{
				"name": "<BINDING_NAME>",
				"class_name": "<CLASS_NAME>",
			},
		],
	},
}

[[durable_objects.bindings]]
name = "<BINDING_NAME>"
class_name = "<CLASS_NAME>"

exports 字段声明此 Worker 导出的 Durable Object 类及其生命周期状态。请参阅 Durable Object 类导出。

exports 中的每个条目以 Durable Object 类名为键。每个条目上的字段为：

• type stringrequired

  • 对于 Durable Object 类条目，设置为 "durable-object"。

• state stringoptional

  • 生命周期状态。其中之一："created"（默认 — 活动类）、"deleted"、"renamed"、"transferred" 或 "expecting-transfer"。

• storage stringconditional

  • 当 state 为 "created" 或 "expecting-transfer" 时需要。其中之一："sqlite"（推荐；新 namespace 必需）或 "legacy-kv"（仅适用于现有键值支持的 namespace）。

• renamed_to stringconditional

  • 当 state 为 "renamed" 时需要。目标类名，还必须在同一 exports 映射中作为活动条目出现。

• transferred_to stringconditional

  • 当 state 为 "transferred" 时需要。将接收 namespace 的目标 Worker 名称。

• transfer_from stringconditional

  • 当 state 为 "expecting-transfer" 时需要。namespace 正在从中转移的源 Worker 名称。

示例：

{
	"exports": {
		"MyDurableObject": {
			"type": "durable-object",
			"storage": "sqlite",
		},
		"OldClass": {
			"type": "durable-object",
			"state": "deleted",
		},
		"OldName": {
			"type": "durable-object",
			"state": "renamed",
			"renamed_to": "NewName",
		},
		"NewName": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}

[exports.MyDurableObject]
type = "durable-object"
storage = "sqlite"

[exports.OldClass]
type = "durable-object"
state = "deleted"

[exports.OldName]
type = "durable-object"
state = "renamed"
renamed_to = "NewName"

[exports.NewName]
type = "durable-object"
storage = "sqlite"

在使用旧版 migrations 数组的 Worker 上更改 Durable Object 类时，必须执行迁移。请参阅 Durable Object 类迁移（旧版）。

• tag stringrequired

  • 此迁移的唯一标识符。

• new_sqlite_classes string[]optional

  • 使用 SQLite 存储后端定义的新 Durable Object 类。

• new_classes string[]optional

  • 使用旧版键值存储后端定义的新 Durable Object 类。

• renamed_classes {from: string, to: string}[]optional

  • 正在重命名的 Durable Object 类。

• deleted_classes string[]optional

  • 正在移除的 Durable Object 类。

• transferred_classes {from: string, from_script: string, to: string}[]optional

  • 从其他 Worker 转移的 Durable Object 类。

示例：

{
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": [
				// Array of new classes
				"DurableObjectExample",
			],
		},
		{
			"tag": "v2", // Should be unique for each entry
			"renamed_classes": [
				// Array of rename directives
				{
					"from": "DurableObjectExample",
					"to": "UpdatedName",
				},
			],
			"deleted_classes": [
				// Array of deleted class names
				"DeprecatedClass",
			],
		},
	],
}

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "DurableObjectExample" ]

[[migrations]]
tag = "v2"
deleted_classes = [ "DeprecatedClass" ]

  [[migrations.renamed_classes]]
  from = "DurableObjectExample"
  to = "UpdatedName"

您可以从 Worker 向在 Email Routing 上验证过的电子邮件地址发送有关 Worker 活动的邮件。例如，当您想了解触发了某些类型的事件时，这非常有用。

在将电子邮件地址绑定到 Worker 之前，您需要启用 Email Routing，并至少拥有一个已验证的电子邮件地址。然后，向对象 (send_email) 分配一个数组，其中包含你需要的电子邮件绑定类型。

• name stringrequired

  • 绑定名称。

• destination_address stringoptional

  • 你发送电子邮件的选定电子邮件地址。

• allowed_destination_addresses string[]optional

  • 你发送电子邮件的电子邮件地址允许列表。

您可以在 Wrangler 文件中添加一种或多种类型的绑定。但是，每个属性必须单独占一行：

{
	"send_email": [
		{
			"name": "<NAME_FOR_BINDING1>"
		},
		{
			"name": "<NAME_FOR_BINDING2>",
			"destination_address": "<YOUR_EMAIL>@example.com"
		},
		{
			"name": "<NAME_FOR_BINDING3>",
			"allowed_destination_addresses": [
				"<YOUR_EMAIL>@example.com",
				"<YOUR_EMAIL2>@example.com"
			]
		}
	]
}

[[send_email]]
name = "<NAME_FOR_BINDING1>"

[[send_email]]
name = "<NAME_FOR_BINDING2>"
destination_address = "<YOUR_EMAIL>@example.com"

[[send_email]]
name = "<NAME_FOR_BINDING3>"
allowed_destination_addresses = [ "<YOUR_EMAIL>@example.com", "<YOUR_EMAIL2>@example.com" ]

环境变量 是一种绑定类型，允许你将文本字符串或 JSON 值附加到 Worker。

示例：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker-dev",
	"vars": {
		"API_HOST": "example.com",
		"API_ACCOUNT_ID": "example_user",
		"SERVICE_X_DATA": {
			"URL": "service-x-api.dev.example",
			"MY_ID": 123
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker-dev"

[vars]
API_HOST = "example.com"
API_ACCOUNT_ID = "example_user"

  [vars.SERVICE_X_DATA]
  URL = "service-x-api.dev.example"
  MY_ID = 123

Hyperdrive 绑定允许你在 Worker 内与任何 Postgres 数据库交互和查询。

• binding stringrequired

  • 绑定名称。

• id stringrequired

  • Hyperdrive 配置的 ID。

示例：

{
	// required for database drivers to function
	"compatibility_flags": ["nodejs_compat_v2"],
	"hyperdrive": [
		{
			"binding": "<BINDING_NAME>",
			"id": "<ID>",
		},
	],
}

compatibility_flags = [ "nodejs_compat_v2" ]

[[hyperdrive]]
binding = "<BINDING_NAME>"
id = "<ID>"

Cloudflare Images 允许你发出转换请求以优化、调整大小和操作存储在远程源中的图像。

要将 Images 绑定到 Worker，将以下对象数组分配给 images 键。

binding（必填）。用于引用 Images API 的绑定名称。

{
	"images": {
		"binding": "IMAGES", // i.e. available in your Worker on env.IMAGES
	},
}

[images]
binding = "IMAGES"

Workers KV 是一个全球低延迟的键值数据存储。它将数据存储在少数集中式数据中心，并在访问后将该数据缓存在 Cloudflare 的数据中心中。

要将 KV namespace 绑定到 Worker，将以下对象数组分配给 kv_namespaces 键。

• binding stringrequired

  • 用于引用 KV namespace 的绑定名称。

• id stringrequired

  • KV namespace 的 ID。

• preview_id stringoptional

  • 此 KV namespace 的预览 ID。使用 wrangler dev --remote 针对远程资源开发时，此选项必需（但使用远程绑定时不需要）。如果本地开发，这是可选字段。wrangler dev 将使用此 ID 作为 KV namespace。否则 wrangler dev 将使用 id。

示例：

{
	"kv_namespaces": [
		{
			"binding": "<BINDING_NAME1>",
			"id": "<NAMESPACE_ID1>",
		},
		{
			"binding": "<BINDING_NAME2>",
			"id": "<NAMESPACE_ID2>",
		},
	],
}

[[kv_namespaces]]
binding = "<BINDING_NAME1>"
id = "<NAMESPACE_ID1>"

[[kv_namespaces]]
binding = "<BINDING_NAME2>"
id = "<NAMESPACE_ID2>"

AI Search 是 Cloudflare 的托管搜索服务。namespace 是 AI Search 实例的逻辑分组。绑定授予对 namespace 内所有实例的完全访问权限。

要将 AI Search namespace 绑定到 Worker，将以下对象数组分配给 ai_search_namespaces 键。

• binding stringrequired

  • 用于引用 AI Search namespace 的绑定名称。

• namespace stringrequired

  • AI Search namespace 的名称。每个账户自动创建 default namespace。如果 namespace 不存在，Wrangler 在部署时创建它。

示例：

{
	"ai_search_namespaces": [
		{
			"binding": "<BINDING_NAME>",
			"namespace": "default",
		},
	],
}

[[ai_search_namespaces]]
binding = "<BINDING_NAME>"
namespace = "default"

要直接绑定到默认 namespace 中预先存在的 AI Search 实例，将以下对象数组分配给 ai_search 键。此绑定不支持 namespace 级操作，如 list()、create() 或 delete()。

• binding stringrequired

  • 用于引用 AI Search 实例的绑定名称。

• instance_name stringrequired

  • AI Search 实例的名称。部署时必须存在于默认 namespace 中。

示例：

{
	"ai_search": [
		{
			"binding": "<BINDING_NAME>",
			"instance_name": "<INSTANCE_NAME>",
		},
	],
}

[[ai_search]]
binding = "<BINDING_NAME>"
instance_name = "<INSTANCE_NAME>"

Queues 是 Cloudflare 的全球消息队列服务，提供保证交付和消息批处理。要通过 Workers 与 queue 交互，需要 producer Worker 向 queue 发送消息，以及 consumer Worker 从 Queue 拉取消息批次。单个 Worker 可以向多个 Queues 生产和消费。

要将 Queues 绑定到 producer Worker，将以下对象数组分配给 [[queues.producers]] 键。

• queue stringrequired

  • queue 名称，在 Cloudflare 仪表板中使用。

• binding stringrequired

  • 在 Worker 中引用 queue 的绑定名称。绑定必须是有效的 JavaScript 变量名 ↗。例如，binding = "MY_QUEUE" 或 binding = "productionQueue" 都是有效的绑定名称。

• delivery_delay numberoptional

  • 默认延迟发送到 queue 的消息的秒数。可以按消息或按批次覆盖。

示例：

{
	"queues": {
		"producers": [
			{
				"binding": "<BINDING_NAME>",
				"queue": "<QUEUE_NAME>",
				"delivery_delay": 60, // Delay messages by 60 seconds before they are delivered to a consumer
			},
		],
	},
}

[[queues.producers]]
binding = "<BINDING_NAME>"
queue = "<QUEUE_NAME>"
delivery_delay = 60

要将 Queues 绑定到 consumer Worker，将以下对象数组分配给 [[queues.consumers]] 键。

• queue stringrequired

  • queue 名称，在 Cloudflare 仪表板中使用。

• max_batch_size numberoptional

  • 每批允许的最大消息数。

• max_batch_timeout numberoptional

  • 在批次发送到 consumer Worker 之前等待消息填满批次的最大秒数。

• max_retries numberoptional

  • 消息失败或调用 retryAll() 时的最大重试次数。

• dead_letter_queue stringoptional

  • 如果消息处理失败至少 max_retries 次，则发送到的另一个 queue 的名称。
  • 如果未定义 dead_letter_queue，反复处理失败的消息将被丢弃。
  • 如果没有指定名称的 queue，将自动创建。

• max_concurrency numberoptional

  • 允许同时运行的最大并发 consumer 数。如果未设置，调用次数将扩展到当前支持的最大值。
  • 有关 consumer 如何自动扩展的更多信息，特别是消息重试时，请参阅 Consumer concurrency。

• retry_delay numberoptional

  • 默认延迟重试消息的秒数，然后重新交付给 consumer。重试消息时可以按消息或按批次覆盖。

示例：

{
	"queues": {
		"consumers": [
			{
				"queue": "my-queue",
				"max_batch_size": 10,
				"max_batch_timeout": 30,
				"max_retries": 10,
				"dead_letter_queue": "my-queue-dlq",
				"max_concurrency": 5,
				"retry_delay": 120, // Delay retried messages by 2 minutes before re-attempting delivery
			},
		],
	},
}

[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
max_batch_timeout = 30
max_retries = 10
dead_letter_queue = "my-queue-dlq"
max_concurrency = 5
retry_delay = 120

Cloudflare R2 Storage 允许开发者存储大量非结构化数据，而无需典型云存储服务相关的高昂出口带宽费用。

要将 R2 bucket 绑定到 Worker，将以下对象数组分配给 r2_buckets 键。

• binding stringrequired

  • 用于引用 R2 bucket 的绑定名称。

• bucket_name stringrequired

  • 此 R2 bucket 的名称。

• jurisdiction stringoptional

  • 如果指定了管辖区域，此 R2 bucket 所在的管辖区域。请参阅管辖限制。

• preview_bucket_name stringoptional

  • 此 R2 bucket 的预览名称。如果提供，wrangler dev 将使用此名称作为 R2 bucket。否则将使用 bucket_name。使用 wrangler dev --remote 时需要此选项（但使用远程绑定时不需要）。

示例：

{
	"r2_buckets": [
		{
			"binding": "<BINDING_NAME1>",
			"bucket_name": "<BUCKET_NAME1>",
		},
		{
			"binding": "<BINDING_NAME2>",
			"bucket_name": "<BUCKET_NAME2>",
		},
	],
}

[[r2_buckets]]
binding = "<BINDING_NAME1>"
bucket_name = "<BUCKET_NAME1>"

[[r2_buckets]]
binding = "<BINDING_NAME2>"
bucket_name = "<BUCKET_NAME2>"

Vectorize 索引 允许你插入和查询向量嵌入，用于语义搜索、分类和其他向量搜索用例。

要将 Vectorize 索引绑定到 Worker，将以下对象数组分配给 vectorize 键。

• binding stringrequired

  • 从 Worker 代码引用绑定索引的绑定名称。

• index_name stringrequired

  • 要绑定的索引名称。

示例：

{
	"vectorize": [
		{
			"binding": "<BINDING_NAME>",
			"index_name": "<INDEX_NAME>",
		},
	],
}

[[vectorize]]
binding = "<BINDING_NAME>"
index_name = "<INDEX_NAME>"

service binding 允许你向另一个 Worker 发送 HTTP 请求，而无需这些请求经过 Internet。请求立即调用下游 Worker，与向第三方服务发送请求相比减少了延迟。请参阅关于 Service Binding。

要将其他 Workers 绑定到你的 Worker，将以下对象数组分配给 services 键。

• binding stringrequired

  • 用于引用绑定 Worker 的绑定名称。

• service stringrequired

  • Worker 的名称。
  • 要绑定到特定环境中的 Worker，需要将环境名称附加到 Worker 名称。格式应为 <worker-name>-<environment-name>。例如，要绑定到 staging 环境中名为 worker-name 的 Worker，service 应设置为 worker-name-staging。

• entrypoint stringoptional

  • 要绑定到的 entrypoint 名称。如果未指定 entrypoint，将使用 Worker 的默认导出。

示例：

{
	"services": [
		{
			"binding": "<BINDING_NAME>",
			"service": "<WORKER_NAME>",
			"entrypoint": "<ENTRYPOINT_NAME>",
		},
	],
}

[[services]]
binding = "<BINDING_NAME>"
service = "<WORKER_NAME>"
entrypoint = "<ENTRYPOINT_NAME>"

请参阅资源（Assets）。

Workers Analytics Engine 提供来自 Workers 的分析、可观测性和数据日志记录。将数据点写入 Worker 绑定，然后使用 SQL API 查询数据。

要将 Analytics Engine 数据集绑定到 Worker，将以下对象数组分配给 analytics_engine_datasets 键。

• binding stringrequired

  • 用于引用数据集的绑定名称。

• dataset stringoptional

  • 要写入的数据集名称。如果未提供，默认为与绑定相同的名称。

示例：

{
	"analytics_engine_datasets": [
		{
			"binding": "<BINDING_NAME>",
			"dataset": "<DATASET_NAME>",
		},
	],
}

[[analytics_engine_datasets]]
binding = "<BINDING_NAME>"
dataset = "<DATASET_NAME>"

要与需要客户端身份验证的源站通信，Worker 可以在子请求中出示 mTLS 证书。Wrangler 提供 mtls-certificate 命令 来上传和管理这些证书。

要为 Worker 创建 mTLS 证书的绑定（binding），将具有以下形状的对象数组分配给 mtls_certificates 键。

• binding stringrequired

  • 用于引用证书的绑定名称。

• certificate_id stringrequired

  • 证书的 ID。Wrangler 通过 mtls-certificate upload 和 mtls-certificate list 命令显示此 ID。

包含 mTLS 证书绑定的 Wrangler 配置文件示例：

{
	"mtls_certificates": [
		{
			"binding": "<BINDING_NAME1>",
			"certificate_id": "<CERTIFICATE_ID1>",
		},
		{
			"binding": "<BINDING_NAME2>",
			"certificate_id": "<CERTIFICATE_ID2>",
		},
	],
}

[[mtls_certificates]]
binding = "<BINDING_NAME1>"
certificate_id = "<CERTIFICATE_ID1>"

[[mtls_certificates]]
binding = "<BINDING_NAME2>"
certificate_id = "<CERTIFICATE_ID2>"

然后可以在运行时通过 fetch 方法 使用 mTLS 证书绑定与受保护的源站通信。

Workers AI 允许你在 Cloudflare 网络上从自己的代码运行机器学习模型—— 无论是从 Workers、Pages 还是通过 REST API 的任何地方。

与其他绑定不同，此绑定限制每个 Worker 项目只能有一个 AI 绑定。

• binding stringrequired
  • 绑定名称。

示例：

{
	"ai": {
		"binding": "AI", // available in your Worker code on `env.AI`
	},
}

[ai]
binding = "AI"

Workflows 允许你使用 Workers 平台构建持久的多步骤应用程序。Workflow 绑定使 Worker 能够以编程方式创建和管理 Workflow 实例。

要将 Workflows 绑定到 Worker，将以下对象数组分配给 workflows 键。

• binding stringrequired

  • 在 Worker 中引用 Workflow 的绑定名称。绑定必须是有效的 JavaScript 变量名 ↗。例如，binding = "MY_WORKFLOW" 是有效的绑定名称。

• name stringrequired

  • Workflow 的名称。

• class_name stringrequired

  • 导出的 Workflow 类名称。class_name 必须与 Worker 代码导出的 Workflow 类名称匹配。

• script_name stringoptional

  • 定义 Workflow 类的 Worker 脚本名称。仅当 Workflow 定义在与配置绑定的 Worker 不同的 Worker 中时才需要。

• schedules string[]optional

  • 自动创建此 Workflow 新实例的 cron 计划列表。
  • 当你想在重复间隔上运行 Workflow 而不定义顶层 triggers.crons 和单独的 scheduled 处理程序时使用。
  • 使用支持 Workflow 计划的 Wrangler 版本。如果本地 schema 不识别 schedules，请先更新 Wrangler。

示例：

{
	"workflows": [
		{
			"binding": "<BINDING_NAME>",
			"name": "<WORKFLOW_NAME>",
			"class_name": "<CLASS_NAME>",
		},
	],
}

[[workflows]]
binding = "<BINDING_NAME>"
name = "<WORKFLOW_NAME>"
class_name = "<CLASS_NAME>"

静态资源 允许开发者在 Workers 上运行前端网站。你可以配置资源目录、可选的运行时绑定和路由配置选项。

每个 Worker 只能配置一个资源集合。

assets 键下提供以下选项。

• directory stringoptional

  • 要提供的静态资源文件夹。
  • 如果使用 Cloudflare Vite 插件，则不需要，它将自动指向客户端构建输出。

• binding stringoptional

  • 用于引用资源的绑定名称。可选，仅当使用 main 设置 Worker 脚本时才有用。

• run_worker_first boolean | string[]optional, defaults to false

  • 控制是直接获取静态资源还是调用 Worker 脚本。可以是布尔值（true/false）或路由模式字符串数组，支持 glob 模式（*）和例外模式（! 前缀）。模式必须以 / 或 !/ 开头。了解使用 run_worker_first 时获取资源的更多信息。

• html_handling: "auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none"optional, defaults to "auto-trailing-slash"

  • 确定 HTML 内容请求的重定向和重写。在资源路由中了解各种选项的更多信息。

• not_found_handling: "single-page-application" | "404-page" | "none"optional, defaults to "none"

  • 确定不映射到资源的请求的处理方式。在路由行为中了解各种选项的更多信息。

示例：

{
	"assets": {
		"directory": "./public",
		"binding": "ASSETS",
		"html_handling": "force-trailing-slash",
		"not_found_handling": "404-page",
	},
}

[assets]
directory = "./public"
binding = "ASSETS"
html_handling = "force-trailing-slash"
not_found_handling = "404-page"

你还可以使用路由模式数组配置 run_worker_first：

{
	"assets": {
		"directory": "./public",
		"binding": "ASSETS",
		"run_worker_first": [
			"/api/*", // API calls go to Worker first
			"!/api/docs/*", // EXCEPTION: For /api/docs/*, try static assets first
		],
	},
}

[assets]
directory = "./public"
binding = "ASSETS"
run_worker_first = [ "/api/*", "!/api/docs/*" ]

你可以使用 containers 字段定义与 Worker 一起运行的 Containers。

提供以下选项：

• image stringrequired

  • 容器使用的镜像。可以是 Dockerfile 的本地路径（此时 wrangler deploy 将 构建并推送镜像），也可以是镜像引用。支持的注册表包括 Cloudflare Registry、Docker Hub、Amazon ECR 和 Google Artifact Registry。有关更多信息，请参阅镜像管理。

• class_name stringrequired

  • 对应的 Durable Object 类名。这将使此 Durable Object 成为支持 container 的 Durable Object 并允许每个实例控制 container。有关详情，请参阅 Durable Object Container Methods。

• instance_type stringoptional

  • container 的实例类型。这决定分配给 container 实例的内存、CPU 和磁盘量。当前选项为 "lite"、"basic"、"standard-1"、"standard-2"、"standard-3" 和 "standard-4"。默认为 "lite"。有关更多信息， 请参阅实例类型文档。

  • 要指定自定义实例类型，请参阅此处。

• max_instances stringoptional

  • 任何给定时刻要运行的最大并发 container 实例数。已停止的 container 不计入此限制 — 你可能总共有更多 container 实例，但一次只有这么多 actively running container。如果启动 container 的请求超过此限制，该请求将出错。

  • 默认为 20。

  • 此值仅在 Cloudflare 网络上生产运行时强制执行。此限制不适用于本地开发，因此你可以运行比指定更多的实例。

• name stringoptional

  • container 的名称。用作标识符。默认为 Worker 名称、类 名和环境的组合。

• image_build_context stringoptional

  • 应用程序的构建上下文，默认为 image 的目录。

• image_vars Record<string, string>optional

  • 构建时变量，等效于使用 docker build 的 --build-arg。如果要在_运行时_向 container 提供环境变量，应使用 Container 类上的 secret 绑定或 envVars。

• rollout_active_grace_period numberoptional

  • 发布 期间活动 container 实例有资格更新之前等待的最少秒数。此时，container 将收到 SIGTERM 信号，在被强制终止和更新之前仍有 15 分钟关闭时间。
  • 默认为 0。

• rollout_step_percentage number | number[]optional

  • 配置发布的每个步骤应更新多少百分比的实例。
  • 如果设置为单个数字，每个步骤将发布到该百分比的实例。选项为 5、10、20、25、50 或 100。
  • 如果是数字数组，每个步骤指定累积发布进度，因此最后一步必须为 100。
  • 默认为 [10, 100]。
  • 可以通过使用 --containers-rollout=immediate 标志部署临时覆盖，这将在一个步骤中发布到 100% 的实例。请注意，如果配置了 rollout_active_grace_period，该标志不会覆盖它。

• ssh objectoptional

  • 通过 Wrangler 的 SSH 配置。请参阅 SSH。

• wrangler_ssh objectoptional deprecated, use `ssh`

  • ssh 的已弃用别名。仍支持向后兼容。

• authorized_keys object[]optional

  • 应添加到 Container 的 authorized_keys 文件的公钥。

• constraints objectoptional

  • container 的放置约束。有关详情，请参阅 Containers placement。

• constraints.regions string[]optional

  • 将 container 放置限制在特定地理区域。有效值："ENAM"、"WNAM"、"EEUR"、"WEUR"、"APAC"、"SAM"、"ME"、"OC"、"AFR"。

• constraints.jurisdiction stringoptional

  • 将 container 限制在合规边界内。有效值："eu"、"fedramp"。

{
	"containers": [
		{
			"class_name": "MyContainer",
			"image": "./Dockerfile",
			"max_instances": 10,
			"instance_type": "basic", // Optional, defaults to "lite"
			"image_vars": {
				"FOO": "BAR",
			},
			"constraints": {
				"regions": ["ENAM", "WNAM"],
				"jurisdiction": "fedramp",
			},
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_CONTAINER",
				"class_name": "MyContainer",
			},
		],
	},
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": ["MyContainer"],
		},
	],
}

[[containers]]
class_name = "MyContainer"
image = "./Dockerfile"
max_instances = 10
instance_type = "basic"

  [containers.image_vars]
  FOO = "BAR"

  [containers.constraints]
  regions = [ "ENAM", "WNAM" ]
  jurisdiction = "fedramp"

[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "MyContainer" ]

代替命名实例类型，可以通过单独配置 vCPU、内存和磁盘来设置自定义实例类型。 有关自定义实例类型的约束，请参阅限制文档。

提供以下选项：

• vcpu numberoptional

  • container 使用的 vCPU。默认为 0.0625（1/16 vCPU）。

• memory_mib numberoptional

  • container 使用的内存，以 MiB 为单位。默认为 256。

• disk_mb numberoptional

  • container 使用的磁盘，以 MB 为单位。默认为 2000（2GB）。

{
	"containers": [
		{
			"image": "./Dockerfile",
			"instance_type": {
				"vcpu": 1,
				"memory_mib": 1024,
				"disk_mb": 4000,
			},
		},
	],
}

[[containers]]
image = "./Dockerfile"

  [containers.instance_type]
  vcpu = 1
  memory_mib = 1_024
  disk_mb = 4_000

通过 Wrangler 访问 Container 实例的 SSH 配置。有关通过 SSH 连接到 Containers 的指南，请参阅 SSH。

提供以下选项：

• enabled booleanoptional

  • 是否启用通过 Wrangler 的 SSH。默认为 true。设置为 false 以禁用 SSH 访问。

• port numberoptional

  • SSH 服务运行的端口。默认为 22。

授权密钥是可用于 SSH 进入 Container 的公钥。

密钥具有以下属性：

• name stringrequired

  • 密钥的显示名称。

• public_key stringrequired

  • 公钥本身。
  • 目前仅支持 ssh-ed25519 密钥类型。

Wrangler 可以在两种模式下运行：默认打包模式和 --no-bundle 模式。 在打包模式下，Wrangler 将遍历代码的所有 import 并生成单个 JavaScript "entry-point" 文件。 导入的源代码被 "inline/bundle" 到此 entry-point 文件中。

还可以将其他模块包含到 Worker 中，与 entry-point 一起上传。 使用 rules 键指定应包含到 Worker 中的其他模块，使这些模块在调用 Worker 时可供 import。 rules 键将是以下对象的数组。

• type stringrequired

  • 模块类型。必须是以下之一：ESModule、CommonJS、CompiledWasm、Text 或 Data。

• globs string[]required

  • glob 规则数组（例如 ["**/*.md"]）。请参阅 glob ↗。

• fallthrough booleanoptional

  • 在规则上设置为 true 时，允许为同一 Type 设置多个规则。

示例：

{
	"rules": [
		{
			"type": "Text",
			"globs": ["**/*.md"],
			"fallthrough": true,
		},
	],
}

[[rules]]
type = "Text"
globs = [ "**/*.md" ]
fallthrough = true

你可以在 Worker 中 import 和引用这些模块，如下所示：

import markdown from "./example.md";

export default {
	async fetch() {
		return new Response(markdown);
	},
};

通常 Wrangler 仅包含在源代码中静态 import 的其他模块，如上述示例。 通过在配置文件中将 find_additional_modules 设置为 true，Wrangler 将遍历 base_dir 下的文件树。 匹配 rules 的任何文件也将作为未打包的外部模块包含在已部署的 Worker 中。 base_dir 默认为包含 main 入口点的目录。

请参阅 https://developers.cloudflare.com/workers/wrangler/bundling/ ↗ 了解更多详情和示例。

默认情况下，Python Workers 打包 Worker 根目录（wrangler 配置文件旁）中 python_modules 的文件和文件夹。 此目录中的文件代表你的 vendored 包，pywrangler 工具将包复制到此处。在某些情况下，你可能 发现此文件夹中的文件太大，如果 worker 不需要它们，它们只会无谓地增大 bundle 大小。

要修复此问题，可以排除某些文件不被包含。使用 python_modules.excludes 选项，例如：

{
	"python_modules": {
		"excludes": ["**/*.pyc", "**/__pycache__"],
	},
}

[python_modules]
excludes = [ "**/*.pyc", "**/__pycache__" ]

这将排除 python_modules 中任何子目录内的所有 .pyc 文件和 __pycache__ 目录。

默认情况下，python_modules.excludes 设置为 ["**/*.pyc"]，因此在设置为不同值时请务必包含此项。

你可以配置本地开发的各个方面，例如本地协议或端口。

• ip stringoptional

• 本地 dev 服务器监听的 IP 地址。默认为 localhost。

• port numberoptional

• 本地 dev 服务器监听的端口。默认为 8787。

• local_protocol stringoptional

  • 本地 dev 服务器监听请求的协议。默认为 http。

• upstream_protocol stringoptional

  • 本地 dev 服务器转发请求的协议。默认为 https。

• host stringoptional

  • 转发请求的目标主机，默认为 Worker 第一个 route 的主机。

• enable_containers booleanoptional

  • 确定在本地 dev 会话期间是否启用 container（如果已配置）。默认为 true。如果设置为 false，可以在不需要 Docker 或其他 container 工具的情况下开发应用程序的其余部分，只要你不调用与 container 交互的任何代码。

• container_engine stringoptional

  • 用于 Containers 的本地开发。Wrangler 将尝试自动找到用于与 container 引擎通信的正确 socket。如果不起作用（通常在尝试连接 Container 时显示为 internal error），可以尝试使用此选项设置 socket 路径。也可以通过环境变量 DOCKER_HOST 设置。

• generate_types booleanoptional

  • 根据 Worker 配置生成类型。默认为 false。

{
	"dev": {
		"ip": "192.168.1.1",
		"port": 8080,
		"local_protocol": "http",
	},
}

[dev]
ip = "192.168.1.1"
port = 8_080
local_protocol = "http"

密钥 是一种绑定类型，允许你附加加密文本值到 Worker。

secrets 配置属性允许你在 Wrangler 配置文件中声明 Worker 所需的密钥名称。在本地开发和部署期间验证必需的密钥，并用作类型生成的真实来源。

{
	"secrets": {
		"required": ["API_KEY", "DB_PASSWORD"],
	},
}

[secrets]
required = [ "API_KEY", "DB_PASSWORD" ]

类型生成

在任何配置级别定义 secrets 时，wrangler types 从 secrets.required 中列出的名称生成类型化绑定，不再从 .dev.vars 或 .env 文件推断密钥名称。这允许你在不存在这些文件的环境中运行类型生成。

支持按环境的密钥。每个命名环境生成自己的接口，聚合的 Env 类型将仅出现在某些环境中的密钥标记为可选。

部署

定义 secrets 时，wrangler deploy 和 wrangler versions upload 在操作成功之前验证 secrets.required 中的所有密钥是否已在 Worker 上配置。如果缺少任何必需的密钥，命令将失败并列出需要设置的密钥。

将本地开发使用的 secrets 放在 .dev.vars 文件或 .env 文件中，与 Wrangler 配置文件位于同一目录。

这些文件应使用 dotenv ↗ 语法格式化。例如：

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

要为每个 Cloudflare 环境设置不同的 secrets，请创建名为 .dev.vars.<environment-name> 或 .env.<environment-name> 的文件。

在本地开发中选择 Cloudflare 环境时，会先加载对应的环境特定文件，再加载通用的 .dev.vars（或 .env）文件。

• 使用 .dev.vars.<environment-name> 文件时，每个环境必须定义所有 secrets。如果存在 .dev.vars.<environment-name>，则只会加载该文件；不会加载 .dev.vars 文件。
• 相比之下，所有匹配的 .env 文件都会被加载，值会被合并。对于每个变量，使用最特定文件中的值，优先级如下：
  • .env.<environment-name>.local（最特定）
  • .env.local
  • .env.<environment-name>
  • .env（最不特定）

你可以通过配置 alias 字段，配置 Wrangler 将所有 import 特定包的调用替换为你选择的模块：

{
	"alias": {
		"foo": "./replacement-module-filepath",
	},
}

[alias]
foo = "./replacement-module-filepath"

export const bar = "baz";

使用上述配置，任何 import 或 require() 模块 foo 的调用都将被别名指向你的替换模块：

import { bar } from "foo";

console.log(bar); // returns "baz"

Wrangler 打包 Worker 时，可能无法解析依赖项。为此类依赖项设置别名是修复问题的简单方法。

但是，在此之前，请验证包是否正确安装在项目中，无论是 package.json 中的直接依赖项还是传递依赖项。

如果别名是依赖项问题的正确解决方案，你有几个选项：

• 替代实现 — 以 Worker 兼容的方式实现模块逻辑，确保所有功能保持完整。
• 空操作模块 — 如果模块逻辑未使用或不相关，将别名指向空文件。这使模块成为空操作，同时修复打包问题。
• 运行时错误 — 如果模块逻辑未使用且 Worker 不应尝试使用它（例如，由于安全漏洞），将别名指向具有单个顶层 throw 语句的文件。这修复打包问题，同时确保模块永远不会实际使用。

你可以使用模块别名为在 Workers 上不起作用的 NPM 包提供实现 — 即使你只是间接依赖该 NPM 包，作为 Worker 依赖项之一的依赖项。

例如，一些 NPM 包依赖 node-fetch ↗，这是一个在 fetch() API 内置到 Node.js 之前提供 polyfill 的包。

Workers 中不需要 node-fetch，因为 fetch() API 由 Workers 运行时提供。node-fetch 在 Workers 上不起作用，因为它依赖 http/https 模块中当前不支持的 Node.js API。

你可以将所有 node-fetch 的 import 别名直接指向 Workers 运行时内置的 fetch() API：

{
	"alias": {
		"node-fetch": "./fetch-polyfill",
	},
}

[alias]
node-fetch = "./fetch-polyfill"

export default fetch;

你可以使用模块别名为 Workers 运行时中尚不可用的 Node.js API 提供自己的 polyfill 实现。

例如，假设你依赖的 NPM 包调用 fs.readFile ↗。可以通过将以下内容添加到 Worker 的 Wrangler 配置文件来别名 fs 模块：

{
	"alias": {
		"fs": "./fs-polyfill",
	},
}

[alias]
fs = "./fs-polyfill"

export function readFile() {
	// ...
}

在许多情况下，这允许你提供足够的 API 使依赖项工作。你可以在 Cloudflare Workers Node.js API 文档页面 了解更多关于 Cloudflare Workers 对 Node.js API 的支持。

Source map 将编译和压缩的代码转换回你编写的原始代码。Source map 与 JavaScript 运行时返回的堆栈跟踪结合，向你呈现堆栈跟踪。

• upload_source_maps boolean
  • 当 upload_source_maps 设置为 true 时，Wrangler 在运行 wrangler deploy 或 wrangler versions deploy 时将自动生成并上传 source map 文件。

示例：

{
	"upload_source_maps": true,
}

upload_source_maps = true

Workers Sites 允许你在 Workers 上托管静态网站，或使用 Vue 或 React 等框架的动态网站。

• bucket stringrequired

  • 包含静态资源的目录。必须是相对于 Wrangler 配置文件的路径。

• include string[]optional

  • 匹配 bucket 位置中文件或目录名称的 .gitignore 风格模式的独占列表。仅上传匹配项。

• exclude string[]optional

  • 匹配 bucket 中应排除上传的文件或目录的 .gitignore 风格模式列表。

示例：

{
	"site": {
		"bucket": "./public",
		"include": ["upload_dir"],
		"exclude": ["ignore_dir"],
	},
}

[site]
bucket = "./public"
include = [ "upload_dir" ]
exclude = [ "ignore_dir" ]

企业网络通常在其网络上有代理，这有时会导致连接问题。要使用适当的代理详情配置 Wrangler，添加以下环境变量：

• https_proxy
• HTTPS_PROXY
• http_proxy
• HTTP_PROXY

要在 macOS 上配置此设置，在 Wrangler 命令前添加 HTTP_PROXY=http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>。

示例：

$ HTTP_PROXY=http://localhost:8080 wrangler dev

如果你的 IT 团队已配置计算机的代理设置，请注意 Wrangler 发出出站请求时将使用此列表中第一个非空环境变量。

例如，如果同时设置了 https_proxy 和 http_proxy，Wrangler 将仅使用 https_proxy 进行出站请求。

我们建议将 Wrangler 配置文件视为 Worker 配置的真实来源，如果使用 Wrangler，避免通过 Cloudflare 仪表板更改 Worker。

如果需要通过 Cloudflare 仪表板更改 Worker，仪表板将生成 TOML 片段供你复制到 Wrangler 配置文件，这有助于确保 Wrangler 配置文件始终是最新的。

如果你在 Cloudflare 仪表板中更改环境变量，Wrangler 将在下次部署时覆盖它们。如果要禁用此行为，在 Wrangler 配置文件中添加 keep_vars = true。

如果你在仪表板中更改路由，Wrangler 将在下次部署时用 Wrangler 配置文件中设置的路由覆盖它们。要仅通过 Cloudflare 仪表板管理路由，从 Wrangler 配置文件中移除任何 route 和 routes 键。然后在 Wrangler 配置文件中添加 workers_dev = false。有关更多信息，请参阅已弃用。

Wrangler 不会删除你的密钥（加密环境变量），除非你运行 wrangler secret delete <key>。

一些框架工具或自定义预构建过程生成修改后的 Wrangler 配置以部署 Worker 代码。 在这种情况下，工具还可能创建特殊的 .wrangler/deploy/config.json 文件，将 Wrangler 重定向到使用生成的配置而不是原始用户配置。

Wrangler 仅对以下与 deploy 和 dev 相关的命令使用此生成的配置：

• wrangler deploy
• wrangler dev
• wrangler versions upload
• wrangler versions deploy
• wrangler pages deploy
• wrangler pages functions build

运行这些命令时，Wrangler 从当前工作目录沿目录树向上查找路径 .wrangler/deploy/config.json 处的文件。 此文件必须仅包含以下形式的单个 JSON 对象：

{ "configPath": "../../path/to/wrangler.jsonc" }

当此 config.json 文件存在时，Wrangler 将跟随 configPath（相对于 .wrangler/deploy/config.json 文件）查找生成的 Wrangler 配置文件以在当前命令中加载和使用。 Wrangler 将向用户显示消息，表明配置已重定向到与用户配置文件不同的文件。

生成的配置文件不应包含任何环境。 这是因为当需要此类文件时，应作为构建步骤的一部分创建，该步骤应已针对特定环境。这些构建工具应为不同环境生成不同的部署配置文件。

使用重定向配置的常见示例是自定义构建工具或框架希望在部署时修改用户配置，通过在 dist 目录中生成新配置。

• 首先，用户编写使用 Cloudflare Workers 资源的代码，通过如下用户 Wrangler 配置文件配置：

  {
  	"$schema": "./node_modules/wrangler/config-schema.json",
  	"name": "my-worker",
  	"main": "src/index.ts",
  	"vars": {
  		"MY_VARIABLE": "production variable",
  	},
  	"env": {
  		"staging": {
  			"vars": {
  				"MY_VARIABLE": "staging variable",
  			},
  		},
  	},
  }

  "$schema" = "./node_modules/wrangler/config-schema.json"
  name = "my-worker"
  main = "src/index.ts"
  
  [vars]
  MY_VARIABLE = "production variable"
  
  [env.staging.vars]
  MY_VARIABLE = "staging variable"

  此配置将 main 指向用户代码入口点，并在两个不同环境中定义 MY_VARIABLE 变量。

• 然后，用户为给定环境（例如 staging）运行自定义构建。这将读取用户的 Wrangler 配置文件以查找源代码入口点和环境特定设置：

  > my-tool build --env=staging

• my-tool 生成包含编译代码和新生成的部署配置文件的 dist 目录，仅包含给定环境的设置。 它还创建 .wrangler/deploy/config.json 文件，将 Wrangler 重定向到新的生成部署配置文件：

  • dist/
    • index.js
    • wrangler.jsonc
  • .wrangler/
    • deploy/
      • config.json

生成的 dist/wrangler.jsonc 可能包含：

{
	"name": "my-worker",
	"main": "./index.js",
	"vars": {
		"MY_VARIABLE": "staging variable"
	}
}

现在，main 属性指向生成的代码入口点，未定义环境， MY_VARIABLE 变量解析为 staging 环境值。

.wrangler/deploy/config.json 包含生成的配置文件路径：

{
	"configPath": "../../dist/wrangler.jsonc"
}