将 GitHub Actions 环境变量与 Secrets 接入 Cloudflare

要将 GitHub Actions 环境变量与 Secrets 连接到 Cloudflare（Workers、Pages 或 Cloudflare API 部署），你需要在 GitHub 仓库中配置机密，并在 wrangler-action 或自定义 CI/CD 工作流步骤中将其传入。

架构调用流程#

flowchart LR
    subgraph GitHub["GitHub 生态系统"]
        G_SEC["GitHub Secrets & Vars<br>(CLOUDFLARE_API_TOKEN, DB_PASS, APP_ENV)"]
        G_ACT["GitHub Actions 运行节点<br>(CI/CD 流水线)"]
        G_SEC -->|通过 env / with 注入| G_ACT
    end

    subgraph CF["Cloudflare 平台"]
        WRANGLER["Cloudflare Wrangler / Deploy Action"]
        CF_WORKER["Cloudflare Worker / Pages / 资源"]
        G_ACT -->|鉴权并部署| WRANGLER
        WRANGLER -->|推送代码、变量与 Secrets| CF_WORKER
    end

步骤 1：获取 Cloudflare 凭证#

以下是在 Cloudflare 控制台中查找和生成两项凭证的具体方法：

1. 获取 CLOUDFLARE_ACCOUNT_ID#

Account ID 是与你的 Cloudflare 账户绑定的 32 位十六进制字符串。

方法 A：从 Workers & Pages 页面（最快捷）
1. 登录 Cloudflare 控制台 ↗。
2. 在左侧边栏点击 Compute (Workers & Pages)（或 Workers & Pages）。
3. 查看右侧边栏 Account details 下的 Account ID，点击即可复制。
方法 B：从浏览器 URL 查看
1. 登录控制台后，进入任意域名或功能面板。
2. 观察浏览器地址栏：https://dash.cloudflare.com/<ACCOUNT_ID>/workers-and-pages
3. dash.cloudflare.com/ 紧随其后的英数字符串即为你的 Account ID。

2. 生成 CLOUDFLARE_API_TOKEN#

切勿使用全局 Global API Key。请创建仅具备最小必要权限的定制 API Token。

点击控制台右上角的用户头像 -> My Profile。
在左侧导航栏选择 API Tokens。
点击 Create Token。
使用预设模板或自定义配置：
- 使用模板：找到 Edit Cloudflare Workers，点击 Use template。
- 自定义 Token：选择 Create Custom Token 并配置：
  - Permissions：
    - Account -> Workers Scripts -> Edit
    - Account -> Workers KV Storage -> Edit（若使用 KV）
    - Account -> Pages -> Edit（若部署 Pages）
  - Account Resources：Include -> All accounts（或指定具体账户）。
滚动至页面底部，点击 Continue to summary -> Create Token。
立即复制并保存该 Token（Cloudflare 仅展示一次）。

终端 CLI 快速验证#

你可以在本地终端通过 curl 发送请求以验证 Token 是否生效：

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer <YOUR_CLOUDFLARE_API_TOKEN>"

bash

若返回 "status": "active"，则证明 Token 有效，可安全添加到 GitHub Secrets 中。

步骤 2：在 GitHub 中配置 Secrets 与 Variables#

进入 Repository Settings > Secrets and variables > Actions 并配置：

1. Repository Secrets (加密 / 敏感机密)#

CLOUDFLARE_API_TOKEN：具备 Worker:Edit 或 Pages:Edit 权限的 Cloudflare API 令牌。
CLOUDFLARE_ACCOUNT_ID：你的 Cloudflare 账户 ID。
APP_SECRET_KEY：应用运行时所需的密钥（如 JWT 密钥、数据库连接字符串等）。

2. Repository Variables (明文 / 非敏感变量)#

ENVIRONMENT：production 或 staging。
API_BASE_URL：https://api.example.com。

步骤 3：GitHub Actions 工作流配置#

创建 .github/workflows/deploy.yml 并在部署过程中传递变量与机密：

.github/workflows/deploy.yml

name: Deploy to Cloudflare

on:
  push:
    branches:
      - main

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

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

      - name: Install dependencies
        run: npm ci

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy
        env:
          # 注入至 Wrangler 构建环境
          ENVIRONMENT: ${{ vars.ENVIRONMENT }}
          API_BASE_URL: ${{ vars.API_BASE_URL }}
          APP_SECRET_KEY: ${{ secrets.APP_SECRET_KEY }}

yaml

步骤 4：在 Cloudflare 中访问变量#

根据变量属于明文还是加密机密，分别通过 wrangler.jsonc 配置或由 CLI 推送：

1. 明文变量 (`wrangler.jsonc`)#

非敏感变量可以直接绑定在配置文件中：

wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-01",
  "vars": {
    "ENVIRONMENT": "production",
    "API_BASE_URL": "https://api.example.com"
  }
}

json

2. 运行时加密 Secrets (通过 Wrangler 直接推送)#

如需直接从 GitHub Actions 上传 Secrets 到 Cloudflare，且无需签入代码仓库：

      - name: Push Secrets to Cloudflare Worker
        run: |
          echo "${{ secrets.APP_SECRET_KEY }}" | npx wrangler secret put APP_SECRET_KEY
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}