Cloudflare Hyperdrive 中文文档

参照官方手册结构整理（数据截至 2026-10，配额/价格以官方最新页面为准）。技术术语保留英文原词。

1. 概述

Hyperdrive 把你的既有区域数据库（Postgres / MySQL 及兼容库，含 AWS、GCP、Azure、Neon、PlanetScale 等）变成全球分布式数据库——它加速从全球各地、经 Workers 发起的查询，无需改写代码或更换工具。

一句话定位：为既有 Postgres/MySQL 加速并就近接入的边缘连接层（连接池 + 查询缓存）。

Free 与 Paid 计划均可用。

2. 核心概念

• 兼容任意 Postgres / MySQL：包括 CockroachDB、Timescale 等兼容库。
• 连接池（Connection Pooling）：Hyperdrive 维护到底层库的连接池，Worker 每次新建 client 都很快，绕过传统数据库的连接数瓶颈。
• 查询缓存（Query Caching）：对热门查询默认开启边缘缓存。
• 零代码改动：用现有驱动（如 pg、mysql2）与 ORM，只换连接串为 env.HYPERDRIVE.connectionString。

3. 架构与工作原理

Worker 通过 Hyperdrive 连接串访问数据库；Hyperdrive 在边缘做连接复用与查询缓存，把跨区域访问变快。它不限制来自 Worker 的并发客户端连接，但限制到底层源库的连接数（因为多数托管库有连接上限）。

4. 快速开始

wrangler.jsonc 绑定：

{ "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<hyperdrive-id>" }] }

import { Client } from "pg";

export default {
  async fetch(request, env): Promise<Response> {
    const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
    await client.connect();
    const res = await client.query("SELECT * FROM posts LIMIT 10");
    return Response.json(res.rows);
  },
} satisfies ExportedHandler<Env>;

5. 配额与限制

• 连接池耗尽会报 Failed to acquire a connection from the pool.；源库拒绝连接报 connection_refused。

6. 定价

• 连接池与查询缓存已包含在计划内，不额外收费。
• 无数据出网费；无论缓存与否、查询还是写入，均按上述查询数计量。
• 通过 Cloudflare 创建的 PlanetScale 数据库按 PlanetScale 标准价单列计费（与 Hyperdrive 用量分开）。

7. 最佳实践

• 把 Hyperdrive 连到已有的 Postgres/MySQL，让全球用户就近低延迟访问。
• 长事务/慢查询会占满连接池，注意控制查询时长（≤ 60 秒）。
• 纯 Cloudflare 原生新项目可优先考虑 D1；已有外部 SQL 库则 Hyperdrive 最省力。

8. 适用场景与选型

• 给既有 Postgres/MySQL 做全球加速、连接池与边缘缓存。
• 已有外部 SQL 数据库 → Hyperdrive；全新 Cloudflare 原生关系库 → D1；强一致状态协调 → Durable Objects。