Tao
所有文章 标签 分类 系列 关于 联系
Tao

目录

Cloudflare Wrangler 权威指南：从本地开发到全球部署

Mttao avatarMttao  收录于  类别 Cloudflare
     约 12805 字  预计阅读 26 分钟 
目录

Cloudflare Wrangler 是为在 Cloudflare 开发者平台上进行构建、管理和部署应用程序而设计的官方命令行界面（CLI）工具。它充当开发者本地开发环境与 Cloudflare 全球网络之间的主要桥梁，使其能够无缝地与 Cloudflare 的无服务器产品进行交互作为更广泛的 Cloudflare Workers SDK 的一部分，Wrangler 与 create-cloudflare（C3）项目脚手架工具和 Miniflare 本地模拟器协同工作，共同构成了一个完整且高效的开发工具链。

Wrangler 不仅仅是一个部署工具，它已经演变为一个全面的平台命令行工具。最初，它专注于 Cloudflare Workers 的管理，但随着 Cloudflare 开发者平台的扩展，Wrangler 的能力也随之增强。现在，它能够管理包括 Cloudflare Pages、D1 数据库、R2 对象存储、Workers KV 键值存储、Queues 消息队列、Hyperdrive 数据库加速器和 Vectorize 向量数据库在内的全套无服务器产品。

这种演变反映Cloudflare 的战略方向——提供一个集成的、全栈的无服务器开发体验。开发者通过掌握 Wrangler，实际上是在学习如何驾驭整个 Cloudflare 生态系统，这使得 Wrangler 成为在 Cloudflare 平台上构建任何应用程序的核心入口点。

Wrangler 在 Cloudflare 的无服务器生态系统中扮演着至关重要的角色，它支持构建从简单的 Worker 脚本和静态网站到复杂的全栈应用程序和 API 的各类应用。该工具的多语言支持能力，包括对 JavaScript、TypeScript、Python 和 Rust 的支持，进一步凸显了 Cloudflare 平台的灵活性和广泛适用性。

Wrangler 的设计理念是提供一个统一的命令行体验，以管理应用程序的整个生命周期。开发者可以使用它来初始化项目、在本地进行开发和测试、配置和绑定云资源，并最终将应用程序部署到 Cloudflare 的全球网络。这种统一的工具链简化了开发流程，减少了在不同工具之间切换的认知负担，从而提高了开发效率。无论是部署一个静态前端应用，还是构建一个连接到多个数据存储的复杂后端 API，Wrangler 都提供了必要的命令和配置选项来完成任务。

要有效使用 Wrangler，理解其背后的几个核心概念至关重要。这些概念构成了 Cloudflare 无服务器平台的基础，并深刻影响着 Wrangler 的设计和功能。

边缘计算是 Cloudflare Workers 的核心价值主张。与传统的集中式云模型不同，边缘计算将代码部署在 Cloudflare 遍布全球的数据中心网络上，使其在物理上更接近最终用户。当用户发起请求时，该请求会被路由到最近的边缘节点进行处理，而不是传输到遥远的中心服务器。这种架构显著降低了网络延迟，从而提升了应用程序的响应速度和用户体验。Wrangler 的 deploy 命令正是将开发者的代码分发到这个全球边缘网络的执行者。

绑定是连接 Worker 与其他 Cloudflare 资源的关键机制。在技术上，绑定是一个在 Worker 运行时环境中可用的变量，通常通过 env 对象访问。这个变量提供了一个编程接口，允许 Worker 与 KV 命名空间、D1 数据库、R2 存储桶，甚至是其他 Worker 服务进行交互。例如，通过将一个 D1 数据库绑定到名为 DB 的变量上，开发者就可以在代码中使用 env.DB.prepare(...).run() 来执行 SQL 查询。绑定的概念是构建功能丰富的复杂应用的基础，它将计算（Worker）与状态（存储、数据库等）解耦，并通过 Wrangler 的配置文件进行声明式管理。

Cloudflare Workers 运行在一个名为 workerd 的高性能 JavaScript/WebAssembly 运行时之上。与许多其他无服务器平台使用的容器（Container）不同，workerd 基于 V8 Isolates 技术。Isolate 是一种轻量级的执行上下文，它提供了内存隔离，但避免了启动一个完整操作系统的开销。这种架构使得 Workers 能够实现接近于零的冷启动时间，因为启动一个新的 Isolate 远比启动一个容器要快得多。workerd 已经开源，并且它不仅为生产环境提供动力，也为 Wrangler 的本地开发环境提供了支持，从而确保了开发与生产环境的高度一致性。

在开始使用 Wrangler 之前，必须确保开发环境满足一些基本要求。首先，需要一个 Cloudflare 账户，这是部署和管理任何 Cloudflare 服务的必要条件。其次，本地系统必须安装 Node.js 和其包管理器 npm。Wrangler 支持 Node.js 的当前版（Current）、活跃版（Active）和维护版（Maintenance）。许多教程和功能明确要求 Node.js 版本不低于 16.17.0 11。

为了避免在全局安装 npm 包时可能出现的权限问题，并能够方便地在不同 Node.js 版本之间切换，官方强烈建议使用 Node 版本管理器，如 nvm 或 Volta 4。最后，Wrangler 本身对操作系统也有要求，这与 workerd 运行时的支持策略保持一致：支持 macOS 13.5+、Windows 11 以及支持 glib 2.35 的 Linux 发行版 17。

安装 Wrangler 有多种方法，选择哪种方法取决于项目需求和个人偏好。近年来，最佳实践已经从全局安装转向了项目本地安装。

Cloudflare 官方文档推荐将 Wrangler 作为每个项目的本地开发依赖项进行安装。这样做的好处是显而易见的：它确保了团队中的所有成员都使用完全相同的 Wrangler 版本，从而避免了因版本不一致而导致的潜在问题。这也使得项目的构建过程更具可预测性和可复现性，并且允许在需要时将特定项目回滚到较早的 Wrangler版本。

  • 使用 npm: npm i -D wrangler@latest
  • 使用 yarn: yarn add -D wrangler@latest
  • 使用 pnpm: pnpm add -D wrangler@latest

这种从全局安装到本地安装的转变，反映了 JavaScript 生态系统的成熟以及 Wrangler 作为一个关键开发工具角色的演进。它不再被视为一个简单的、独立的系统级工具，而是项目构建和部署工具链中一个不可或缺的、需要进行版本控制的部分。这种做法与 ESLint、Prettier 等其他现代开发工具的最佳实践一致，旨在从根本上解决"在我的机器上可以运行"这一经典难题。

许多较早的教程和第三方指南中常见的是全局安装方法：npm install -g wrangler。全局安装的便利之处在于可以在系统的任何目录下直接运行 wrangler 命令。然而，这种方式可能会导致不同项目之间因依赖的 Wrangler 版本不同而产生冲突。尽管全局安装仍然可用，但本地安装已成为现代 Web 开发的更优选择。

对于 macOS 用户，可以通过 Homebrew 进行安装：brew install cloudflare-wrangler。对于 Rust 开发者或在某些 ARM 架构的系统（npm 安装程序可能无法正常工作）上，也可以使用 cargo 进行安装：cargo install wrangler。

安装完成后，下一步是授权 Wrangler 访问您的 Cloudflare 账户。wrangler login 是完成此任务的主要命令。该命令会启动一个标准的 OAuth 2.0 授权流程。执行后，它会自动打开默认的网页浏览器，并导航到 Cloudflare 的登录和授权页面。在页面上登录并批准 Wrangler 的访问请求后，Cloudflare 会生成一个 OAuth 令牌，Wrangler 会安全地存储这个令牌，用于后续代表用户执行管理操作。

对于没有图形界面的环境，如 SSH 连接的远程服务器，wrangler login 会在终端中显示一个 URL。开发者可以将此 URL 复制到任何有浏览器的设备上打开，完成授权流程后，CLI 将会自动获取认证。

为了验证身份验证是否成功，可以运行 wrangler whoami 命令。该命令会显示当前登录的 Cloudflare 用户信息以及关联的账户 ID，这是一个很好的检查步骤。

在持续集成/持续部署（CI/CD）等自动化环境中，交互式登录是不现实的。在这种情况下，首选的认证方式是使用 Cloudflare API 令牌，并通过 CLOUDFLARE_API_TOKEN 环境变量提供给 Wrangler。虽然 wrangler config 命令也支持使用 API 令牌进行配置，但通过环境变量传递更为灵活和安全，是自动化工作流的标准实践。

开始一个新项目的最标准、最推荐的方式是使用 create-cloudflare (C3) 命令行工具。只需在终端中运行以下命令：

bash

npm create cloudflare@latest

C3 会引导用户完成一个交互式的设置过程。它会询问项目名称、要使用的模板（例如，“Hello World” Worker、静态网站或全栈应用）、开发语言（JavaScript 或 TypeScript），以及是否要初始化一个 Git 仓库。完成这些步骤后，C3 会自动创建一个包含所有必要文件和配置的新项目目录，并默认将 Wrangler 安装为项目的本地开发依赖项。

作为 C3 的替代方案，wrangler init 命令可以在一个已经存在的目录中创建一个骨架 wrangler.toml 配置文件。如果您倾向于手动克隆一个 Git 仓库或从一个现有项目开始，这个命令会非常有用。

一个由 C3 生成的标准 Wrangler 项目包含了一组结构清晰的文件和目录，这些文件共同定义了项目的行为和依赖。

  • wrangler.jsonc (或 wrangler.toml): 这是项目的核心配置文件，也是 Wrangler 的"事实来源"。它定义了 Worker 的名称、主入口文件、兼容性日期、路由规则以及与 D1、R2、KV 等其他 Cloudflare 资源的绑定关系。
  • src/index.ts (或 .js): 这是 Worker 的源代码入口文件。所有业务逻辑都从这里开始。该文件必须导出一个包含 fetch 处理程序的默认对象，以响应传入的 HTTP 请求。
  • package.json: 这是标准的 Node.js 项目清单文件。它记录了项目的元数据（如名称、版本）、依赖项（如 Hono 框架或数据库客户端）以及一系列可执行的脚本命令（如 dev 用于启动本地服务器，deploy 用于发布到 Cloudflare）。
  • node_modules/ 和 package-lock.json: 这些是 Node.js 生态系统的标准组成部分，分别用于存放已安装的依赖包和锁定依赖版本，以确保环境的一致性。
  • public/ 或 dist/ 目录: 对于包含静态资产的项目（如全栈应用或静态网站），通常会有一个目录用于存放 HTML、CSS、JavaScript 和图片等文件。Wrangler 会在部署时将此目录的内容上传。

C3 生成的默认模板提供了一个极简但功能完备的 Worker 脚本，这是理解 Worker 运行模式的最佳起点。

javascript

export default {
  async fetch(request, env, ctx) {
    return new Response("Hello World!");
  },
};

这段代码的结构和行为刻意模仿了 Web 平台的标准 Service Worker API。这种设计选择极大地降低了前端和 Web 开发人员进入后端开发的门槛，因为它允许他们利用现有的 Web 标准知识来构建服务器端逻辑。

  • export default {… }: 这是定义 Worker 的标准 ES 模块语法。Worker 的入口必须是一个默认导出的对象。
  • async fetch(request, env, ctx): 这是处理 HTTP 请求的核心事件处理程序。每当有请求到达分配给此 Worker 的路由时，Cloudflare 运行时就会调用这个函数。
    • request: 一个标准的 Request 对象，包含了所有关于入站 HTTP 请求的信息，如 URL、方法、头部和正文。
    • env: 一个至关重要的对象，它包含了 Worker 的所有绑定。环境变量、Secrets、以及到 KV、D1、R2 等服务的连接句柄都通过 env 对象提供给代码。
    • ctx: 执行上下文对象，提供了一些高级功能，最常用的是 ctx.waitUntil()。该方法允许您在已将响应发送回客户端后，继续执行一些异步任务（如写入日志或分析数据），而不会阻塞响应。
  • return new Response(“Hello World!”): fetch 处理程序必须返回一个标准的 Response 对象。这个对象代表了将要发送回客户端的 HTTP 响应，包括状态码、头部和正文。

这种基于 Web 标准 API 的设计并非偶然，而是 Cloudflare 的一项战略决策。它没有像其他一些无服务器平台那样创造一套专有的、平台特定的 API，而是选择了拥抱开放的 Web 标准。这意味着，任何熟悉现代 Web 开发，特别是使用过 Service Worker 来实现 PWA 或离线功能的开发者，都可以几乎无缝地过渡到 Cloudflare Workers 的开发中，从而大大缩短了学习曲线，使平台更具吸引力。

wrangler dev 是 Wrangler CLI 中最核心的命令之一，它能启动一个本地开发服务器，让开发者在部署到生产环境之前，能够在本地快速迭代和测试他们的 Worker。

在早期版本中，wrangler dev 通过将本地请求代理到 Cloudflare 的边缘网络来工作。这种模式虽然能保证与生产环境的高度一致性，但网络延迟也导致了较慢的开发体验。为了解决这个问题，社区开发了 Miniflare，一个纯本地的 Worker 模拟器，因其极速的反馈循环而广受欢迎。

最终，Cloudflare 正式采纳了 Miniflare，并将其深度集成到 Wrangler 中。从 Wrangler v3 开始，“本地优先"成为了 wrangler dev 的默认模式。更重要的是，这个本地服务器现在由 workerd 驱动——这与 Cloudflare 在全球生产环境中运行 Workers 的开源 C++ 运行时完全相同。这一变化带来了革命性的提升：开发者现在拥有了一个与生产环境几乎完全一致的本地模拟环境，从而最大限度地减少了"本地正常，线上异常"这类问题的发生。

在运行 wrangler dev 时，所有在 wrangler.jsonc 中定义的绑定（如 KV、R2、D1 和 Queues）都会默认连接到本地的、基于内存或文件的模拟实现。这使得开发者可以免费、快速地进行开发和测试，而无需消耗任何生产资源。本地数据默认会在 wrangler dev 会话之间持久化，也可以使用 --persist-to 标志指定一个持久化目录。

现代 wrangler dev 提供了一套丰富的工具，旨在优化开发者的"内循环”（即编码、运行、调试的循环过程）。

  • 实时重载 (Live Reloading): 当您保存代码文件的任何更改时，本地开发服务器会自动重新加载您的 Worker，无需手动重启。这种即时反馈极大地提高了开发效率。
  • DevTools 集成: 在运行 wrangler dev 的终端中按下 d 键，Wrangler 会为您打开一个连接到本地 Worker 的 Chrome DevTools 实例。通过这个熟悉的界面，您可以检查网络请求、查看 console.log 输出、分析 CPU 和内存使用情况，以及进行交互式调试。
  • 断点调试: Wrangler 支持在 VS Code 和 WebStorm 等主流 IDE 中进行断点调试。这通常需要您在项目的 .vscode/launch.json 文件中创建一个简单的配置，以将 IDE 的调试器附加到 Wrangler 开发服务器暴露的检查器端口（默认为 9229）。配置完成后，您就可以在代码中设置断点，并在请求命中时暂停执行、检查变量和调用堆栈。

尽管本地模拟非常强大，但在某些情况下，开发者仍需要将本地运行的 Worker 代码连接到部署在 Cloudflare 上的真实资源（例如，一个包含生产数据的 D1 数据库或一个尚未在本地模拟器中支持的新服务）。Wrangler 提供了两种模式来支持这种混合开发。

  • 新方式 (experimental_remote): 这是推荐的远程开发方式。您可以在 wrangler.jsonc 文件中为单个绑定设置 "experimental_remote": true。这会创建一个混合开发环境：您的 Worker 代码仍在本地机器上执行，享受快速重载的好处，但对该特定绑定的 API 调用会被透明地代理到云端的真实资源。
  • 传统方式 (wrangler dev –remote): 这个旧的 --remote 标志仍然可用。它不会在本地运行 workerd，而是将您的代码部署到一个临时的预览 URL 上，然后通过隧道将本地请求转发到这个远程预览实例。这种模式的性能不如本地优先模式，但对于测试那些尚未被本地模拟器支持的边缘功能非常有用。

wrangler dev 的架构演进体现了 Cloudflare 对开发者体验的深刻理解和巨大投入。通过开源其核心运行时 workerd 并将其作为本地模拟器的基础，Cloudflare 成功地解决了无服务器开发中的一个核心痛点，即在开发速度和生产保真度之间取得平衡。这种提供与生产环境几乎完全一致的本地开发环境的能力，不仅建立了开发者的信心，也显著减少了因环境差异导致的错误，构成了 Cloudflare 平台一个强大的竞争优势。

Wrangler 使用一个配置文件来定制 Worker 的开发和部署设置。从 Wrangler v3 开始，支持 JSON (wrangler.jsonc) 和 TOML (wrangler.toml) 两种格式，其中 wrangler.jsonc 是新项目的推荐格式。

一个至关重要的最佳实践是将此配置文件视为 Worker 配置的唯一"事实来源"（Source of Truth）。这意味着所有配置，包括路由、环境变量和资源绑定，都应该在 wrangler.jsonc 文件中进行声明式管理。虽然可以在 Cloudflare 仪表板中进行更改，但下一次通过 wrangler deploy 进行的部署将会用文件中的配置覆盖这些更改，除非明确配置了 keep_vars = true 等特殊选项。这种做法确保了配置的版本可控、可审查，并避免了本地代码与云端状态之间的配置漂移。

一个可部署的 Worker 的最小配置需要三个核心参数：

  • name (string): Worker 脚本的名称。
  • main (string): 指向 Worker 入口点文件的路径，例如 "src/index.ts"。
  • compatibility_date (string): 一个 YYYY-MM-DD 格式的日期。这个参数至关重要，它将您的 Worker “钉"在特定版本的 workerd 运行时上。这可以防止 Cloudflare 运行时的未来更新（可能包含不兼容的更改）自动应用到您的 Worker，从而保证了应用的长期稳定性。
  • compatibility_flags (array): 一个字符串数组，允许您在不更改 compatibility_date 的情况下，选择性地启用新的、可能不向后兼容的运行时特性。

其他一些常用的顶级参数包括：

  • workers_dev (boolean): 控制是否将 Worker 部署到您的 *.workers.dev 子域。
  • routes 或 route: 定义 Worker 在您的自定义域上生效的 URL 模式。

Wrangler 强大的环境管理功能允许您在同一个 wrangler.jsonc 文件中为同一个应用程序定义多套配置，例如用于开发、预发（staging）和生产环境。环境在 env 键下定义。当您使用 --env 标志进行部署时（例如 wrangler deploy --env staging），Wrangler 会创建一个名为 <项目名>-<环境名> 的新 Worker（例如 my-worker-staging）。这使得您可以为每个环境配置不同的路由、环境变量和资源绑定，从而实现环境之间的完全隔离。

大多数顶级配置键（如 main, compatibility_date）会被环境继承。然而，一个关键的设计决策是，绑定（如 kv_namespaces, d1_databases, r2_buckets）和变量（vars）是不可继承的。这意味着，即使您在顶级配置中定义了数据库绑定，您仍必须在每个环境（如 env.staging）中显式地重新定义它。

这种非继承规则是一种刻意的安全设计。它通过强制开发者为每个环境明确指定其资源，来防止最常见的配置错误之一——在预发环境中意外地读写生产数据库。如果绑定是可继承的，开发者在添加一个新的预发环境时，很容易忘记覆盖生产数据库的绑定，这可能导致灾难性的数据污染。Wrangler 的配置模式通过让"安全的做法”（即为每个环境配置独立的资源）成为必须遵循的路径，充当了一个重要的安全护栏，体现了优秀开发者工具的设计原则：让做错事变得更难。

绑定是 Worker 与 Cloudflare 平台其他部分进行交互的粘合剂。它们在 wrangler.jsonc 中定义，并在 Worker 代码中通过 env 对象访问。以下是一些核心服务的绑定配置示例：

  • Workers KV: {"kv_namespaces": [...]}
  • D1 数据库: {"d1_databases": [...]}
  • R2 对象存储: {"r2_buckets": [...]}
  • 环境变量: {"vars": { "API_URL": "https://api.example.com" }}
  • Secrets: 出于安全考虑，敏感信息（如 API 密钥）不应直接写入 vars，而应通过 wrangler secret 命令进行管理（详见第 8 节）。

除了这些，Wrangler 还支持为 Queues、Durable Objects、Workers AI、Hyperdrive、Vectorize 等众多服务进行绑定，这进一步巩固了 Wrangler 作为平台级编排工具的地位。

配置块 目的 wrangler.jsonc 示例 wrangler.toml 示例
顶级键 定义 Worker 的基本属性 {"name": "my-worker", "main": "src/index.ts", "compatibility_date": "2024-01-01"} name = "my-worker" main = "src/index.ts" compatibility_date = "2024-01-01"
KV 命名空间绑定 将 KV 命名空间连接到 Worker {"kv_namespaces": [...]} [[kv_namespaces]] binding = "MY_KV" id = "..."
D1 数据库绑定 将 D1 数据库连接到 Worker {"d1_databases": [...]} [[d1_databases]] binding = "DB" database_name = "prod-db" database_id = "..."
R2 存储桶绑定 将 R2 存储桶连接到 Worker {"r2_buckets": [...]} [[r2_buckets]] binding = "ASSETS" bucket_name = "prod-assets"
环境定义 为不同部署阶段（如 staging）定义特定配置 {"env": {"staging": {"vars": {"ENVIRONMENT": "staging"}}}} [env.staging] vars = { ENVIRONMENT = "staging" }

Wrangler 不仅是一个开发和部署工具，还是一个强大的云资源管理器。它提供了一系列子命令，让开发者可以直接在终端中对 Cloudflare 的各种存储和数据服务进行 CRUD（创建、读取、更新、删除）操作。

服务 命令 描述 示例
KV kv:namespace create 创建一个新的 KV 命名空间 wrangler kv:namespace create MY_KV
kv:key put 写入一个键值对 wrangler kv:key put --namespace-id=... "my-key" "my-value"
kv:key get 读取一个键的值 wrangler kv:key get --namespace-id=... "my-key"
kv:key list 列出命名空间中的所有键 wrangler kv:key list --namespace-id=...
D1 d1 create 创建一个新的 D1 数据库 wrangler d1 create my-database
d1 execute 执行一条 SQL 命令或一个 SQL 文件 wrangler d1 execute my-database --command "SELECT * FROM users"
d1 migrations apply 应用所有待处理的数据库迁移 wrangler d1 migrations apply my-database
d1 list 列出账户中的所有 D1 数据库 wrangler d1 list
R2 r2 bucket create 创建一个新的 R2 存储桶 wrangler r2 bucket create my-bucket
r2 object put 上传一个文件到 R2 存储桶 wrangler r2 object put my-bucket/image.png --file=./image.png
r2 object get 从 R2 存储桶下载一个文件 wrangler r2 object get my-bucket/image.png --file=./download.png
r2 bucket list 列出账户中的所有 R2 存储桶 wrangler r2 bucket list
Queues queues create 创建一个新的消息队列 wrangler queues create my-queue
queues list 列出账户中的所有队列 wrangler queues list

Workers KV 是一个全球分布的键值存储，专为高读取、低延迟的场景设计。Wrangler 提供了一整套 kv 命令来管理它。

使用 wrangler kv:namespace create <BINDING_NAME> 来创建一个新的 KV 命名空间。该命令不仅会创建资源，还会直接输出需要添加到 wrangler.jsonc 文件中的配置代码段，非常方便。wrangler kv:namespace list 和 wrangler kv:namespace delete 分别用于列出和删除命名空间。

wrangler kv:key put 用于写入数据，可以直接提供值，也可以通过 --path 标志从文件中读取，这对于写入较大的值或二进制内容很有用。get、list 和 delete 命令则分别用于读取、列出和删除键值对。所有这些操作都需要通过 --namespace-id 标志指定要操作的命名空间。

对于需要处理大量数据的情况，wrangler kv:bulk 命令提供了高效的批量写入和删除功能，它通过读取一个特定格式的 JSON 文件来执行操作。

D1 是 Cloudflare 的原生无服务器 SQL 数据库，基于 SQLite 构建。Wrangler 的 d1 子命令是与 D1 交互的主要工具。

wrangler d1 create <DATABASE_NAME> 用于创建新数据库。list、delete 和 info 命令则用于基本的数据库生命周期管理。

wrangler d1 execute 是一个非常强大的命令，可以直接执行 SQL 查询（通过 --command）或从 SQL 文件执行（通过 --file），后者非常适合用于初始化数据库模式。通过 --local 和 --remote 标志，可以精确控制命令是作用于本地开发数据库还是已部署的远程数据库。

D1 拥有强大的、内置的迁移系统，完全通过 Wrangler 进行管理。wrangler d1 migrations create <DB_NAME> <MIGRATION_MESSAGE> 会在项目的 migrations 目录下创建一个新的、带有版本号的 SQL 文件，您可以在其中编写 DDL 语句（如 CREATE TABLE, ALTER TABLE）。wrangler d1 migrations apply <DB_NAME> 会检查所有尚未应用的迁移文件，并按顺序将它们应用到数据库中，从而以一种可控、可版本化的方式演进数据库模式。

R2 是 Cloudflare 提供的 S3 兼容的对象存储服务，其主要特点是零出口费用。Wrangler 的 r2 命令集提供了完整的管理能力。

与 KV 和 D1 类似，wrangler r2 bucket create、list 和 delete 用于存储桶的基本生命周期管理。

wrangler r2 object put 用于上传文件。它需要一个 bucket/key 格式的目标路径，并通过 --file 标志指定本地文件路径。wrangler r2 object get 和 delete 则分别用于下载和删除 R2 中的对象。

Cloudflare Queues 是一种消息队列服务，用于解耦应用程序组件和处理异步任务。wrangler queues create <QUEUE_NAME> 用于创建一个新的队列。wrangler queues consumer add <QUEUE_NAME> <SCRIPT_NAME> 是一个关键命令，它将一个 Worker 脚本指定为某个队列的消费者。这意味着每当有消息被发送到该队列时，Cloudflare 平台就会调用这个 Worker 来处理消息。

wrangler deploy 是将您的 Worker 应用程序从本地开发环境发布到 Cloudflare 全球边缘网络的核心命令。当执行此命令时，Wrangler 会执行一系列操作：它会根据 wrangler.jsonc 中的配置，构建并捆绑您的代码及其依赖项，然后将生成的脚本上传到 Cloudflare。同时，它还会应用所有在配置文件中声明的设置，如路由规则、环境变量和资源绑定，从而完成整个部署过程。

Wrangler 的环境功能与 deploy 命令紧密结合，实现了对不同部署阶段（如开发、预发、生产）的精细化控制。要部署到特定的环境，只需在命令后附加 --env (或 -e) 标志。例如，执行 wrangler deploy --env staging 会指示 Wrangler 读取 wrangler.jsonc 文件中 env.staging 部分的配置。这使得为预发环境部署一套完全独立的配置成为可能，包括使用不同的路由、连接到预发数据库，以及设置特定的环境变量。如果不提供 --env 标志，Wrangler 会默认使用配置文件中的顶级配置，这通常被约定为生产环境的配置。

Wrangler 的设计充分考虑了自动化需求，使其能够轻松地集成到任何持续集成/持续部署（CI/CD）流程中。Cloudflare 官方提供了 cloudflare/wrangler-action，这是一个专门为 GitHub Actions 设计的工具，也是实现自动化部署的推荐方式。

一个典型的 CI/CD 工作流如下：

  1. 触发: 在 .github/workflows/deploy.yml 文件中配置工作流，使其在代码被推送到特定分支（如 main 或 staging）时自动触发。
  2. 认证: 工作流使用存储在 GitHub Secrets 中的 CLOUDFLARE_API_TOKEN 来安全地认证 wrangler-action。
  3. 部署: wrangler-action 检出代码，并执行部署。可以通过向 action 传递 environment 参数来指定部署目标，这等同于在命令行中使用 --env 标志。
  4. Secrets 管理: 可以在 GitHub Actions 的工作流中安全地将 GitHub Secrets 传递给 Worker，wrangler-action 会负责使用 wrangler secret put 命令将它们上传。

Wrangler 的环境感知配置与一流的 CI/CD 集成相结合，共同构成了一个强大的 GitOps 工作流。在这种模式下，wrangler.jsonc 配置文件和 Git 分支成为基础设施的唯一事实来源。开发者通过提交代码和配置更改到 Git，自动触发一个可预测、可审计的部署流程。所有基础设施的变更都通过拉取请求（Pull Request）进行管理，这不仅提供了清晰的变更历史，还极大地减少了因手动操作导致部署错误的风险。

在任何应用程序中，安全地管理敏感信息（如 API 密钥、数据库密码和认证令牌）都至关重要。Wrangler 提供了一套强大的工具和工作流来应对这一挑战，其核心原则是在本地开发便利性与生产环境安全性之间取得平衡。

  • 核心原则: 绝对不要将任何敏感信息以明文形式存储在 wrangler.jsonc 的 vars 部分，也绝不能将其提交到版本控制系统（如 Git）中。
  • 生产环境 Secrets: 对于部署到 Cloudflare 的 Worker，应使用 wrangler secret put <SECRET_NAME> 命令来上传敏感数据。Wrangler 会将这些值进行加密存储，它们在 Worker 代码中可以通过 env 对象访问，但在创建后其值在仪表板或 CLI 中将不可见，从而保证了安全性。要为特定环境设置 secret，请使用 --env 标志，例如：wrangler secret put DB_PASSWORD --env production。
  • 本地开发 Secrets: 为了方便本地开发和测试，可以在项目根目录下创建一个名为 .dev.vars 的文件。在此文件中，以 KEY="VALUE" 的格式定义本地开发所需的 secrets 67。至关重要的是，必须将 .dev.vars 文件添加到 .gitignore 中，以防止其被意外提交。
  • 特定环境的本地 Secrets: 如果您的本地开发需要模拟不同的环境（例如，连接到不同的本地数据库），可以创建特定于环境的 secrets 文件，如 .dev.vars.staging。当您运行 wrangler dev --env staging 时，Wrangler 会优先加载这个文件中的变量。
  • Cloudflare Secrets Store: 对于需要在多个 Worker 之间共享的 secrets，Cloudflare 提供了 Secrets Store 服务。它支持在账户级别创建 secrets，并提供更精细的基于角色的访问控制（RBAC），适用于更复杂的企业级应用场景。

这种分层、环境感知的 secrets 管理方法体现了一个成熟的安全模型。它为开发生命周期的不同阶段提供了量身定制的解决方案，有效地防止了最常见的 secrets 泄露途径。

随着应用程序复杂度的增加，将其拆分为多个独立的、相互协作的 Worker 是一种常见的架构模式（例如，一个处理前端渲染，另一个提供后端 API）。Wrangler 完全支持这种多 Worker 的开发模式。通过向 wrangler dev 命令传递多个配置文件的路径，可以在单个本地开发会话中同时运行多个 Worker。

bash

npx wrangler dev -c ./frontend/wrangler.jsonc -c ./api/wrangler.jsonc

在这种模式下，Wrangler 会将第一个指定的配置文件视为主 Worker（通常监听在 localhost:8787），而将其他 Worker 作为辅助服务运行。这对于在本地环境中测试 Worker 之间的交互至关重要，例如通过服务绑定（Service Bindings）进行的直接 RPC 调用，或是测试一个 Worker 作为生产者向队列发送消息，而另一个 Worker 作为消费者进行处理的场景。

Wrangler 的能力不仅限于 Workers，它同样可以用于管理 Cloudflare Pages 项目中的后端逻辑，即 Pages Functions。wrangler pages dev <ASSET_DIRECTORY> 命令可以启动一个本地开发服务器，该服务器不仅能提供 Pages 项目的静态资源，还能运行 functions 目录下的所有函数，从而实现对全栈 Pages 应用的本地模拟。

Pages Functions 也可以通过 wrangler.jsonc 文件进行配置，但这与纯 Worker 项目的配置存在一些关键差异。例如，Pages 的配置文件必须包含一个 pages_build_output_dir 键来指定静态资源的构建输出目录，而 Worker 特有的 main 键则不适用。此外，环境的继承模型也与 Workers 有所不同。

对于已部署的应用程序，快速诊断生产环境中的问题至关重要。wrangler tail 命令为此提供了一个强大的解决方案。它可以在您的终端中实时流式传输来自已部署 Worker 的日志。这包括 Worker 代码中所有的 console.log 输出以及任何未捕获的异常。这对于调试生产环境中的突发问题是无价的，因为它提供了对 Worker 实时行为的直接洞察。tail 命令还支持多种过滤选项，允许您根据请求状态、IP 地址、HTTP 方法等条件来筛选日志流，帮助您在海量日志中快速定位到问题所在。

本节提供了一些最常用的 Wrangler 命令及其用法示例，以帮助您快速上手日常开发和管理任务。

wrangler init <NAME>: 使用 create-cloudflare-cli (C3) 工具创建一个新的 Worker 项目。

bash

# 创建一个名为 "my-worker" 的新项目
npx wrangler init my-worker

wrangler dev: 启动一个本地开发服务器，用于测试和调试您的 Worker。它支持实时重载和 DevTools 集成。

bash

# 在项目目录中启动本地服务器
npx wrangler dev

wrangler deploy: 将您的 Worker 部署到 Cloudflare 的全球网络。

bash

# 部署 Worker 到生产环境
npx wrangler deploy

# 部署到名为 "staging" 的特定环境
npx wrangler deploy --env staging

wrangler kv: 管理 Workers KV 命名空间和键值对。

bash

# 创建一个名为 "MY_KV" 的新 KV 命名空间
npx wrangler kv:namespace create "MY_KV"

# 将一个键值对写入绑定的 KV 命名空间
npx wrangler kv:key put --binding=MY_KV "my-key" "my-value"

# 读取一个键的值
npx wrangler kv:key get --binding=MY_KV "my-key"

# 列出所有键
npx wrangler kv:key list --binding=MY_KV

wrangler d1: 管理 D1 数据库 55。

bash

# 创建一个名为 "my-database" 的新 D1 数据库
npx wrangler d1 create my-database

# 对数据库执行一条 SQL 命令
npx wrangler d1 execute my-database --command "SELECT * FROM users"

# 创建一个新的数据库迁移文件
npx wrangler d1 migrations create my-database "add_users_table"

# 应用所有待处理的迁移
npx wrangler d1 migrations apply my-database

wrangler r2: 管理 R2 对象存储桶和对象。

bash

# 创建一个名为 "my-bucket" 的新 R2 存储桶
npx wrangler r2 bucket create my-bucket

# 从本地上传一个文件到 R2
npx wrangler r2 object put my-bucket/image.png --file=./image.png

# 从 R2 下载一个文件到本地
npx wrangler r2 object get my-bucket/image.png --file=./download.png

wrangler secret: 安全地管理环境变量，如 API 密钥。

bash

# 创建或更新一个名为 "API_KEY" 的 secret
npx wrangler secret put API_KEY

# 列出所有已配置的 secrets
npx wrangler secret list

# 删除一个 secret
npx wrangler secret delete API_KEY

wrangler tail: 实时流式传输来自已部署 Worker 的日志，用于实时调试和监控。

bash

# 开始监听名为 "my-worker" 的 Worker 的日志
npx wrangler tail my-worker

# 监听日志并只显示状态为 "error" 的请求
npx wrangler tail my-worker --status error

Cloudflare Wrangler 已经从一个单纯用于部署 Cloudflare Workers 的工具，演变为整个 Cloudflare 开发者平台的核心编排引擎。本指南全面探讨了 Wrangler 的功能，从基础的安装和项目初始化，到高级的配置、资源管理和自动化部署，旨在为开发者提供一个权威性的参考。

分析表明，Wrangler 的设计哲学和功能演进体现了对现代云原生开发工作流的深刻理解。其关键优势在于：

Wrangler 提供了一个单一的命令行界面，用于管理从计算（Workers、Pages）到存储（KV、R2、D1）再到消息传递（Queues）的全套无服务器产品。这种统一性极大地简化了构建复杂全栈应用的流程。

通过将开源的 workerd 运行时集成到 wrangler dev 中，Wrangler 提供了与生产环境几乎完全一致的本地开发体验。这不仅通过实时重载和调试器集成等功能显著提高了开发效率，更重要的是，它增强了开发者在部署前的信心，减少了环境差异所导致的错误。

wrangler.jsonc 配置文件是 Wrangler 工作流的核心。通过将路由、环境变量和资源绑定等基础设施配置与应用程序代码一同进行版本控制，Wrangler 鼓励并促成了一种 GitOps 实践。这种"配置即代码"的方法使得部署过程可预测、可重复且可审计。

Wrangler 对多环境（开发、预发、生产）的原生支持，结合其精心设计的 secrets 管理工作流，为开发者提供了一套既灵活又安全的框架。特别是绑定和变量的非继承规则，以及本地 .dev.vars 与远程加密 secrets 的分离，都是旨在防止常见配置错误的深思熟虑的设计。

综上所述，掌握 Wrangler 不仅仅是学习一个 CLI 工具的命令，更是理解和运用 Cloudflare 边缘计算范式的方式。对于希望在 Cloudflare 平台上构建高性能、全球分布的无服务器应用程序的开发者而言，Wrangler 是一个不可或缺的、功能强大的助手。

相关内容

全面深入的 Cloudflare Wrangler 开发指南。涵盖 Wrangler CLI 安装配置、项目初始化、本地开发环境、配置文件管理、资源管理、部署策略、CI/CD 集成、Secrets 管理等核心功能，帮助开发者构建现代化的无服务器应用程序。

使用 Cloudflare Zero Trust 保护 SSH 访问的使用指南

全面深入的 Cloudflare Wrangler 开发指南。涵盖 Wrangler CLI 安装配置、项目初始化、本地开发环境、配置文件管理、资源管理、部署策略、CI/CD 集成、Secrets 管理等核心功能，帮助开发者构建现代化的无服务器应用程序。

Podman Build 技术解析

更新于 2025-08-15
 Cloudflare, Wrangler, CLI, 无服务器, Workers, Pages, D1, R2, KV, Tunnels, 边缘计算, 开发工具, 部署, CI/CD, DevOps
 | 主页