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

bun create hono@latest my-app

deno init --npm 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. 运行

在本地运行开发服务器，然后在浏览器中访问 http://localhost:8787。

npmyarnpnpmbun

npm run dev

yarn dev

pnpm dev

bun run dev

更改端口号

如果需要更改端口号，可以按照此处的说明更新 wrangler.toml / wrangler.json / wrangler.jsonc 文件： Wrangler 配置

也可以按照此处的说明设置 CLI 选项： Wrangler CLI

4. 部署

如果拥有 Cloudflare 账户，就可以部署到 Cloudflare。需要在 package.json 中将 $npm_execpath 改为你选择的包管理器。

npmyarnpnpmbun

npm run deploy

yarn deploy

pnpm run deploy

bun run deploy

就是这样！

将 Hono 与其他事件处理函数结合使用

在 Module Worker 模式下，可以将 Hono 与其他事件处理函数（例如 scheduled）结合使用。

为此，将 app.fetch 导出为模块的 fetch 处理函数，再按需实现其他处理函数：

const app = new Hono()

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

提供静态文件

如果要提供静态文件，可以使用 Cloudflare Workers 的静态资源功能。在 wrangler.jsonc 中指定文件目录：

jsonc

"assets": { "directory": "public" }

然后创建 public 目录并将文件放入其中。例如，./public/static/hello.txt 会以 /static/hello.txt 的路径提供。

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

类型

如果需要 Workers 类型，必须安装 @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('http://localhost/')
    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!`)
})

自动生成绑定类型

无需手动定义绑定类型，可以使用 wrangler types 命令根据 wrangler.toml 自动生成。使用 --env-interface 标志，避免与 Hono 内置的 Env 类型发生命名冲突：

wrangler types --env-interface CloudflareBindings

这会生成一个 worker-configuration.d.ts 文件，接口名称就是你指定的名称。然后将其传给 Hono：

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

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!`)
})

在中间件中使用变量

此方式仅适用于 Module 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 Actions 部署

通过 CI 向 Cloudflare 部署代码前，需要一个 Cloudflare 令牌。可以在用户 API 令牌中管理它。

如果创建新令牌，请选择 Edit Cloudflare Workers 模板。如果已有其他令牌，请确保它具备相应权限。

然后进入 GitHub 仓库设置页面：Settings->Secrets and variables->Actions->Repository secrets，添加一个名为 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.jsonc，在 compatibility_date 行后添加以下代码。

jsonc

"main": "src/index.ts",
"minify": true

一切就绪！现在推送代码即可。

本地开发时加载环境变量

要配置本地开发的环境变量，请在项目根目录中创建 .dev.vars 或 .env 文件。这些文件应采用 dotenv 语法。例如：

SECRET_KEY=value
API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

本节的更多信息请参阅 Cloudflare 文档： https://developers.cloudflare.com/workers/wrangler/configuration/#secrets

然后在代码中使用 c.env.* 获取环境变量。

说明

Cloudflare Workers 默认无法使用 process.env，因此建议通过 c.env 获取环境变量。如果要使用它，需要启用 nodejs_compat_populate_process_env 标志。也可以从 cloudflare:workers 中导入 env。详情请参阅 Cloudflare 文档中访问 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 Workers 项目配置中设置环境变量和机密。

本节的更多信息请参阅 Cloudflare 文档： https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard

Cloudflare Workers ​

1. 初始化 ​

2. Hello World ​

3. 运行 ​

更改端口号 ​

4. 部署 ​

将 Hono 与其他事件处理函数结合使用 ​

提供静态文件 ​

类型 ​

测试 ​

绑定 ​

自动生成绑定类型 ​

在中间件中使用变量 ​

通过 GitHub Actions 部署 ​

本地开发时加载环境变量 ​

Cloudflare Workers

1. 初始化

2. Hello World

3. 运行

更改端口号

4. 部署

将 Hono 与其他事件处理函数结合使用

提供静态文件

类型

测试

绑定

自动生成绑定类型

在中间件中使用变量

通过 GitHub Actions 部署

本地开发时加载环境变量