Deploy with Workers 按钮使用指南

为开发者和使用者而写的指南。需要使用该按钮的用户请看使用一节，需要设置该按钮的开发者请看开发一节。

由于 Cloudflare Workers 的特殊性，该按钮无论是使用还是设置起来都比 Vercel 的按钮复杂多了，而且文档也语焉不详，所以特地写了一篇文章。

写于 2024 年 10 月，如果之后流程有变请评论通知我修改。

使用

为这个样子的按钮提供的指南。

开始之前

需要有一个 GitHub 账号。

最好提前注册好一个 Cloudflare 账号（如果没有，会在部署过程中提示注册）。

Authorize GitHub with Workers

没啥可说的，点击按钮后在 GitHub 授权即可。

Authorize

Configure Cloudflare Account

这步比较复杂。

首先登录/创建一个 Cloudflare 账户。

下一步中， Account ID 按照它的指引（点击链接）后可以直接找到，很方便； API Token 略微复杂一些，下面细说。

首先点击它提供的 My Profile 链接，这个链接应该会直接指向 API Tokens 这个页面（如果没有，先登录，然后重新点击这个链接）

点击 Create Token 按钮；

选择 Edit Cloudflare Workers 这个 template

然后下一个界面里，

修改 Token name （不必要但推荐）
Permissions 不需要修改
Account Resources 和 Zone Resources 都选 Include All 就行
TTL 可以不管

Continue to Summary 然后 Create Token。

复制此时显示的 Token，然后返回 Deploy Button 的网页填入。

Deploy with GitHub Actions

这里跟着指引应该很轻松。

先点下按钮，会自动 Fork Repo（此时 Repo 中会自动创建数个 CF 相关的 Action Secrets）
按照指引前往（点击链接）前往 GitHub 启用 GitHub Actions
最后点击 Deploy 按钮，等待一段时间（一般就几分钟）让 GitHub Actions 跑完就部署好了。

如果 GitHub Actions 报错，请联系仓库原主人，有可能是他的 GitHub Actions 配错了/没有为 Fork 的仓库考虑。

开发

Cloudflare 有一篇文档，但是年久失修，且不全。https://developers.cloudflare.com/workers/tutorials/deploy-button/。所以才写了本文。

我的一个使用了该按钮的例子： yy4382/read-aloud: 运行于 Cloudflare Workers 上的微软“大声朗读”转发器。通过简单的 HTTP GET 请求，将文本转换为语音。

原理

这篇教程适用于使用 wrangler 进行部署的 Cloudflare Workers 项目，比如 Hono 项目。

Deploy with Cloudflare 按钮的基本原理是帮用户 Fork 你（开发者）的 Repo，然后使用 Repo 中的 Actions 部署 Worker 到 Cloudflare 中。

而由于这个按钮会帮助用户 Fork，因此作为开发者需要做的就是设置一个 GitHub Actions，可以在任何仓库中进行部署。

设置 Actions

首先，需要保证你的项目可以直接通过 wrangler deploy 命令（不带其他选项）进行部署。需要注意的是，如果是 Hono 创建的项目，可能需要在 wrangler.toml 中增加 main 属性指定入口文件（一般是 src/index.ts[x]）。

然后添加 .github/workflows/deploy.yml，以下是我推荐的一个例子

name: Deploy Worker
on:
  push:
    branches:
      - main # trigger deploy everytimes pushed to main
  repository_dispatch: # The deploy button relies on this line to work
  workflow_dispatch: # gives you a button to manually trigger job

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v2
      - name: Build & Deploy Worker
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          # workingDirectory: # required if your wrangler.toml is not in root dir
          # See https://github.com/cloudflare/wrangler-action for more options

可以发现，使用了 CF_API_TOKEN 和 CF_ACCOUNT_ID 两个 secret，作为开发者需要手动设置（在 GitHub Actions 中使用机密 - GitHub 文档），而你的用户通过 Deploy with Cloudflare 按钮 Fork 时会被自动设置好。

然后尝试手动运行该 Action，确定可以正常运行。

插入按钮

将 [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/YOURUSERNAME/YOURREPO) 中的 YOURUSERNAME 和 YOURREPO 替换一下之后就可以放在任何 Markdown 文档里了。