Hyperdrive 常见陷阱

# 常见问题 (Gotchas) 查看 [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md)。 ## 常见错误 ### "Too many open connections" / "Connection limit exceeded" **原因：** Workers 每个调用有 **6 个并发连接** 的硬性限制。 **解决方案：** 在驱动配置中设置 `max: 5`，重用连接，确保使用 `client.end()` 或 `ctx.waitUntil(conn.end())` 正确清理。 ### "Failed to acquire a connection (Pool exhausted)" **原因：** 连接池中的所有连接都在使用中，通常是因为长时间运行的事务。 **解决方案：** 缩短事务持续时间，避免超过 60 秒的查询，不要在外部调用期间持有连接，或升级到付费计划以获得更多连接。 ### "connection_refused" **原因：** 数据库因防火墙、连接限制或服务关闭而拒绝连接。 **解决方案：** 检查防火墙是否允许 Cloudflare IP，验证数据库是否在端口上监听，确认服务正在运行，并验证凭据。 ### "Query timeout (deadline exceeded)" **原因：** 查询执行超过 60 秒的超时限制。 **解决方案：** 使用索引优化，通过 LIMIT 减少数据集，拆分为更小的查询，或使用异步处理。 ### "password authentication failed" **原因：** Hyperdrive 配置中的凭据无效。 **解决方案：** 检查 Hyperdrive 配置中的用户名和密码是否与数据库凭据匹配。 ### "SSL/TLS connection error" **原因：** Hyperdrive 和数据库之间的 SSL/TLS 配置不匹配。 **解决方案：** 添加 `sslmode=require` (Postgres) 或 `sslMode=REQUIRED` (MySQL)，如果是自签名证书则上传 CA 证书，验证数据库已启用 SSL，并检查证书是否过期。 ### "Queries not being cached" **原因：** 查询是修改类（INSERT/UPDATE/DELETE）、包含易变函数（NOW(), RANDOM()）或禁用了缓存。 **解决方案：** 验证查询是否为非修改类 SELECT，避免使用易变函数，确认已启用缓存，使用 `wrangler dev --remote` 进行测试，并为 postgres.js 设置 `prepare=true`。 ### "Slow multi-query Workers despite Hyperdrive" **原因：** Worker 在边缘执行，每个查询都要往返数据库区域。 **解决方案：** 启用智能放置 (`"placement": {"mode": "smart"}` in wrangler.jsonc) 以在数据库附近执行 Worker。参考 [patterns.md](./patterns.md) 中的多查询模式。 ### "Local database connection failed" **原因：** `localConnectionString` 不正确或数据库未运行。 **解决方案：** 验证 `localConnectionString` 是否正确，检查数据库是否正在运行，确认环境变量名称匹配