使用 Wrangler CLI 创建并部署第一个 Cloudflare Pages 网站

在完成 Cloudflare 账号注册后，最让人兴奋的一步莫过于将你的第一个网站推送到遍布全球的 Cloudflare 边缘网络。Cloudflare Pages 是一套 JAMstack 与全栈 Serverless 托管平台，能够将你的网页分发到全球 300 多个城市的数据中心，实现极速加载与高可用性。

虽然在网页端 Dashboard 可以手动上传压缩包，但通过官方的 Wrangler CLI（命令行工具），你可以获得更流畅、高效且易于接入 CI/CD 自动化流水线的开发者体验。

本文将以通俗易懂的方式，从环境准备、底层原理解析到命令行部署，带你顺利上线第一个 Cloudflare Page。

1. 核心概念（ELI5）：超音速货机与全球中转站#

我们可以把网站的分发过程比作实体漫画书的发行：

传统单服务器模式：你在办公室只印了一本样书。不管读者在东京、伦敦还是纽约，都必须跨越大洋来你的办公室翻看 -> 页面加载慢，服务器容易被挤爆。
Cloudflare Pages： Wrangler CLI 就好比一架超音速货机。当你在终端输入 wrangler pages deploy 时，它会瞬间把你的网站代码复制并分发到全球 300 多个边缘枢纽（Edge Data Centers）。
用户访问体验：东京的读者直接在东京分部读取，伦敦的读者在伦敦分部读取。无需复杂的服务器运维，几毫秒内即可极速打开。

flowchart TD
    A["💻 本地电脑<br/>(前端项目工程)"] -->|1. npx wrangler pages deploy| B["⚡ Cloudflare 全球边缘网络"]
    B --> C["🌏 东京边缘节点"]
    B --> D["🌏 法兰克福边缘节点"]
    B --> E["🌏 新加坡边缘节点"]
    B --> F["🌏 圣何塞边缘节点"]
    
    User1["👤 日本读者"] -->|极速响应| C
    User2["👤 欧洲读者"] -->|极速响应| D
    User3["👤 美洲读者"] -->|极速响应| F

2. 常见问题与解决思路#

新手常见困惑#

安装了废弃的旧版本包：误装了 @cloudflare/wrangler (v1)，导致命令行参数不兼容或报错。
全局安装引发冲突：使用 npm install -g 容易造成权限问题（Permission Denied）或者不同项目间的 CLI 版本冲突。
手动上传费时费力：依赖网页端拖拽不仅效率低下，且不利于多人协作与自动化集成。

最佳解决实践#

推荐使用项目本地依赖（Local DevDependency）安装 Wrangler，或直接使用 npx 执行。
借助官方脚手架 C3（create-cloudflare）一键初始化工程。
使用 npx wrangler login 唤起浏览器单点登录，安全完成鉴权绑定。

3. 系统环境要求（System Requirements）#

在开始之前，请确保你的开发环境满足以下条件：

Node.js: 版本 16.17.0 或更高（强烈建议使用 nvm、volta、fnm 或 bun 等版本管理工具）。
操作系统: macOS 13.5+、Windows 11 或 Linux (支持 glibc 2.35+)。
浏览器环境: 已注册并能正常登录 Cloudflare 控制台 ↗。

[!TIP] 如果你的系统中曾全局安装过旧版 Wrangler，建议先将其卸载：
npm uninstall -g @cloudflare/wrangler
bash

4. 详细操作步骤#

方案 1：使用 C3 脚手架从零创建全新项目（推荐）#

Create Cloudflare CLI (C3) 是初始化 Cloudflare 项目的最快途径，会自动为你配置好最新版 Wrangler。

在终端中执行以下命令之一：

# 使用 npm
npm create cloudflare@latest -- my-pages-app

# 使用 pnpm
pnpm create cloudflare@latest my-pages-app

# 使用 Bun
bun create cloudflare@latest my-pages-app

bash

终端交互提示将引导你选择：

项目类型：静态网站、常用现代框架（Astro、Next.js、Nuxt、SvelteKit、React/Vite 等）或 “Hello World”。
语言选择： TypeScript 或 JavaScript。
是否立即部署：可选择先本地查看或直接发布上线。

方案 2：为已有项目配置 Wrangler 并部署静态网页#

如果你已有现成的前端构建产物，或希望手动编写一个极简 HTML 页面：

第一步：创建项目目录与页面#

新建工程文件夹与静态资源目录 public：

mkdir my-first-page
cd my-first-page

bash

创建 public/index.html：

public/index.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>我的第一个 Cloudflare Pages 页面</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      margin: 0;
      background: linear-gradient(135deg, #f38020, #faad3f);
      color: #fff;
    }
    .card {
      background: rgba(255, 255, 255, 0.15);
      backdrop-filter: blur(10px);
      padding: 2.5rem;
      border-radius: 16px;
      box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
      text-align: center;
      max-width: 500px;
    }
    h1 { margin-top: 0; }
  </style>
</head>
<body>
  <div class="card">
    <h1>🚀 欢迎访问 Cloudflare Pages！</h1>
    <p>通过 Wrangler CLI 秒级分发至全球 300 多个边缘数据中心。</p>
  </div>
</body>
</html>

html

第二步：本地安装 Wrangler#

初始化 package.json 并添加 Wrangler 依赖：

npm init -y
npm install --save-dev wrangler

bash

第三步：绑定 Cloudflare 账号#

在终端运行登录命令：

npx wrangler login

bash

系统将自动打开默认浏览器跳转至授权页面。点击 Allow（允许）完成授权。返回终端后会看到成功提示：

Successfully logged in.

text

随时可以通过该命令确认当前登录身份：

npx wrangler whoami

bash

5. 部署到 Cloudflare Pages#

运行 pages deploy 命令，指定需要上传的静态资源目录（例如 public 或框架构建输出的 dist）：

npx wrangler pages deploy public --project-name my-first-page

bash

首次部署时：

Wrangler 会自动在你的 Cloudflare 账户下创建名为 my-first-page 的 Pages 项目。
将 public 目录下的所有静态资源推送到边缘网络。
输出一个公开访问域名（例如：https://my-first-page.pages.dev）。

[!NOTE] 在正式发布前，你也可以使用以下命令启动本地仿真服务器进行实时预览：
npx wrangler pages dev public --port 8788
bash

6. Wrangler 常用命令速查表（Quick Reference）#

常用操作	对应命令	功能说明
登录授权	`npx wrangler login`	在浏览器中打开授权页绑定账户
账号信息	`npx wrangler whoami`	查看当前绑定的邮箱与 Account ID
本地调试	`npx wrangler pages dev <目录>`	启动本地开发服务器仿真 Pages 环境
发布上线	`npx wrangler pages deploy <目录>`	部署静态文件并生成 `.pages.dev` 访问链接
项目列表	`npx wrangler pages project list`	查看账户下所有 Cloudflare Pages 项目
部署记录	`npx wrangler pages deployment list`	查看近期的部署记录及 Commit 哈希

1. 核心概念（ELI5）：超音速货机与全球中转站#

2. 常见问题与解决思路#

新手常见困惑#

最佳解决实践#

3. 系统环境要求（System Requirements）#

4. 详细操作步骤#

方案 1：使用 C3 脚手架从零创建全新项目（推荐）#

方案 2：为已有项目配置 Wrangler 并部署静态网页#

第一步：创建项目目录与页面#

第二步：本地安装 Wrangler#

第三步：绑定 Cloudflare 账号#

5. 部署到 Cloudflare Pages#

6. Wrangler 常用命令速查表（Quick Reference）#

7. 参考资料（References）#