Workers 连接 Turso：@libsql/client/web 是唯一路径
Turso 是 libSQL（SQLite 分支），不能走 Hyperdrive；在 Workers 里必须用 @libsql/client/web 导入。
编辑与核验：橙宝书编辑团队 ·
先给结论
Turso 基于 libSQL，Hyperdrive 的支持列表不含 SQLite/libSQL，因此不能走 Hyperdrive。唯一路径是官方 @libsql/client，且在 Workers 里必须显式使用 @libsql/client/web 导入。
为什么只有一条路
Hyperdrive 池化的是 Postgres/MySQL 的 TCP 协议，libSQL 不在其支持范围内。好在 @libsql/client 的 HTTP 模式天然适合 Workers：每个请求就是一次 HTTPS 调用，不需要长连接。
免费额度约 100 个数据库、5GB 存储，足够原型与中小应用。
准备数据库与凭据
turso db create notes
turso db show notes --url # 形如 libsql://<db>-<user>.turso.io
turso db tokens create notes # 生成 auth token连接串与 token 分开存为 Secret：
npx wrangler secret put TURSO_DATABASE_URL
npx wrangler secret put TURSO_AUTH_TOKENtoken 不要写进 wrangler.jsonc 的 vars，也不要提交到仓库。泄露后在 Turso 侧重新生成并轮换。
Worker 代码
npm i @libsql/client导入路径决定能否运行
普通的 import { createClient } from '@libsql/client' 在 Workers 运行时不工作——它解析到依赖 Node 原生模块的构建。必须写成 @libsql/client/web。
import { createClient } from '@libsql/client/web';
interface Env {
TURSO_DATABASE_URL: string;
TURSO_AUTH_TOKEN: string;
}
export default {
async fetch(request, env: Env): Promise<Response> {
const client = createClient({
url: env.TURSO_DATABASE_URL,
authToken: env.TURSO_AUTH_TOKEN,
});
try {
const result = await client.execute('SELECT id, title FROM notes LIMIT 10');
return Response.json({ notes: result.rows });
} catch (error) {
return Response.json({ error: String(error) }, { status: 502 });
}
},
};该路径不需要任何 wrangler 绑定，配置只有两条 Secret。
验证与排障
curl -s https://<worker>.workers.dev/notes| 现象 | 先检查 | 恢复动作 |
|---|---|---|
| 构建或运行时报 Node 模块缺失 | 导入路径是否为 @libsql/client/web | 改导入路径后重新部署 |
401/403 | token 是否写错、被轮换或对应另一个库 | turso db tokens create 重建并 wrangler secret put 更新 |
| 连接串报协议错误 | URL 是否以 libsql:// 开头而非 https:// | 用 turso db show --url 的原始值 |
| 查询慢且无改善 | 是否期望 Hyperdrive 池化 | libSQL 不支持 Hyperdrive，改用应用层缓存（如 Cache API） |
远程边界与回滚
创建 Turso 数据库、生成 token、写入 Secret、部署 Worker 都会修改远程状态，本教程不自动执行。回滚时：代码侧删除相关路由并重新部署即可，Workers 不持有长连接，没有连接池需要排空；随后在 Cloudflare 侧删除 TURSO_DATABASE_URL 与 TURSO_AUTH_TOKEN 两条 Secret，并在 Turso 侧作废对应 token。若整个方案要回退到 D1，先导出数据再导入 D1，连接层代码按 D1 绑定重写——schema 是 SQLite 方言，迁移成本相对低，但仍需逐表验证。
下一步：Workers 连接 TiDB；选型回顾见外部数据库集成总览。
官方来源
这篇内容帮你完成目标了吗？
内测反馈只在当前浏览器生成，不会自动上传。