Workers 连接 Supabase：supabase-js 或 Hyperdrive
用 @supabase/supabase-js 走 PostgREST，或用 Hyperdrive 池化直连 Postgres，按查询频率与冷启动要求二选一。
编辑与核验：橙宝书编辑团队 ·
先给结论
用 Supabase 的表 API、Auth、Storage 时选 @supabase/supabase-js（HTTP/PostgREST，天然适合 Workers）；需要原生 SQL、连接池和更低延迟时用 Hyperdrive + postgres.js 直连 Postgres。
两条路径怎么选
| 路径 | 适合 | 关键限制 |
|---|---|---|
@supabase/supabase-js | 表查询、行级安全（RLS）、Auth、Storage 全套 Supabase 功能 | 走 PostgREST，表达能力受 API 限制；无连接池收益 |
Hyperdrive + postgres.js | 原生 SQL、复杂事务、高频短查询 | 需要 Hyperdrive 配置；不支持 LISTEN/NOTIFY 与 advisory locks |
Supabase 免费计划的项目约 7 天无活动会自动暂停（可恢复）。暂停期间两条路径都会失败，排障时先在 Supabase Dashboard 确认项目状态。
路径一：supabase-js
npm i @supabase/supabase-js
npx wrangler secret put SUPABASE_URL
npx wrangler secret put SUPABASE_SERVICE_ROLE_KEYSUPABASE_URL 形如 https://<project-ref>.supabase.co，service role key 在 Supabase Dashboard 的 API 设置里。service key 能绕过 RLS，只能存在服务端 Secret 里，绝不能进前端包。
import { createClient } from '@supabase/supabase-js';
interface Env {
SUPABASE_URL: string;
SUPABASE_SERVICE_ROLE_KEY: string;
}
export default {
async fetch(request, env: Env): Promise<Response> {
const supabase = createClient(env.SUPABASE_URL, env.SUPABASE_SERVICE_ROLE_KEY);
const { data, error } = await supabase.from('notes').select('id,title').limit(10);
if (error) {
return Response.json({ error: error.message }, { status: 502 });
}
return Response.json({ notes: data });
},
};该路径不需要任何 wrangler 绑定，Secret 之外没有额外配置。
路径二：Hyperdrive 直连 Postgres
先在 Supabase Dashboard 的连接信息里拿到直连串，形如 postgres://USER:PASSWORD@HOST:PORT/postgres，然后创建 Hyperdrive 配置：
npx wrangler hyperdrive create supabase-pg --connection-string="postgres://USER:PASSWORD@HOST:PORT/postgres"{
"name": "notes-api",
"compatibility_date": "2026-08-25",
"compatibility_flags": ["nodejs_compat"],
"hyperdrive": [
{ "binding": "HYPERDRIVE", "id": "<创建命令返回的 id>" }
]
}import { Client } from 'pg';
interface Env {
HYPERDRIVE: Hyperdrive;
}
export default {
async fetch(request, env: Env): Promise<Response> {
const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
try {
await client.connect();
const result = await client.query('SELECT id, title FROM notes LIMIT 10');
return Response.json({ notes: result.rows });
} catch (error) {
return Response.json({ error: String(error) }, { status: 502 });
} finally {
await client.end().catch(() => {});
}
},
};用 postgres.js 时思路相同，把连接串换成 env.HYPERDRIVE.connectionString 即可。Hyperdrive 强制 TLS，Supabase 默认满足。
验证与排障
部署后用 curl 走一遍：
curl -s https://<worker>.workers.dev/notes| 现象 | 先检查 | 恢复动作 |
|---|---|---|
502 且报 fetch 失败 | Supabase 项目是否被自动暂停 | 在 Dashboard 恢复项目后重试 |
401/403 | service role key 是否写错或已轮换 | wrangler secret put 重写后重新部署 |
| Hyperdrive 路径连不上 | 连接串的 HOST/PORT 是否为直连地址而非池化地址 | 换用 Dashboard 里的 direct connection 串重建 Hyperdrive |
SQL 报 LISTEN 相关错误 | 是否用了 Hyperdrive 不支持的特性 | 改用轮询或 supabase-js 的 Realtime |
远程边界与回滚
创建 Hyperdrive 配置、写入 Supabase 密钥、部署 Worker 都会修改 Cloudflare 或 Supabase 侧状态，本教程不自动执行。回滚时：先在 wrangler.jsonc 删除 hyperdrive 绑定并重新部署，再用 wrangler hyperdrive delete <id> 删除配置；若轮换过 service role key，在 Supabase Dashboard 重新生成并把旧值作废。业务数据不受代码回滚影响，无需回退。
下一步：Workers 连接 Neon；绑定与密钥的通用规则见 Bindings、环境与 Secrets。
官方来源
这篇内容帮你完成目标了吗？
内测反馈只在当前浏览器生成，不会自动上传。