S00-00 General-Cloudflare-Wrangler、Hono

[TOC]

Wrangler

你想了解 Cloudflare Wrangler 的常用命令，首先需要明确：Wrangler 是 Cloudflare 官方提供的命令行工具（CLI），专门用于管理、开发、调试和部署 Cloudflare 生态下的项目（核心是 Workers、Pages，还支持 KV、D1、Durable Objects 等周边服务），是 Cloudflare 开发者的核心工具。下面按「命令用途分类」详细介绍常用命令，附带用法、作用和关键参数。

基础前置命令

这是使用 Wrangler 的第一步，完成环境准备和项目初始化。

安装 Wrangler

~~安装 Wrangler（全局安装）~~:

支持多种包管理器，核心命令如下（推荐 npm）：

bash

# npm 全局安装（最常用）
npm install -g wrangler

# yarn 全局安装
yarn global add wrangler

# pnpm 全局安装
pnpm add -g wrangler

# 验证安装成功（查看版本）
wrangler -v  # 简写，等价于 wrangler version

作用：将 Wrangler 安装到本地环境，使其可以在任意终端目录下调用。

登录 Cloudflare 账户

~~登录 Cloudflare 账户（授权 Wrangler）~~:

bash

# 交互式登录（推荐，自动打开浏览器授权）
wrangler login

# 无浏览器环境登录（如服务器，手动提供 API Token）
wrangler login --api-token

作用：授权 Wrangler 访问你的 Cloudflare 账户资源，登录后会在本地保存加密凭证，无需重复授权。授权成功后，Wrangler 会关联你的 Cloudflare 账户 ID、域名等资源。

初始化新项目

~~初始化新项目（wrangler init）~~:

bash

# 交互式初始化（默认，会提问项目信息）
wrangler init [project-name]  # project-name 可选，不填则在当前目录初始化

# 非交互式初始化（跳过提问，使用默认配置）
wrangler init [project-name] --yes  # 简写 -y

# 指定项目类型初始化（如 Worker、Pages、Durable Object）
wrangler init [project-name] --type worker  # 初始化 Worker 项目（默认类型）
wrangler init [project-name] --type pages    # 初始化 Pages 项目

作用：在指定目录创建一个标准的 Cloudflare 项目结构，自动生成核心配置文件 wrangler.toml（项目配置核心）、入口代码文件（如 src/index.ts）、依赖配置文件等。 生成的核心文件：wrangler.toml 是后续所有命令的配置基础，大部分项目配置（部署环境、KV 关联、环境变量等）都在此文件中定义。

开发调试命令

这类命令用于本地模拟 Cloudflare 运行环境，调试项目代码，避免直接部署到线上排查问题。

本地开发服务器

~~本地开发服务器（wrangler dev）~~:

bash

# 启动本地开发服务器（默认端口 8787）
wrangler dev

# 指定端口启动
wrangler dev --port 3000  # 简写 -p 3000

# 指定项目环境启动（对应 wrangler.toml 中配置的 env）
wrangler dev --env production  # 如生产环境、测试环境

# Pages 项目启动（指定静态资源目录）
wrangler dev ./public

核心作用：

启动本地模拟服务器，复刻 Cloudflare 线上运行环境，支持 Worker/Pages 代码的本地执行；
开启热重载，修改代码后无需重启命令，自动刷新生效；
终端实时输出日志（请求信息、错误堆栈等），方便调试；
本地访问 http://localhost:8787 即可预览项目效果，与线上部署效果高度一致。

实时查看线上日志

~~实时查看线上日志（wrangler tail）~~:

bash

# 实时流式查看已部署项目的日志（默认跟随，类似 tail -f）
wrangler tail [worker-name]  # worker-name 可选，未指定则使用 wrangler.toml 中配置的项目名

# 指定环境查看日志
wrangler tail --env staging

# 过滤日志级别（仅查看 error 级别日志）
wrangler tail --log-level error  # 支持 info/warn/error 三个级别

# 过滤指定请求的日志（通过请求 ID）
wrangler tail --request-id <REQUEST_ID>

作用：线上项目部署后，实时查看运行日志，用于线上问题排查，不会遗漏实时产生的请求日志、错误信息，是线上调试的核心命令。

部署发布命令

将本地开发完成的项目部署到 Cloudflare 线上平台，供用户访问。

项目部署

~~项目部署（wrangler deploy）~~:

bash

# 默认部署（根据 wrangler.toml 配置，默认部署到预览环境或生产环境）
wrangler deploy

# 指定环境部署
wrangler deploy --env production

# 强制部署（忽略部分配置校验，紧急上线时可用）
wrangler deploy --force

# Pages 项目部署（指定静态资源构建目录）
wrangler pages deploy ./dist

# 指定自定义配置文件部署
wrangler deploy --config ./wrangler.custom.toml

核心作用：

将本地项目打包、上传并部署到 Cloudflare 平台，生成可公开访问的 URL（如 xxx.workers.dev 或自定义域名）；
部署完成后，终端会输出项目访问地址、部署 ID、环境信息等；
支持增量部署，仅上传修改的代码片段，提升部署效率。

临时线上预览

~~临时线上预览（wrangler preview，新版可整合到 dev）~~:

bash

# 创建临时线上预览环境（不影响生产环境）
wrangler preview

# 实时同步本地修改到预览环境
wrangler preview --watch

作用：创建一个临时的线上预览地址，用于向他人展示效果或验证线上环境兼容性，预览环境不会替代正式部署的项目，过期后自动失效，适合测试和演示。

环境变量与秘密值管理

Cloudflare 项目中，普通环境变量可直接配置在 wrangler.toml，但敏感信息（如 API 密钥、数据库密码）必须通过 Wrangler 命令管理为「秘密值（Secret）」，加密存储且不暴露明文。

添加/更新秘密值

~~添加/更新秘密值（wrangler secret put）~~:

bash

# 交互式添加秘密值（运行后会提示输入秘密值，输入时不显示明文）
wrangler secret put <SECRET_NAME>  # 如 wrangler secret put API_KEY

# 管道输入秘密值（非交互式，适合脚本自动化）
echo "my-sensitive-api-key" | wrangler secret put API_KEY

作用：将敏感信息加密存储到 Cloudflare 后台，关联当前项目，在代码中可通过 env.SECRET_NAME 访问（如 env.API_KEY），秘密值不会在 wrangler.toml 中留存，也不会在部署日志中暴露。

列出所有秘密值名称

~~列出所有秘密值名称（wrangler secret list）~~:

bash

wrangler secret list

作用：查看当前项目已配置的所有秘密值名称（仅显示名称，不显示具体值，保证安全），用于确认敏感信息是否已配置。

删除秘密值

~~删除秘密值（wrangler secret delete）~~:

bash

wrangler secret delete <SECRET_NAME>  # 如 wrangler secret delete API_KEY

作用：删除指定的秘密值，删除后代码中无法再访问该值，需谨慎操作。

项目配置与账户信息查询

查看当前登录账户信息

~~查看当前登录账户信息（wrangler whoami / wrangler info）~~:

bash

# 简洁查看账户信息（账户 ID、邮箱、用户名）
wrangler whoami

# 详细查看账户信息（含已关联的 Worker、Pages、KV 等资源）
wrangler info

作用：确认当前 Wrangler 关联的 Cloudflare 账户，获取账户 ID（常用于 wrangler.toml 配置），排查账户授权问题。

管理 Wrangler 全局配置

~~管理 Wrangler 全局配置（wrangler config）~~:

bash

# 查看全局配置列表
wrangler config list

# 重新配置全局账户凭证（覆盖现有本地授权）
wrangler config

# 删除指定全局配置项
wrangler config unset <CONFIG_KEY>

作用：管理 Wrangler 的全局配置，无需重新登录即可更新账户关联或调整全局参数。

快速打开官方文档

~~快速打开官方文档（wrangler docs）~~:

bash

wrangler docs

作用：自动在浏览器中打开 Cloudflare Workers/Pages 的官方文档，方便快速查阅开发指南和 API 参考。

其他实用辅助命令

登出当前账户

~~登出当前账户（wrangler logout）~~:

bash

wrangler logout

作用：清除本地存储的 Cloudflare 账户授权凭证，登出后需重新运行 wrangler login 才能继续操作。

升级 Wrangler 到最新版本

~~升级 Wrangler 到最新版本（wrangler upgrade）~~:

bash

wrangler upgrade

作用：快速将本地 Wrangler 升级到官方最新版本，获取新功能和 bug 修复（等价于 npm update -g wrangler，更便捷）。

KV 命名空间管理

~~KV 命名空间管理（补充，常用周边服务命令）~~:

Cloudflare KV 是持久化键值存储服务，相关常用命令：

bash

# 创建 KV 命名空间
wrangler kv:namespace create <NAMESPACE_NAME>  # 如 wrangler kv:namespace create USER_DATA

# 列出所有 KV 命名空间
wrangler kv:namespace list

# 向 KV 命名空间添加键值对
wrangler kv:key put <KEY> <VALUE> --namespace-id <NAMESPACE_ID>

使用小贴士

wrangler.toml 是项目核心配置文件，大部分命令的默认行为都由该文件决定，命令行参数会覆盖配置文件中的对应设置；
开发优先使用 wrangler dev 本地调试，避免频繁部署线上排查问题，提升开发效率；
敏感信息务必使用 wrangler secret 系列命令管理，切勿明文写入 wrangler.toml 或提交到代码仓库；
若对某个命令的用法存疑，可添加 --help 参数查看详细说明（如 wrangler dev --help）。

总结

Wrangler 的常用命令可归纳为三大核心场景：

基础准备：install（安装）→ login（登录）→ init（初始化）；
开发调试：dev（本地开发）→ tail（线上日志）；
上线与管理：deploy（部署）→ secret（敏感信息管理）→ whoami（账户查询）。

掌握这些命令即可满足 Cloudflare Workers/Pages 项目的绝大部分开发、部署和运维需求。

Hono

你想详细了解在 Cloudflare 生态（尤其是 Workers/Pages 场景）中使用的 Hono 框架，包括它的定位、核心特性、与 Cloudflare 的适配方式，以及具体的使用方法和实战示例。接下来我会从「基础认知→核心优势→实战使用→进阶功能」全面讲解 Hono，重点聚焦它在 Cloudflare 环境下的应用。

Hono 是什么？

Hono（日语意为「炎」，象征「快速」）是一款轻量、高性能、跨平台的 Web 框架，专为「边缘计算场景」设计（如 Cloudflare Workers/Pages、Vercel Edge Functions、Deno Deploy 等）。

相比于传统 Web 框架（如 Express），Hono 最大的特点是：

极致轻量化：核心代码仅 ~10KB（无冗余依赖），完美适配 Cloudflare Workers 的脚本大小限制（默认 1MB 以内）；
原生适配边缘环境：针对 Cloudflare Workers 的运行时（V8 引擎、无 Node.js 环境）做了深度优化，无需额外兼容层；
高性能路由：采用 Radix Tree（基数树）算法实现路由匹配，比传统正则路由快数倍，边缘场景下响应延迟更低。

简单来说：Hono 是 Cloudflare Workers/Pages 开发的「首选框架」，兼顾轻量、性能和开发体验，是替代原生 Workers 原生代码（纯 Fetch API 编写）的最佳选择。

Hono 核心优势

~~Hono 核心优势（针对 Cloudflare 场景）~~:

零(Node.js)依赖：Cloudflare Workers 运行时基于 V8 引擎，不支持 Node.js 核心模块（如 fs/http），Hono 完全基于 Web Standard API（Fetch、Request、Response）开发，无需任何 polyfill；
TypeScript 原生支持：自带完善的类型定义，开发时类型提示精准，避免边缘场景下的类型错误；
丰富的内置功能：路由、中间件、参数解析、CORS、认证、Cookie 处理等，无需额外安装插件；
无缝衔接 Cloudflare 服务：可直接调用 Cloudflare KV、D1（SQL 数据库）、Durable Objects、R2（对象存储）等周边服务；
开发体验友好：API 设计简洁（类似 Express/Koa），学习成本低，新手可快速上手。

前置准备

~~前置准备（与 Wrangler 配合）~~:

在 Cloudflare 中使用 Hono，需先完成基础环境搭建（承接上一期讲的 Wrangler）：

已安装 Wrangler（npm install -g wrangler）；
已登录 Cloudflare 账户（wrangler login）。

Hono 快速上手

~~Hono 快速上手（Cloudflare Workers 实战）~~:

步骤 1：初始化 Worker 项目：

bash

# 初始化一个 Worker 项目（交互式，一路回车即可）
wrangler init hono-cloudflare-demo
# 进入项目目录
cd hono-cloudflare-demo

步骤 2：安装 Hono：

bash

# 安装 Hono（仅需安装到项目依赖）
npm install hono

步骤 3：编写基础 Hono 应用：

替换项目中 src/index.ts 的内容（核心代码）：

typescript

// src/index.ts
import { Hono } from 'hono'

// 1. 创建 Hono 应用实例
const app = new Hono()

// 2. 基础路由（GET 请求）
app.get('/', (c) => {
  // c = Context（上下文），包含 Request/Response/参数等核心信息
  return c.text('Hello Hono on Cloudflare Workers! 🚀')
})

// 3. 路径参数路由（动态参数）
app.get('/user/:id', (c) => {
  // 获取路径参数 id
  const id = c.req.param('id')
  return c.json({
    message: `Hello User ${id}`,
    timestamp: new Date().toISOString()
  })
})

// 4. 查询参数路由
app.get('/search', (c) => {
  // 获取查询参数 q（如 /search?q=hono）
  const query = c.req.query('q') || 'empty'
  return c.text(`Search query: ${query}`)
})

// 5. POST 请求（解析 JSON 体）
app.post('/api/data', async (c) => {
  // 解析请求体为 JSON
  const data = await c.req.json()
  return c.json({
    received: true,
    data,
    env: c.env // 可访问 Cloudflare 环境变量/Secret
  })
})

// 6. 导出 Cloudflare Workers 处理函数
export default app.fetch

步骤 4：本地调试：

~~步骤 4：本地调试（Wrangler + Hono）~~:

bash

# 启动本地开发服务器（默认端口 8787）
wrangler dev

启动后访问以下地址验证效果：

http://localhost:8787 → 输出 Hello Hono on Cloudflare Workers! 🚀
http://localhost:8787/user/123 → 输出 JSON { "message": "Hello User 123", ... }
http://localhost:8787/search?q=hono → 输出 Search query: hono

步骤 5：部署到 Cloudflare 线上：

bash

# 部署到 Cloudflare Workers 线上环境
wrangler deploy

部署完成后，终端会输出线上访问地址（如 https://hono-cloudflare-demo.<你的账户>.workers.dev），功能与本地完全一致。

Hono 核心功能

中间件（Middleware）

Hono 支持中间件机制，可统一处理日志、认证、CORS 等逻辑，以下是 Cloudflare 常用的内置中间件示例：

typescript

import { Hono } from 'hono'
import { cors, logger, basicAuth } from 'hono/middleware'

const app = new Hono()

// 1. 日志中间件（终端输出请求信息）
app.use(logger())

// 2. CORS 中间件（解决跨域，Cloudflare 场景必备）
app.use(
  cors({
    origin: '*', // 生产环境建议指定具体域名
    allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowHeaders: ['Content-Type', 'Authorization']
  })
)

// 3. 基础认证中间件（保护特定路由）
app.use(
  '/admin/*',
  basicAuth({
    username: 'admin',
    password: 'cloudflare123'
  })
)

// 受保护的路由
app.get('/admin/dashboard', (c) => {
  return c.text('Admin Dashboard (Authenticated)')
})

export default app.fetch

访问 Cloudflare 特有服务

~~访问 Cloudflare 特有服务（以 KV 为例）~~:

Hono 可直接通过 c.env 访问 Cloudflare KV（需先在 wrangler.toml 配置 KV 命名空间）：

步骤 1：配置 KV 命名空间：

修改 wrangler.toml，添加 KV 关联：

toml

name = "hono-cloudflare-demo"
main = "src/index.ts"
compatibility_date = "2026-01-24"

# 添加 KV 命名空间（先通过 wrangler kv:namespace create USER_DATA 创建）
[[kv_namespaces]]
binding = "USER_DATA" # 绑定名，代码中通过 c.env.USER_DATA 访问
id = "<你的 KV 命名空间 ID>" # 创建 KV 后会输出该 ID

步骤 2：在 Hono 中操作 KV：

typescript

app.get('/kv/set/:key/:value', async (c) => {
  const key = c.req.param('key')
  const value = c.req.param('value')
  // 写入 KV
  await c.env.USER_DATA.put(key, value)
  return c.text(`KV set: ${key} = ${value}`)
})

app.get('/kv/get/:key', async (c) => {
  const key = c.req.param('key')
  // 读取 KV
  const value = (await c.env.USER_DATA.get(key)) || 'Not found'
  return c.json({ key, value })
})

在 Cloudflare Pages 中使用 Hono

~~在 Cloudflare Pages 中使用 Hono~~:

Cloudflare Pages 支持「Pages Functions」（边缘函数），Hono 也可无缝适配，只需调整目录结构和导出方式：

your-pages-project/
├── public/          # 静态资源目录
└── functions/       # Pages Functions 目录
    └── [[path]].ts  # 通配路由文件（核心）

functions/[[path]].ts 代码示例：

typescript

import { Hono } from 'hono'
import { handle } from 'hono/cloudflare-pages'

const app = new Hono()

app.get('/', (c) => c.text('Hello Hono on Cloudflare Pages!'))
app.get('/about', (c) => c.text('About Page'))

// 适配 Pages Functions 导出方式
export const onRequest = handle(app)

Hono vs 原生Cloudflare

维度	Hono 框架	Cloudflare 原生代码（Fetch API）
开发效率	高（路由、中间件开箱即用）	低（需手动处理路由、参数解析）
代码体积	~10KB（轻量化）	更小（但功能简陋）
可维护性	高（模块化、语义化）	低（代码冗余，易混乱）
学习成本	低（类似 Express）	中（需熟悉 Fetch API 细节）

常用属性与方法

你需要一份格式规整、无错乱的 Hono 核心属性/方法解析，我会彻底放弃易出错的表格嵌套代码块形式，改用「模块拆分 + 独立代码块 + 清晰层级」的结构，完整覆盖 Cloudflare 场景下 Hono 的高频属性和方法，确保阅读体验和信息完整性。

核心前提

Hono 开发中最核心的两个对象是：

Hono 实例：通过 new Hono() 创建，用于定义路由、注册中间件、配置全局规则；
Context（上下文）对象：简称 c，是路由/中间件的唯一参数，封装了请求、响应、Cloudflare 环境资源等所有核心能力。

Hono 实例的常用方法

Hono 实例（通常命名为 app）是构建应用的基础，以下是高频使用的方法，每个方法单独说明，代码块独立展示：

HTTP 路由注册方法

~~HTTP 路由注册方法（get/post/put/delete/patch/all）~~:

语法：app.METHOD(path, handler)
作用：注册对应 HTTP 方法的路由，all 可匹配所有 HTTP 方法（GET/POST/OPTIONS 等）。
Cloudflare 示例：

typescript

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

// GET 路由：返回纯文本响应
app.get('/', (c) => c.text('Hello Cloudflare Hono! 🚀'))

// POST 路由：解析 JSON 请求体并返回
app.post('/api/data', async (c) => {
  const data = await c.req.json()
  return c.json({ received: data, code: 200 })
})

// all 路由：匹配所有 HTTP 方法
app.all('/any-method', (c) => c.text(`Matched method: ${c.req.method}`))

中间件注册方法

~~中间件注册方法（use）~~:

语法：app.use([path], middleware)
作用：注册全局或局部中间件，用于拦截请求/响应（如日志、认证、CORS 处理），path 可选，不传则为全局中间件。
Cloudflare 示例：

typescript

// 全局中间件：记录请求日志 + 设置响应头
app.use(async (c, next) => {
  // 请求处理前：打印日志（Cloudflare 终端可见）
  console.log(`Request URL: ${c.req.url}`)
  // 执行后续路由/中间件
  await next()
  // 请求处理后：设置自定义响应头
  c.res.headers.set('X-Powered-By', 'Hono + Cloudflare Workers')
})

// 局部中间件：仅 /admin 前缀路由生效的基础认证
import { basicAuth } from 'hono/basic-auth'
app.use(
  '/admin/*',
  basicAuth({
    username: 'admin',
    password: 'cloudflare123'
  })
)
app.get('/admin/dashboard', (c) => c.text('Admin Dashboard (Authenticated)'))

路由分组方法

~~路由分组方法（route）~~:

语法：app.route(prefix, subApp)
作用：模块化管理路由，将子路由挂载到指定前缀下，提升代码可维护性。
Cloudflare 示例：

typescript

// 创建子路由实例
const userRouter = new Hono()
userRouter.get('/:id', (c) => c.text(`User ID: ${c.req.param('id')}`))
userRouter.post('/create', (c) => c.json({ msg: 'User created' }))

// 挂载到 /api/user 前缀，访问 /api/user/123 即可匹配
app.route('/api/user', userRouter)

全局基础路径设置

~~全局基础路径设置（basePath）~~:

语法：app.basePath(path)
作用：为所有路由添加全局前缀，适配 Cloudflare 多环境部署（如测试环境 /staging）。
Cloudflare 示例：

typescript

// 所有路由默认带 /v1 前缀，需访问 /v1/hello 才能匹配
app.basePath('/v1').get('/hello', (c) => c.text('Hello /v1/hello!'))

自定义 404 响应

~~自定义 404 响应（notFound）~~:

语法：app.notFound(handler)
作用：覆盖 Cloudflare 默认的 404 响应，返回自定义内容。
Cloudflare 示例：

typescript

app.notFound((c) => {
  c.status(404) // 设置响应状态码
  return c.json({
    error: 'Not Found',
    path: c.req.path,
    tip: 'Check your request path!'
  })
})

全局错误处理

~~全局错误处理（onError）~~:

语法：app.onError(handler)
作用：捕获所有路由/中间件中的异常，返回统一的错误响应，避免暴露原始错误堆栈。
Cloudflare 示例：

typescript

app.onError((err, c) => {
  // 打印错误到 Cloudflare 日志
  console.error(`Server Error: ${err.message}`)
  // 返回自定义 500 响应
  c.status(500)
  return c.json({
    error: 'Internal Server Error',
    message: err.message,
    env: 'cloudflare'
  })
})

// 测试错误路由
app.get('/error', () => {
  throw new Error('Test error for Hono on Cloudflare')
})

Context

c 是路由/中间件的核心参数，以下按「请求处理、环境资源、响应返回」三大模块拆分，清晰展示高频用法：

模块 1：c.req 请求处理

c.req 封装了所有请求相关信息，是读取客户端请求的核心入口，常用属性/方法如下：

基础请求信息

~~基础请求信息~~：

typescript

app.get('/req-info', (c) => {
  // 完整请求 URL（如 https://xxx.workers.dev/req-info?name=cf）
  const url = c.req.url
  // 请求路径（不含域名/查询参数，如 /req-info）
  const path = c.req.path
  // HTTP 方法（如 GET/POST）
  const method = c.req.method
  // 协议（如 https）
  const protocol = c.req.protocol

  return c.json({ url, path, method, protocol })
})

路径参数解析

~~路径参数解析（param）~~:

typescript

// 路由定义：/user/:id/:name（动态参数）
app.get('/user/:id/:name', (c) => {
  // 获取单个参数
  const id = c.req.param('id')
  const name = c.req.param('name')
  // 获取所有参数（返回对象）
  const allParams = c.req.param() // { id: '123', name: 'cloudflare' }

  return c.json({ id, name, allParams })
})

查询参数解析

~~查询参数解析（query）~~:

typescript

// 访问示例：/search?q=hono&page=1&size=10
app.get('/search', (c) => {
  // 获取单个查询参数
  const q = c.req.query('q') // 'hono'
  const page = c.req.query('page') // '1'
  // 获取所有查询参数（返回对象）
  const allQuery = c.req.query() // { q: 'hono', page: '1', size: '10' }

  return c.json({ q, page, allQuery })
})

请求头解析

~~请求头解析（header）~~:

typescript

app.get('/headers', (c) => {
  // 获取单个请求头
  const auth = c.req.header('Authorization') || ''
  const userAgent = c.req.header('User-Agent') || ''
  // 获取所有请求头（返回对象）
  const allHeaders = c.req.header()

  return c.json({ auth, userAgent, allHeaders })
})

请求体解析

~~请求体解析（json/text/formData）~~:

typescript

// 解析 JSON 体
app.post('/json-body', async (c) => {
  const data = await c.req.json()
  return c.json({ received: data })
})

// 解析纯文本体
app.post('/text-body', async (c) => {
  const text = await c.req.text()
  return c.text(`Received text: ${text}`)
})

// 解析表单体（form-data/x-www-form-urlencoded）
app.post('/form-body', async (c) => {
  const form = await c.req.formData()
  const username = form.get('username') || ''
  return c.json({ username })
})

模块 2：c.env 环境资源访问

c.env 是访问 Cloudflare 专属资源的核心入口，直接关联 wrangler.toml 中配置的绑定，常用场景如下：

访问 KV 命名空间

typescript

// 前提：wrangler.toml 中已配置 KV 绑定（binding: "USER_DATA"）
app.get('/kv/:key', async (c) => {
  const key = c.req.param('key')
  // 读取 KV 数据
  const value = await c.env.USER_DATA.get(key)
  // 写入 KV 数据
  // await c.env.USER_DATA.put(key, JSON.stringify({ name: 'cf' }))

  return c.json({ key, value: value || 'Not found' })
})

访问 D1 数据库

typescript

// 前提：wrangler.toml 中已配置 D1 绑定（binding: "MY_DB"）
app.get('/d1/users', async (c) => {
  // 执行 D1 查询
  const { results } = await c.env.MY_DB.prepare('SELECT * FROM users WHERE id = ?').bind(123).all()

  return c.json({ users: results })
})

访问 Secret 秘密值

typescript

// 前提：已通过 wrangler secret put API_KEY 设置秘密值
app.get('/secret', (c) => {
  // 读取加密的秘密值（不会暴露明文）
  const apiKey = c.env.API_KEY
  return c.json({ apiKey: '******' }) // 避免返回明文
})

访问 R2 对象存储

typescript

// 前提：wrangler.toml 中已配置 R2 绑定（binding: "MY_BUCKET"）
app.get('/r2/:filename', async (c) => {
  const filename = c.req.param('filename')
  // 读取 R2 存储中的文件
  const object = await c.env.MY_BUCKET.get(filename)
  if (!object) return c.text('File not found', { status: 404 })

  return new Response(object.body, {
    headers: {
      'Content-Type': object.httpMetadata.contentType || 'application/octet-stream'
    }
  })
})

模块 3：响应返回

c 提供了简洁的响应方法，替代原生 new Response()，常用方法如下：

纯文本响应

~~纯文本响应（text）~~:

typescript

app.get('/text', (c) => {
  // 支持自定义状态码和响应头
  return c.text('Success!', {
    status: 200,
    headers: { 'X-Custom-Header': 'hono-cf' }
  })
})

JSON 响应

~~JSON 响应（json）~~:

typescript

app.get('/json', (c) => {
  // 自动设置 Content-Type: application/json
  return c.json(
    {
      code: 200,
      msg: 'OK',
      data: { name: 'Cloudflare Hono' }
    },
    { status: 200 }
  )
})

HTML 响应

~~HTML 响应（html）~~:

typescript

app.get('/html', (c) => {
  return c.html(`
    <!DOCTYPE html>
    <html>
      <head><title>Hono on Cloudflare</title></head>
      <body><h1>Hello Hono! 🎉</h1></body>
    </html>
  `)
})

重定向响应

~~重定向响应（redirect）~~:

typescript

app.get('/redirect', (c) => {
  // 支持自定义状态码（301 永久重定向，302 临时重定向）
  return c.redirect('/target', 302)
})

自定义响应

~~自定义响应（Response）~~:

typescript

app.get('/custom-res', (c) => {
  // 直接返回原生 Response 对象，适配复杂场景
  return new Response('Custom Response', {
    status: 200,
    headers: { 'Content-Type': 'text/plain' }
  })
})

S00-00 General-Cloudflare-Wrangler、Hono ​

Wrangler ​

基础前置命令 ​

安装 Wrangler ​

登录 Cloudflare 账户 ​

初始化新项目 ​

开发调试命令 ​

本地开发服务器 ​

实时查看线上日志 ​

部署发布命令 ​

项目部署 ​

临时线上预览 ​

环境变量与秘密值管理 ​

添加/更新秘密值 ​

列出所有秘密值名称 ​

删除秘密值 ​

项目配置与账户信息查询 ​

查看当前登录账户信息 ​

管理 Wrangler 全局配置 ​

快速打开官方文档 ​

其他实用辅助命令 ​

登出当前账户 ​

升级 Wrangler 到最新版本 ​

KV 命名空间管理 ​

使用小贴士 ​

总结 ​

Hono ​

Hono 是什么？ ​

Hono 核心优势 ​

前置准备 ​

Hono 快速上手 ​

Hono 核心功能 ​

中间件（Middleware） ​

访问 Cloudflare 特有服务 ​

在 Cloudflare Pages 中使用 Hono ​

Hono vs 原生Cloudflare ​

常用属性与方法 ​

核心前提 ​

Hono 实例的常用方法 ​

HTTP 路由注册方法 ​

中间件注册方法 ​

路由分组方法 ​

全局基础路径设置 ​

自定义 404 响应 ​

全局错误处理 ​

Context ​

模块 1：c.req 请求处理 ​

基础请求信息 ​

路径参数解析 ​

查询参数解析 ​

请求头解析 ​

请求体解析 ​

模块 2：c.env 环境资源访问 ​

访问 KV 命名空间 ​

访问 D1 数据库 ​

访问 Secret 秘密值 ​

访问 R2 对象存储 ​

模块 3：响应返回 ​

纯文本响应 ​

JSON 响应 ​

HTML 响应 ​

重定向响应 ​

自定义响应 ​

S00-00 General-Cloudflare-Wrangler、Hono

Wrangler

基础前置命令

安装 Wrangler

登录 Cloudflare 账户

初始化新项目

开发调试命令

本地开发服务器

实时查看线上日志

部署发布命令

项目部署

临时线上预览

环境变量与秘密值管理

添加/更新秘密值

列出所有秘密值名称

删除秘密值

项目配置与账户信息查询

查看当前登录账户信息

管理 Wrangler 全局配置

快速打开官方文档

其他实用辅助命令

登出当前账户

升级 Wrangler 到最新版本

KV 命名空间管理

使用小贴士

总结

Hono

Hono 是什么？

Hono 核心优势

前置准备

Hono 快速上手

Hono 核心功能

中间件（Middleware）

访问 Cloudflare 特有服务

在 Cloudflare Pages 中使用 Hono

Hono vs 原生Cloudflare

常用属性与方法

核心前提

Hono 实例的常用方法

HTTP 路由注册方法

中间件注册方法

路由分组方法

全局基础路径设置

自定义 404 响应

全局错误处理

Context

模块 1：c.req 请求处理

基础请求信息

路径参数解析

查询参数解析

请求头解析

请求体解析

模块 2：c.env 环境资源访问

访问 KV 命名空间

访问 D1 数据库

访问 Secret 秘密值

访问 R2 对象存储

模块 3：响应返回

纯文本响应

JSON 响应

HTML 响应

重定向响应

自定义响应