Wrangler 到 cf 参考

cf migrate 会替你将 Wrangler 项目转换为 cf。它根据 Wrangler 配置文件写入 cloudflare.config.ts，将 cf 添加到项目，并列出需要你手动完成的事项。请先阅读迁移 Wrangler 项目，然后使用本页了解 cf migrate 更改了什么，或手动完成转换。

命令

大多数 Wrangler 命令都有 cf 等效项，尽管命令名称和参数可能不同。例如，Worker 版本和部署位于 cf workers versions 和 cf workers deployments 下。

要查找任务对应的 cf 命令，可以使用以下任一方式：

搜索：向 cf cli search 描述任务，然后用 cf schema 检查匹配项：
```
cf cli search "create a D1 database"
cf schema d1 create
```
帮助：向命令组添加 --help，例如 cf d1 --help，以列出其命令和选项。
编码 Agent：向 Agent 询问 Wrangler 命令对应的 cf 等效项。要设置 Agent，请参阅将 cf 用于编码 Agent。

cf 中的资源命令使用 Cloudflare API 期望的标识符，例如 D1 数据库 ID 而不是名称。它们作用于远程资源。--local 仅适用于本地开发提供的少数资源，例如 KV 键、通过 cf d1 raw、cf d1 migrations list 和 cf d1 migrations apply 操作的 D1，以及 R2 对象。完整列表请参阅本地资源数据。没有本地等效项的命令（例如 cf d1 query）会返回错误。

尚不支持的命令

cf 处于 Beta 阶段，部分 Wrangler 命令尚不支持。请用 npx wrangler 运行它们，而不是安装 Wrangler。Wrangler 不会读取 cloudflare.config.ts，因此请传入 Worker 名称。

wrangler tail：cf 尚不能流式传输实时日志。请运行：
```
npx wrangler tail <WORKER_NAME>
```
wrangler secret put：cf 尚不能设置单个 secret。请运行 npx wrangler secret put <SECRET_NAME> --name <WORKER_NAME>，或通过向 cf deploy 或 cf workers versions create 传入 --secrets-file <PATH>，随新的 Worker Version 上传 secrets。

配置字段

cf migrate 按以下表格转换 Wrangler 字段。Worker 设置位于 cloudflare.config.ts 的 worker 下，绑定位于 worker.env 下。必需项是需要你手动解决的后续事项，如解决后续事项所述。

Wrangler 字段	`cloudflare.config.ts`	说明
`name`	`worker.name`	—
`main`	`worker.entrypoint`	写成字符串路径。可以用 `cf-worker` 导入替换。
`compatibility_date`	`worker.compatibilityDate`	—
`compatibility_flags`	`worker.compatibilityFlags`	—
`account_id`	`accountId`	顶层
`compliance_region`	`complianceRegion`	顶层。`fedramp_high` 变为 `fedramp-high`。
`vars`	`bindings.text()` 或 `bindings.json()`	字符串使用 `text()`。其他值使用 `json()`。
`secrets.required`	`bindings.secret()`	—
KV、D1、R2、Hyperdrive 和其他绑定	对应的 `bindings` 构建器	预览资源字段是必需项。
`services`	`bindings.worker({ worker })`	旧版 service environment 是必需项。
`queues.producers`	`bindings.queue({ name })`	—
`queues.consumers`	`triggers.queue({ name })`	consumer 设置变为 camelCase 选项，例如 `maxBatchSize`。
Hyperdrive `localConnectionString`	`bindings.hyperdrive()` 上的 `dev: { connectionString }`	—
绑定上的 `remote: true`	`dev: { remote: true }`	—
带 `zone_name` 的 `routes`	`triggers.fetch({ pattern, zone })`	—
带 `zone_id` 的 `routes`	`triggers.fetch({ pattern, zone })`	必需项。`zone` 接受 zone 名称或 zone ID。
带 `custom_domain: true` 的 `routes`	`worker.domains`	—
`triggers.crons`	`triggers.scheduled({ schedule })`	—
`durable_objects.bindings`	`bindings.durableObject({ worker, exportName })`	必需项。请审查每个绑定。
`migrations`	`worker.exports`	不会转换。请参阅转换 Durable Object 迁移。
`workflows`	`bindings.workflow()` 和 `exports.workflow()`	必需项。请参阅 Workflows。
`containers`	顶层 `containers` 中的 `defineContainer()`	必需项。请参阅 Containers。
`assets.binding`	`bindings.assets()`	—
`assets.html_handling`、`not_found_handling`、`run_worker_first`	`worker.assets`	键变为 camelCase，例如 `notFoundHandling`。
`assets.directory`	构建设置	请参阅构建设置。
`observability`	`worker.observability`	键变为 camelCase，例如 `headSamplingRate`。
`limits`	`worker.limits`	键变为 camelCase，例如 `cpuMs`。
`placement`	`worker.placement`	—
`tail_consumers`	`worker.tailConsumers`	—
`streaming_tail_consumers`	`worker.tailConsumers`	每个条目获得 `streaming: true`。
`workers_dev`	`worker.workersDev`	—
`preview_urls`	`worker.previewUrls`	—
`env.<NAME>`	`switch (ctx.mode)` 中的 `case`	请参阅将环境转换为模式。
`previews`	`ctx.isPreview` 上的分支	必需项。请审查该分支。
`site`	—	不支持。将站点迁移到 Workers Static Assets。
D1 的 `migrations_dir`、`migrations_pattern`、`migrations_table`	—	向 `cf d1 migrations apply` 传入 `--dir`、`--pattern` 和 `--table`。
`build`、`minify`、`alias` 以及其他构建字段	构建设置	请参阅构建设置。

每个字段和构建器请参阅编程式配置和配置浏览器。

构建设置

构建设置不放在 cloudflare.config.ts 中。它们的位置取决于打包器：

Wrangler 字段	Vite 打包器：`vite.config.ts`	Wrangler 打包器：`wrangler.config.ts`
`alias`	`resolve.alias`	`alias`
`define`	`define`	`define`
`minify`	`build.minify`	`minify`
`upload_source_maps`	Worker 的 Vite 环境中的 `build.sourcemap`	`uploadSourceMaps`
`assets.directory`	`publicDir`	`assetsDirectory`
`build`	在 `cf build` 之前自行运行该命令	`build`，使用 camelCase 键
`dev`	`server` 选项	`dev`，使用 camelCase 键
`rules`、`tsconfig`、`no_bundle`、`find_additional_modules`、`base_dir`、`preserve_file_names`	不使用。Vite 处理模块解析和打包。	camelCase 键，例如 `noBundle` 和 `baseDir`

使用 Wrangler 打包器时，cf migrate 会替你将这些设置写入 wrangler.config.ts，并添加 types: { generate: false }。使用 Vite 打包器时，它会在必需项中列出这些字段供你迁移。wrangler.config.ts 是实验性的，在 Beta 期间可能变化。

将环境转换为模式

Wrangler 环境会继承部分顶层字段。cloudflare.config.ts 不会合并环境。它改为为每个模式返回一份完整配置。cf migrate 会写入带有每个环境一个 case 的 switch (ctx.mode) 语句。生成的形状请参阅环境。

在项目命令上将 --env <NAME> 替换为 --mode <NAME>，例如 cf dev、cf build、cf deploy、cf workers versions create 和 cf workers triggers deploy。

不带 --mode 时，模式取决于命令和打包器：

命令	Vite 打包器	Wrangler 打包器
`cf dev`	`development`	`undefined`
`cf build` 和 `cf deploy`	`production`	`undefined`
API 命令，例如 `cf d1 list`	`undefined`	`undefined`

API 命令仅求值 cloudflare.config.ts 以读取 accountId 和 complianceRegion。如果 accountId 取决于模式，Vite 构建和 API 命令可能解析出不同账户。请保持 accountId 与模式无关，或向每条命令传入相同的 --mode。

更多信息请参阅模式。

转换 Durable Object 迁移

worker.exports 替代有序的 migrations 历史。cf migrate 不会转换它。

在首次从 migrations 切换到 worker.exports 的部署上，声明现在仍存活的每个类的命名空间。使用 storage: "sqlite" 或 storage: "legacy-kv" 以匹配其现有存储。

不要复制完整迁移历史。省略已经应用的重命名和删除操作。如果添加它们，它们会成为过期墓碑，部署会报告可以安全移除。

仅为尚未应用的生命周期变更添加墓碑：

cloudflare.config.ts

import { defineConfig, exports } from "cf/config";

import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };

export default defineConfig({

defineConfigFunctionLink to defineConfig

defineConfig<T extends ConfigInput<CloudflareConfig>>(config: T): T;

Defines the default export of cloudflare.config.ts. Pass a configuration object, a promise that resolves to one, or a function that receives the config context (isPreview and mode) and returns either.

Options (4)

accountId?: string: This is the ID of the account associated with your zone. It can also be specified through the CLOUDFLARE_ACCOUNT_ID environment variable.
complianceRegion?: "public" | "fedramp-high": The compliance boundary in which commands should operate. When omitted, this can be supplied through CLOUDFLARE_COMPLIANCE_REGION.
worker?: ConfigInput<WorkerConfig>: The Worker defined by this configuration.
containers?: ConfigInput<ContainerConfig>[]: Container applications defined by this configuration.

worker: {

workerOptionalLink to worker

worker?: ConfigInput<WorkerConfig>

The Worker defined by this configuration.

nameRequiredLink to name

name: string

The name of your Worker.

entrypoint,

entrypointOptionalLink to entrypoint

entrypoint?: string | WorkerModule

The entrypoint module that will be executed. May be either a path string (e.g. "./src/index.ts") or a module namespace imported with the cf-worker import attribute.

compatibilityDate: "2026-08-24",

compatibilityDateRequiredLink to compatibilityDate

compatibilityDate: string

A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used. More details at https://developers.cloudflare.com/workers/configuration/compatibility-dates

exports: {

exportsOptionalLink to exports

exports?: Record<string, Export>

Configuration for named exports declared by the Worker. Each entry's key is the exported class name; the value configures the export. - Construct entries with exports.durableObject(...). - Declares Durable Object classes exported from this Worker. For more information about Durable Objects, see the documentation at https://developers.cloudflare.com/workers/learning/using-durable-objects. For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#durable-objects. - Construct entries with exports.workflow(...). - Declares Workflows defined by this Worker. For more information about Workflows, see the documentation at https://developers.cloudflare.com/workflows/.

Counter: exports.durableObject({ storage: "sqlite" }),

durableObjectBuilderLink to durableObject

durableObject<TContainer extends ContainerDefinition | undefined = undefined>(options: DurableObjectCreatedExportOptions<TContainer>): DurableObjectCreatedExport<TContainer>;

Declares a Durable Object class defined by this Worker. For more information about Durable Objects, see the documentation at https://developers.cloudflare.com/workers/learning/using-durable-objects For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#durable-objects

Options (4)

state?: "created"
storage: "sqlite": Selects the SQLite-backed storage engine (recommended for new classes).
container?: TContainer: Attach a Container application to this Durable Object by config reference.
storage: "legacy-kv": Selects the legacy key-value storage engine.

storageRequiredLink to storage

storage: "sqlite" | "legacy-kv"

Selects the SQLite-backed storage engine (recommended for new classes). Selects the legacy key-value storage engine.

OldCounter: exports.durableObject({

durableObjectBuilderLink to durableObject

durableObject(options: DurableObjectRenamedExportOptions): DurableObjectRenamedExport;

Rename a provisioned Durable Object namespace's class.

Options (2)

state: "renamed"
renamedTo: string: The destination class name. Must be a valid JavaScript identifier and must appear as a live (state: "created") durableObject entry in the same exports map.

state: "renamed",

stateRequiredLink to state

state: "renamed"

The type definition does not include a description.

renamedTo: "Counter",

renamedToRequiredLink to renamedTo

renamedTo: string

The destination class name. Must be a valid JavaScript identifier and must appear as a live (state: "created") durableObject entry in the same exports map.

}),

UnusedCounter: exports.durableObject({ state: "deleted" }),

durableObjectBuilderLink to durableObject

durableObject(options: DurableObjectDeletedExportOptions): DurableObjectDeletedExport;

Retire a provisioned Durable Object namespace whose class has been removed from code.

Options (1)

state: "deleted"

stateRequiredLink to state

state: "deleted"

The type definition does not include a description.

});

.ace-bar { display: none !important; } .ace-panel[hidden] { display: block !important; content-visibility: visible !important; } .ace-panel-heading { display: block !important; }

将墓碑保留到部署响应报告它已过期，然后再移除。对创建、删除、重命名或转移 Durable Object 类的版本使用 cf deploy，而不是版本上传。你无法将 Durable Object 生命周期变更回滚到变更之前的版本。

有关 Worker 之间的转移以及完整状态列表，请参阅管理 Durable Object 生命周期。

完整示例

此示例完成 orders-api 的迁移，即迁移 Wrangler 项目中使用的 Worker。它包含 D1 数据库、队列、cron 触发器、路由和 Durable Object。在 cf migrate 和后续步骤之后，cloudflare.config.ts 为：

cloudflare.config.ts

import { bindings, defineConfig, exports, triggers } from "cf/config";

import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };

type Job = { orderId: string };

export default defineConfig({

defineConfigFunctionLink to defineConfig

defineConfig<T extends ConfigInput<CloudflareConfig>>(config: T): T;

Options (4)

accountId?: string: This is the ID of the account associated with your zone. It can also be specified through the CLOUDFLARE_ACCOUNT_ID environment variable.
complianceRegion?: "public" | "fedramp-high": The compliance boundary in which commands should operate. When omitted, this can be supplied through CLOUDFLARE_COMPLIANCE_REGION.
worker?: ConfigInput<WorkerConfig>: The Worker defined by this configuration.
containers?: ConfigInput<ContainerConfig>[]: Container applications defined by this configuration.

accountId: "<ACCOUNT_ID>",

accountIdOptionalLink to accountId

accountId?: string

This is the ID of the account associated with your zone. It can also be specified through the CLOUDFLARE_ACCOUNT_ID environment variable.

worker: {

workerOptionalLink to worker

worker?: ConfigInput<WorkerConfig>

The Worker defined by this configuration.

nameRequiredLink to name

name: string

The name of your Worker.

entrypoint,

entrypointOptionalLink to entrypoint

entrypoint?: string | WorkerModule

The entrypoint module that will be executed. May be either a path string (e.g. "./src/index.ts") or a module namespace imported with the cf-worker import attribute.

compatibilityDate: "2026-08-24",

compatibilityDateRequiredLink to compatibilityDate

compatibilityDate: string

compatibilityFlags: ["nodejs_compat"],

compatibilityFlagsOptionalLink to compatibilityFlags

compatibilityFlags?: string[]

A list of flags that enable features from upcoming features of the Workers runtime, usually used together with compatibilityDate. More details at https://developers.cloudflare.com/workers/configuration/compatibility-flags/

Default: []

env: {

envOptionalLink to env

env?: Record<string, Binding>

Bindings exposed on the Worker's env object. Construct entries with bindings.kv(...), bindings.r2(...), etc.

ENVIRONMENT: bindings.text("production"),

textBuilderLink to text

text<T$1 extends string>(value: T$1): TextBinding<T$1>;

Inline string value made available to the Worker on env under the binding name. For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#environment-variables

DB: bindings.d1({

d1BuilderLink to d1

d1(options?: D1BindingOptions): D1Binding;

Binding to a D1 database. For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#d1-databases

Options (3)

id?: string: The UUID of this D1 database (not required).
name?: string: The name of this D1 database.
dev?: BindingDevOptions: Options that only apply during local development.

nameOptionalLink to name

name?: string

The name of this D1 database.

id: "<DATABASE_ID>",

idOptionalLink to id

id?: string

The UUID of this D1 database (not required).

}),

JOBS: bindings.queue<Job>({ name: "orders-jobs" }),

queueBuilderLink to queue

queue<TBody = unknown>(options?: QueueBindingOptions): TypedQueueBinding<TBody>;

Producer binding to a Cloudflare Queue. For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#queues

Options (3)

name?: string: The name of this Queue.
deliveryDelay?: number: The number of seconds to wait before delivering a message.
dev?: BindingDevOptions: Options that only apply during local development.

nameOptionalLink to name

name?: string

The name of this Queue.

COUNTERS: bindings.durableObject({

durableObjectBuilderLink to durableObject

durableObject<TWorker$1 extends WorkerReference, TExportName$1 extends DurableObjectExportName<TWorker$1>>(options: DurableObjectBindingOptions<TWorker$1, TExportName$1>): DurableObjectBinding<TWorker$1, TExportName$1>;

Binding to a Durable Object class. worker is the name or config of the Worker that defines the class; exportName is the exported class name. For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#durable-objects

Options (2)

worker: TWorker$1: The name or config of the Worker that defines the Durable Object class.
exportName: TExportName$1: The exported class name of the Durable Object.

worker: "orders-api",

workerRequiredLink to worker

worker: TWorker$1

The name or config of the Worker that defines the Durable Object class.

exportName: "Counter",

exportNameRequiredLink to exportName

exportName: TExportName$1

The exported class name of the Durable Object.

}),

exports: {

exportsOptionalLink to exports

exports?: Record<string, Export>

Counter: exports.durableObject({ storage: "sqlite" }),

durableObjectBuilderLink to durableObject

durableObject<TContainer extends ContainerDefinition | undefined = undefined>(options: DurableObjectCreatedExportOptions<TContainer>): DurableObjectCreatedExport<TContainer>;

Options (4)

state?: "created"
storage: "sqlite": Selects the SQLite-backed storage engine (recommended for new classes).
container?: TContainer: Attach a Container application to this Durable Object by config reference.
storage: "legacy-kv": Selects the legacy key-value storage engine.

storageRequiredLink to storage

storage: "sqlite" | "legacy-kv"

Selects the SQLite-backed storage engine (recommended for new classes). Selects the legacy key-value storage engine.

triggers: [

triggersOptionalLink to triggers

triggers?: Trigger[]

Event triggers — fetch routes, queue consumers, cron schedules, Email Routing addresses, and raw sockets — that invoke this Worker. Construct entries with triggers.fetch(...), triggers.queue(...), triggers.scheduled(...), triggers.email(...), or triggers.connect(...). For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#triggers

triggers.fetch({

fetchBuilderLink to fetch

fetch(options: FetchTriggerOptions): FetchTrigger;

Fetch trigger — a route that your Worker should be published to. For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#types-of-routes

Options (2)

pattern: string: A route that your Worker should be published to. For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#types-of-routes
zone?: string: The DNS zone the pattern is attached to. Required when the pattern is ambiguous.

pattern: "api.example.com/*",

patternRequiredLink to pattern

pattern: string

A route that your Worker should be published to. For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#types-of-routes

zone: "example.com",

zoneOptionalLink to zone

zone?: string

The DNS zone the pattern is attached to. Required when the pattern is ambiguous.

}),

triggers.queue({ name: "orders-jobs", maxBatchSize: 10 }),

queueBuilderLink to queue

queue(options: QueueConsumerTriggerOptions): QueueConsumerTrigger;

Queue consumer trigger — invokes this Worker when messages arrive on the named queue. For reference, see https://developers.cloudflare.com/workers/wrangler/configuration/#queues

Options (8)

name: string: The name of the queue from which this consumer should consume.
deadLetterQueue?: string: The queue to send messages that failed to be consumed.
maxBatchSize?: number: The maximum number of messages per batch.
maxBatchTimeout?: number: The maximum number of seconds to wait to fill a batch with messages.
maxConcurrency?: number | null: The maximum number of concurrent consumer Worker invocations. Leaving this unset will allow your consumer to scale to the maximum concurrency needed to keep up with the message backlog.
maxRetries?: number: The maximum number of retries for each message.
retryDelay?: number: The number of seconds to wait before retrying a message.
visibilityTimeoutMs?: number: The number of milliseconds to wait for pulled messages to become visible again.

nameRequiredLink to name

name: string

The name of the queue from which this consumer should consume.

maxBatchSizeOptionalLink to maxBatchSize

maxBatchSize?: number

The maximum number of messages per batch.

triggers.scheduled({ schedule: "0 * * * *" }),

scheduledBuilderLink to scheduled

scheduled(options: ScheduledTriggerOptions): ScheduledTrigger;

Scheduled (cron) trigger — invokes this Worker on the given schedules. More details here https://developers.cloudflare.com/workers/platform/cron-triggers

Options (1)

schedule: string: A "cron" definition to trigger a Worker's "scheduled" function. Lets you call Workers periodically, much like a cron job. More details here https://developers.cloudflare.com/workers/platform/cron-triggers

scheduleRequiredLink to schedule

schedule: string

A "cron" definition to trigger a Worker's "scheduled" function. Lets you call Workers periodically, much like a cron job. More details here https://developers.cloudflare.com/workers/platform/cron-triggers

});

.ace-bar { display: none !important; } .ace-panel[hidden] { display: block !important; content-visibility: visible !important; } .ace-panel-heading { display: block !important; }

与 cf migrate 生成的文件相比，完成后的文件：

使用带 cf-worker 属性的导入替代字符串路径引入入口，因此 Worker 模块导出带有类型。
在 exports 下声明 Counter 类，替代 migrations 历史。
使用 bindings.queue<Job>() 为队列消息添加类型。
没有 TODO(@cloudflare) 注释或 throw 语句。

要查看生成的文件，请参阅阅读输出。