Cloudflare Workers

Cloudflare Workers 是 Cloudflare CDN 上的 JavaScript 边缘运行时。

您可以使用 Wrangler 在本地开发应用程序并使用几个命令发布它。Wrangler 包含转译器，因此我们可以使用 TypeScript 编写代码。

让我们使用 Hono 为 Cloudflare Workers 创建您的第一个应用程序。

1. 设置

Cloudflare Workers 的入门程序可用。使用“create-hono”命令开始您的项目。在此示例中，选择cloudflare-workers 模板。

npm

npm create hono@latest my-app

yarn

yarn create hono my-app

pnpm

pnpm create hono my-app

bun

bunx create-hono my-app

deno

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

移动到my-app 并安装依赖项。

npm

cd my-app
npm i

yarn

cd my-app
yarn

pnpm

cd my-app
pnpm i

bun

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. 运行

在本地运行开发服务器。然后，在您的 Web 浏览器中访问https://127.0.0.1:8787。

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

4. 部署

如果您有 Cloudflare 帐户，您可以部署到 Cloudflare。在package.json 中，$npm_execpath 需要更改为您的包管理器。

npm

npm run deploy

yarn

yarn deploy

pnpm

pnpm run deploy

bun

bun run deploy

就这样！

服务工作者模式或模块工作者模式

编写 Cloudflare Workers 有两种语法。模块工作者模式和服务工作者模式。使用 Hono，您可以使用两种语法编写，但我们建议您使用模块工作者模式，以便绑定变量本地化。

// Module Worker
export default app

// Service Worker
app.fire()

使用 Hono 与其他事件处理程序

您可以在模块工作者模式中将 Hono 与其他事件处理程序（例如scheduled）集成。

为此，将app.fetch 导出为模块的fetch 处理程序，然后根据需要实现其他处理程序

const app = new Hono()

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

提供静态文件

如果您想提供静态文件，可以使用 Cloudflare Workers 的 静态资产功能。在wrangler.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。

npm

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

yarn

yarn add -D @cloudflare/workers-types

pnpm

pnpm add -D @cloudflare/workers-types

bun

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 存储桶或持久对象。您可以在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!`)
})

在中间件中使用变量

这是模块工作者模式的唯一情况。如果您想在中间件中使用变量或秘密变量，例如基本身份验证中间件中的“用户名”或“密码”，您需要像以下这样编写。

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 工作者之间不共享）。

然后转到您的 Github 存储库设置仪表板：Settings->Secrets and variables->Actions->Repository secrets，并添加一个名为CLOUDFLARE_API_TOKEN 的新秘密。

然后在您的 hono 项目根文件夹中创建.github/workflows/deploy.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 行之后添加此代码。

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

一切准备就绪！现在推送代码并享受它。

在本地开发时加载环境

要配置本地开发的环境变量，请在项目的根目录中创建.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