使用 Wrangler CLI 部署 Cloudflare Pages

文章目录

一、准备与登录
二、核心部署命令
- 1. 部署预览版本（Preview Deployment）
- 2. 部署到生产环境（Production Deployment）
三、使用配置文件 wrangler.jsonc / wrangler.toml
四、常用进阶 Flag 选项
五、在 CI/CD (如 GitHub Actions) 中自动化集成

使用 Wrangler CLI 部署 Cloudflare Pages

酷玩 2026-10-09

12 观看次数

586 字数

0 评论

cloudflare wrangler pages 建站资源

使用 Wrangler CLI 部署 Cloudflare Pages，适合追求自动化、需要在本地/终端快速投产，或希望将部署集成到 CI/CD 流程中的开发者。

一、准备与登录

环境准备
确保本地已安装 Node.js（建议 v18+）。
全局安装或项目本地安装 Wrangler
建议在项目根目录下推荐局部安装，或者直接使用 npx：
```
npm install --save-dev wrangler
```
登录身份验证
在终端运行授权命令：
```
npx wrangler login
```

此时会自动打开浏览器，点击 authorize（授权）连接你的 Cloudflare 账号即可。

二、核心部署命令

部署的基本语法格式为：

npx wrangler pages deploy <静态资源目录> [常用选项]

1. 部署预览版本（Preview Deployment）

如果是功能测试或临时分支，可以直接运行命令。Wrangler 会自动为你生成一个包含随机 Hash 的临时预览链接（形如 https://<hash>.<project-name>.pages.dev）：

# 假设你的项目构建输出目录是 dist
npx wrangler pages deploy ./dist --project-name=my-app

注意：首次部署时，如果 --project-name 对应的项目不存在，Cloudflare Pages 会在你的账号下自动新建该项目。

2. 部署到生产环境（Production Deployment）

如果要直接将代码推送到主生产域名（即直接更新线上站点），需要附加 --branch=main（或你指定的主分支名）：

npx wrangler pages deploy ./dist --project-name=my-app --branch=main

三、使用配置文件 `wrangler.jsonc` / `wrangler.toml`

从 Wrangler v3.45+ 开始，Cloudflare Pages 已经原生支持通过配置文件进行设置（类似 Cloudflare Workers 的配置方式）。这样就无需在命令行里打一长串参数。

在项目根目录下新建 wrangler.jsonc（或 wrangler.toml）：

// wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-app",
  "pages_build_output_dir": "./dist", // 声明静态资源目录
  "compatibility_date": "2026-01-01",
  "vars": {
    "API_URL": "https://api.example.com" // 可以在此声明环境变量
  }
}

配置好文件后，部署命令将变得非常简洁：

# Wrangler 会自动读取配置中的 name 和 pages_build_output_dir
npx wrangler pages deploy

四、常用进阶 Flag 选项

在 CLI 部署时，你可以灵活运用以下常用参数：

选项 Flag	说明	示例
`--project-name`	指定 Pages 项目名称	`--project-name=my-blog`
`--branch`	指定部署对应的分支（传入主分支名即为生产环境部署）	`--branch=main`
`--commit-hash`	显式附带 Git 提交 Hash，方便在控制台追溯版本	`--commit-hash=a1b2c3d`
`--commit-message`	附带说明信息（显示在 Pages 控制台部署历史中）	`--commit-message="Update Homepage UI"`
`--commit-dirty`	允许未提交的代码状态上传	`--commit-dirty=true`

综合示例：

npx wrangler pages deploy ./public \
  --project-name=company-landing \
  --branch=main \
  --commit-message="Release v2.0.0"

五、在 CI/CD (如 GitHub Actions) 中自动化集成

如果不想依赖 Cloudflare 原生的 Git 机器构建，而是想在 GitHub Actions 或 GitLab CI 中自主构建并部署，可以在 Actions 中使用 Wrangler 的 API Token：

获取 API Token：
进入 Cloudflare 控制台 -> 我的个人资料 -> API 令牌。
创建一个包含 Cloudflare Pages: Edit 权限的 Token。
将 Token 保存到 GitHub 仓库的 Secrets 中（例如命名为 CLOUDFLARE_API_TOKEN）。
编写 GitHub Actions 工作流 (.github/workflows/deploy.yml)：

name: Deploy to Cloudflare Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install & Build
        run: |
          npm install
          npm run build

      - name: Deploy with Wrangler Action
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: pages deploy ./dist --project-name=my-app --branch=main