Cloudflare Workers

Cloudflare Workers 是 Cloudflare CDN 上的 JavaScript 邊緣執行環境。

您可以在本地開發應用程式，並使用 Wrangler 以幾個指令發佈。Wrangler 包括轉譯編譯器，因此我們可以使用 TypeScript 編寫程式碼。

讓我們使用 Hono 為 Cloudflare Workers 建立您的第一個應用程式。

1. 設定

Cloudflare Workers 的入門範本已可用。使用 "create-hono" 命令開始您的專案。在此範例中選擇 cloudflare-workers 範本。

npm create hono@latest my-app

yarn create hono my-app

pnpm create hono my-app

bunx create-hono my-app

deno run -A npm:create-hono my-app

移動到 my-app 並安裝依賴項。

npmyarnpnpmbun

cd my-app
npm i

cd my-app
yarn

cd my-app
pnpm i

cd my-app
bun i

2. Hello World

如下編輯 src/index.ts。

import { Hono } from 'hono'
const app = new Hono()

app.get('/', (c) => c.text('Hello Cloudflare Workers!'))

export default app

3. 執行

在本地執行開發伺服器。然後，在您的網頁瀏覽器中存取 https://127.0.0.1:8787。

npmyarnpnpmbun

npm run dev

yarn dev

pnpm dev

bun run dev

4. 部署

如果您有 Cloudflare 帳戶，您可以部署到 Cloudflare。在 package.json 中，$npm_execpath 需要更改為您選擇的套件管理器。

npmyarnpnpmbun

npm run deploy

yarn deploy

pnpm run deploy

bun run deploy

就是這樣！

Service Worker 模式或模組 Worker 模式

有兩種語法用於編寫 Cloudflare Workers。模組 Worker 模式 和 Service Worker 模式。使用 Hono，您可以使用這兩種語法編寫，但我們建議使用模組 Worker 模式，以便綁定變數是本地化的。

// Module Worker
export default app

// Service Worker
app.fire()

將 Hono 與其他事件處理程式一起使用

您可以在 模組 Worker 模式 中將 Hono 與其他事件處理程式 (例如 scheduled) 整合。

要做到這一點，請將 app.fetch 作為模組的 fetch 處理程式匯出，然後根據需要實作其他處理程式

const app = new Hono()

export default {
  fetch: app.fetch,
  scheduled: async (batch, env) => {},
}

提供靜態檔案

如果您想提供靜態檔案，您可以使用 Cloudflare Workers 的靜態資產功能。在 wrangler.toml 中指定檔案的目錄

toml

assets = { directory = "public" }

然後建立 public 目錄並將檔案放置在那裡。例如，./public/static/hello.txt 將作為 /static/hello.txt 提供。

.
├── package.json
├── public
│   ├── favicon.ico
│   └── static
│       └── hello.txt
├── src
│   └── index.ts
└── wrangler.toml

類型

如果您想要使用 worker 類型，您必須安裝 @cloudflare/workers-types。

npmyarnpnpmbun

npm i --save-dev @cloudflare/workers-types

yarn add -D @cloudflare/workers-types

pnpm add -D @cloudflare/workers-types

bun add --dev @cloudflare/workers-types

測試

對於測試，我們建議使用 @cloudflare/vitest-pool-workers。請參考範例進行設定。

如果有以下應用程式。

import { Hono } from 'hono'

const app = new Hono()
app.get('/', (c) => c.text('Please test me!'))

我們可以使用此程式碼測試它是否傳回 "200 OK" 回應。

describe('Test the application', () => {
  it('Should return 200 response', async () => {
    const res = await app.request('https://127.0.0.1/')
    expect(res.status).toBe(200)
  })
})

綁定

在 Cloudflare Workers 中，我們可以綁定環境值、KV 命名空間、R2 儲存桶或 Durable Object。您可以在 c.env 中存取它們。如果您將 "類型結構" 作為泛型傳遞給 Hono 的綁定，它將具有類型。

type Bindings = {
  MY_BUCKET: R2Bucket
  USERNAME: string
  PASSWORD: string
}

const app = new Hono<{ Bindings: Bindings }>()

// Access to environment values
app.put('/upload/:key', async (c, next) => {
  const key = c.req.param('key')
  await c.env.MY_BUCKET.put(key, c.req.body)
  return c.text(`Put ${key} successfully!`)
})

在中介層中使用變數

這是模組 Worker 模式的唯一情況。如果您想在中介層中使用變數或機密變數，例如基本身份驗證中介層中的 "username" 或 "password"，您需要如下編寫。

import { basicAuth } from 'hono/basic-auth'

type Bindings = {
  USERNAME: string
  PASSWORD: string
}

const app = new Hono<{ Bindings: Bindings }>()

//...

app.use('/auth/*', async (c, next) => {
  const auth = basicAuth({
    username: c.env.USERNAME,
    password: c.env.PASSWORD,
  })
  return auth(c, next)
})

同樣適用於 Bearer 身份驗證中介層、JWT 身份驗證或其他中介層。

從 Github Action 部署

在透過 CI 將程式碼部署到 Cloudflare 之前，您需要一個 cloudflare 令牌。您可以從這裡管理：https://dash.cloudflare.com/profile/api-tokens

如果是新建立的令牌，請選擇 編輯 Cloudflare Workers 範本，如果您已經有另一個令牌，請確保該令牌具有相應的權限（不，令牌權限在 cloudflare 頁面和 cloudflare worker 之間不共享）。

然後前往您的 Github 儲存庫設定儀表板：設定->機密和變數->操作->儲存庫機密，並新增一個名為 CLOUDFLARE_API_TOKEN 的新機密。

然後在您的 hono 專案根資料夾中建立 .github/workflows/deploy.yml，貼上以下程式碼

yml

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

然後編輯 wrangler.toml，並在 compatibility_date 行之後新增此程式碼。

toml

main = "src/index.ts"
minify = true

一切都準備好了！現在推送程式碼並享受它。

本地開發時載入 env

要設定本地開發的環境變數，請在專案的根目錄中建立 .dev.vars 檔案。然後像配置一般的 env 檔案一樣配置您的環境變數。

SECRET_KEY=value
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

有關此部分的更多資訊，您可以在 Cloudflare 文件中找到：https://developers.cloudflare.com/workers/wrangler/configuration/#secrets

然後我們使用 c.env.* 來取得我們程式碼中的環境變數。
對於 Cloudflare Workers，環境變數必須透過 c 取得，而不是透過 process.env。

type Bindings = {
  SECRET_KEY: string
}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/env', (c) => {
  const SECRET_KEY = c.env.SECRET_KEY
  return c.text(SECRET_KEY)
})

在將專案部署到 cloudflare 之前，請記住設定 Cloudflare Worker 專案配置中的環境變數/機密。

有關此部分的更多資訊，您可以在 Cloudflare 文件中找到：https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard

Cloudflare Workers ​

1. 設定 ​

2. Hello World ​

3. 執行 ​

4. 部署 ​

Service Worker 模式或模組 Worker 模式 ​

將 Hono 與其他事件處理程式一起使用 ​

提供靜態檔案 ​

類型 ​

測試 ​

綁定 ​

在中介層中使用變數 ​

從 Github Action 部署 ​

本地開發時載入 env ​

Cloudflare Workers

1. 設定

2. Hello World

3. 執行

4. 部署

Service Worker 模式或模組 Worker 模式

將 Hono 與其他事件處理程式一起使用

提供靜態檔案

類型

測試

綁定

在中介層中使用變數

從 Github Action 部署

本地開發時載入 env