手把手教你用Wrangler部署项目到CloudflarePages

Wrangler 简介

Wrangler 是 Cloudflare 官方开发的命令行工具，专门用于管理和部署 Cloudflare 平台上的各种服务。
它就像是连接你本地开发环境和 Cloudflare 全球网络的桥梁，
让你无需打开浏览器就能完成复杂的部署和配置工作。

Wrangler 的主要功能包括：

• Cloudflare Workers：部署无服务器函数
• Cloudflare Pages：部署静态网站和全栈应用
• Cloudflare R2：管理对象存储
• D1 数据库：操作边缘数据库
• 环境管理：配置变量、密钥和兼容性设置

今天，我们将专注于它的 Pages 功能，学习如何用最简单的命令将本地项目部署到全球网络。

前置知识要求

在开始本教程之前，我默认你已具备以下基础知识和技能。这将确保你能顺利理解并执行后续所有步骤。

• 1. 命令行操作基础

  • 要求：能够在你的操作系统（如 Windows 的 PowerShell/CMD）中，
    打开终端并执行基本的命令行操作。
  • 核心能力：
    • 知道如何定位到项目所在目录（使用 cd 命令）。
    • 熟悉各种快捷键如 Ctrl+C & Ctrl+V （使用 复制&粘贴 命令）。
  • 本教程完全在命令行中完成，从工具安装、登录到最终部署，每个步骤都依赖于命令行。

• 2. 前端项目基本概念

  • 要求：你有一个已开发完成或可构建的本地网站/应用项目。(将开源项目下载到本地也可以)
  • 核心概念：
    • 项目根目录：你知道项目的哪个文件夹是“根目录”。
    • 构建：你了解你所使用的框架（如 Vite、Next.js、Vue CLI 等）如何生成生产环境文件。
      你应该能够在本地成功运行构建命令，并在项目根目录下生成一个输出文件夹
      （如 dist、build 或 out）。
  • Wrangler 部署的正是这个构建后生成的静态文件目录。
    你需要明确知道“构建”这个动作以及“输出目录是哪里”。

• 3. 必备的 Cloudflare 账户

  • 要求：你需要拥有一个有效的 Cloudflare 账户。如果没有，请先访问 https://dash.cloudflare.com/sign-up 免费注册。
  • 所有部署操作最终都会将你的项目文件上传到你的 Cloudflare 账户下，这是部署目标平台。

确认清单： 在继续下一步之前，你可以快速自我检查：
☐ 我能在电脑上打开终端/命令行窗口。
☐ 我有一个可以构建的本地项目。
☐ 我知道如何构建我的项目，并且知道构建后的文件在哪个文件夹里。
☐ 我已经注册了 Cloudflare 账户。

如果你确认以上几点，那么你已经完全具备了学习本教程的基础，可以开始享受流畅的部署过程了！

第一步：环境准备

安装 Node.js

Node.js® 是一个免费、开源、跨平台的 JavaScript 运行时环境。
Wrangler 基于 Node.js 开发，因此你需要先安装 Node.js 运行环境。

如果你尚未安装 Node.js：

请访问 https://nodejs.org/ 下载并安装 Node.js 运行环境。
网上有许多详细的 Node.js 安装教程，你可以搜索“Node.js 安装教程”找到适合的指南。

验证安装

安装完成后，打开你的终端，输入以下命令验证安装是否正确：

第一个命令：

node -v

第二个命令：

npm -v

如果看到类似这样的版本号输出，说明安装成功：

v25.6.0  # Node.js 版本
11.9.0     # npm 版本

如果这些命令提示“未找到命令”或显示错误信息，
请重新检查 Node.js 的安装步骤，确保已将 Node.js 添加到系统环境变量中。

关于包管理器（推荐pnpm）

相比npm，为何推荐使用pnpm？它在以下两个方面优势显著：

1. 极致的安装速度 pnpm采用独特的硬链接机制管理依赖，避免了npm复制文件的操作，
   通常能将依赖安装时间缩短数倍。

2. 高效的磁盘利用 在pnpm的全局存储模式下，同一个版本的依赖包在磁盘上只会保存一次。
   你创建的所有项目都可以共享这些依赖，从而节省大量磁盘空间。

安装 pnpm 非常简单，只需在终端中执行以下命令即可：

npm install -g pnpm@latest-10

安装完毕后，可通过以下命令来验证是否安装成功：

pnpm -v

如果终端显示出 pnpm 的版本号（例如 10.29.3），就说明 pnpm 已准备就绪。
完成环境准备后，我们就可以开始安装和使用 Wrangler 了。

第二步：安装 Wrangler

确保在项目根目录打开终端，然后执行以下命令安装 Wrangler：

pnpm add -D wrangler@latest

安装完成后，通过以下命令验证是否安装成功：

pnpm wrangler -v

如果终端输出类似 wrangler 4.x.x 的版本号信息，则表明 Wrangler 已成功安装并准备就绪。

补充说明： 如果你希望使用 npm 而非 pnpm 安装 Wrangler，
只需将上述命令中的 pnpm 替换为 npm 即可。
例如：

npm i -D wrangler@latest

验证安装时，由于 Wrangler 被安装在项目本地而非全局，你需要通过 npm 自带的 npx 工具来运行它：

npx wrangler -v

两种包管理器安装后的效果完全一致。 为统一演示流程，后续操作将全部基于 pnpm 进行说明。

第三步：登录 Cloudflare 账户

安装好 Wrangler 后，你需要为它授权，以便获得将项目部署到 Cloudflare Pages 的权限。
你可以选择以下任一方法完成登录。

方法 A：快速交互式登录（推荐用于本地开发）

这是最直接的方法，适合在个人电脑上进行开发和测试。在终端中运行：

pnpm wrangler login

执行后，Wrangler 会自动打开你的浏览器，跳转到 Cloudflare 授权页面。
按照提示完成授权即可。
成功后，终端会显示 “Successfully logged in.”。

优点：简单快捷，一键完成。
注意：此方法依赖本地浏览器，不适用于无图形界面的服务器或自动化流程。

方法 B：使用 API 令牌登录（适用于 CI/CD 与服务器）

此方法更稳定、可编程，是在持续集成（CI/CD）、远程服务器或 Docker 容器中进行自动部署的推荐方式。

1. 生成 API 令牌

1. 登录 https://dash.cloudflare.com
2. 在左侧导航栏底部，点击 “帐户 API 令牌”。
3. 点击页面中的 “创建令牌” 按钮。
4. 在模板列表中找到并选择 “编辑 Cloudflare Workers” 模板，点击其右侧的 “使用模板” 按钮。
5. 关键配置：在打开的配置页面中：
   • 在”区域资源”部分，选择 包括 >> 账户的所有区域 >> 账户昵称
6. 滚动到页面底部，点击 “继续以生成摘要”。
7. 在最终摘要页面核对信息，确认无误后点击 “创建令牌”。
8. 在弹出的窗口中，完整复制并妥善保存生成的令牌字符串。 关闭此窗口后，令牌将无法再次完整查看。

2. 获取账户 ID

1. 登录 https://dash.cloudflare.com
2. 在左侧导航栏中，点击 “Workers & Pages”。
3. 在页面右侧的 Account Details 区域，直接复制 Account ID 的值。

3. 在部署环境中使用 API 令牌

生成并保存好 API 令牌后，你需要在你的 CI/CD 服务器、远程机器或本地项目环境中，
让 Wrangler 能够读取到这个令牌，从而完成身份验证。
主要有以下两种推荐方式：

方式一：在项目中使用 .env 文件（推荐用于本地项目和可复用的部署脚本）

这是最常见且安全的方式，尤其适合将配置与项目代码放在一起管理。

1. 创建环境变量文件：在你的项目根目录下，创建一个名为 .env 的文件。
2. 写入令牌：在 .env 文件中，添加以下内容：

   # Cloudflare API Token for Wrangler
   CLOUDFLARE_API_TOKEN=你刚才复制的令牌字符串
   CLOUDFLARE_ACCOUNT_ID=你刚才复制的账户ID

3. 确保文件安全： 你必须将 .env 文件添加到项目的 .gitignore 文件中， 以防止此包含敏感信息的文件被意外提交到公开的代码仓库。 在 .gitignore 中加入一行：.env。
4. 工作原理：此后，当你在项目目录下运行 Wrangler 命令（如 pnpm wrangler pages deploy）时，Wrangler 会自动读取此 .env 文件中的 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID
   并以此完成认证，无需任何手动交互。

方式二：在系统或 CI/CD 流水线中设置环境变量（推荐用于服务器和自动化流程）

在 CI/CD 服务（如 GitHub Actions、GitLab CI）或远程服务器的 Shell 环境中，
你可以直接设置环境变量。

• 在 Linux/macOS 的终端或 CI/CD 脚本中：

  export CLOUDFLARE_API_TOKEN="你刚才复制的令牌字符串"
  export CLOUDFLARE_ACCOUNT_ID="你刚才复制的账户ID"

• 在 Windows 命令提示符 (CMD) 中：

  set CLOUDFLARE_API_TOKEN=你刚才复制的令牌字符串
  set CLOUDFLARE_ACCOUNT_ID=你刚才复制的账户ID

• 在 CI/CD 平台中：在你使用的 CI/CD 平台（如 GitHub、GitLab、Jenkins 等）
  的项目设置或流水线配置中，找到”Secrets”（机密）或”Environment Variables”（环境变量）
  设置项，添加名为 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 的变量，
  并将相应的值粘贴进去。
  这样，在流水线运行时，这些变量会自动对脚本可见。

验证登录状态

现在，无论你通过哪种方式登录，都建议在最终执行部署的终端环境中运行以下命令，
进行最终的、统一的权限确认：

pnpm wrangler whoami

预期成功的输出会清晰显示你的账户名和 ID，例如：

⛅️ wrangler 4.x.x
-------------------
Getting User settings...

┌─────────────────────────┬──────────────────────────────────────┐
│ Account Name            │ Account ID                           │
│ Account Name            │ Account ID                           │
└─────────────────────────┴──────────────────────────────────────┘

这个命令的作用是：

1. 最终确认登录成功。
2. 明确当前操作账户，防止误操作到其他 Cloudflare 账户。

看到正确的账户信息后，你就可以放心地进行后续的项目部署操作了。

第四步：配置 wrangler.toml 文件

为了在部署时更轻松，你可以在项目根目录创建一个 wrangler.toml 配置文件。
这能让你的部署命令更简洁，配置更清晰、可重复。

1. 创建配置文件

在你的项目根目录下，创建一个名为 wrangler.toml 的新文件。

2. 写入基础配置

将以下内容复制到 wrangler.toml 文件中，并根据你的实际情况修改：

# 你的 Cloudflare Pages 项目名称
name = "your-project-name"
# 兼容性日期
compatibility_date = "2026-02-14"
# 项目构建后的输出目录路径
pages_build_output_dir = "./dist"

参数说明：

• name: 这将是你在 Cloudflare Pages 上创建的项目名称。
  如果这个名称的项目尚不存在，首次部署时会自动创建。
• compatibility_date: 它定义了你的项目应遵循哪个版本的 Cloudflare Workers 运行时功能。
  设置一个当前或未来的日期，以确保你能使用最新的稳定
• pages_build_output_dir: 这是你本地项目经过构建后，生成的静态文件所在的目录路径。
  请根据你使用的框架或工具进行修改，常见的有 ./dist, ./build, ./out 等。

3. 配置文件的好处

Wrangler 会自动读取 wrangler.toml 中的 name 和 pages_build_output_dir 配置。
这使得命令行更简洁，并且配置（特别是项目名称）可以通过版本控制系统在团队中共享。

进阶配置：wrangler.toml 的功能远不止于此，
它还是你管理项目环境变量和绑定 Cloudflare 资源（如 KV 命名空间）的中心。
你可以通过它来：

• 定义环境变量：在 [vars] 区块中声明键值对，
  这些变量可以在你的 Pages Functions 或 Worker 代码中被访问。

  [vars]
  API_BASE_URL = “https://api.example.com“
  ADMIN_EMAIL = “admin@example.com“

• 绑定 KV 命名空间：在 [[kv_namespaces]] 区块中，
  将你在 Cloudflare 上创建的 KV 存储绑定到你的项目代码中，以便在边缘读取和写入数据。

  [[kv_namespaces]]
  binding = “MY_KV_STORE“  # 在代码中使用的变量名
  id = “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx“  # KV 命名空间的 ID

通过在 wrangler.toml 中集中管理这些配置，你可以确保不同环境（开发、生产）的配置一致性，
并避免在代码中硬写敏感信息。

第五步：执行一键部署

一条命令，即可将你的网站发布至 Cloudflare 全球边缘网络。

核心部署命令：

pnpm wrangler pages deploy --project-name=项目名称

首次部署流程：

1. Wrangler 将自动上传 pages_build_output_dir 参数指定的路径下的全部文件。
2. 若项目名称不存在，Cloudflare 会即时为你创建对应的 Pages 项目。
3. 部署成功后，终端将输出一个专属预览链接（格式如：https://[随机字符串].[项目名].pages.dev）
4. 点击该链接，你的网站即刻在全球网络中可访问。

总结

至此，你已成功解锁了通过 Wrangler CLI 从本地开发环境直达 Cloudflare 全球网络的完整部署能力。
这不仅是操作方式的转变——从图形界面点击到高效的命令行驱动，
更是将发布流程彻底标准化、自动化，使之无缝嵌入现代开发工作流的精髓所在。

进阶探索方向

掌握了基础部署，Cloudflare Pages 的潜力远不止于此。 你可以继续深入，构建更强大、更自动化的应用：

• 自动化部署流水线 (CI/CD)：将 Wrangler 部署命令集成到 GitHub Actions 或 GitLab CI 等工具中。
  实现代码推送后，自动完成构建、测试、部署的全流程，真正做到“提交即上线”。
• 即时预览与协作 (Branch Preview)：利用 Cloudflare Pages 原生支持的 Branch Preview 功能。
  每个 Pull Request 或功能分支都会自动生成一个独有的、可分享的预览链接，
  极大地简化了代码评审和功能测试流程。
• 构建全栈应用 (Pages Functions)：文档中提到的 Pages Functions 是核心进阶能力。
  它允许你在 Pages 项目中直接编写并部署无服务器函数，
  轻松实现 API 路由、动态渲染、表单处理等后端逻辑，而无需管理任何服务器。
  这正是创建“瞬时部署到全球网络的全栈应用”的关键。

核心价值回顾

选择 Wrangler 部署，其核心价值在于极致的开发者体验与无限的自动化可能。
它不仅仅是简化了点击操作，更是将应用发布从一项“任务”转变为一种
可编程、可重复、可集成的“基础设施”。

现在，你的项目已经具备了全球可访问的基石。
接下来，无论是构建静态博客、动态应用，还是复杂的全栈服务，
Cloudflare Pages 都为你提供了从边缘网络、数据库到对象存储的完整生态系统支持。

立即开始你的下一次构建吧！
如果在实践中遇到任何问题，可以随时回顾本教程的各步骤要点，
或访问 https://developers.cloudflare.com/pages/ 获取最权威的指南、API 参考和社区资源。
你也可以加入 Cloudflare 开发者社区，与其他开发者交流心得。