clickhouse-js-node-troubleshooting

ClickHouse Node.js 客户端故障排查

参考：https://clickhouse.com/docs/integrations/javascript

⚠️ 仅适用于 Node.js 运行时。 本技能仅涵盖在 Node.js 运行时 中运行的 @clickhouse/client 包，包括 Next.js Node 运行时 API 路由、React Server Components、Server Actions 和标准 Node.js 进程。请勿将本技能用于浏览器客户端组件、Web Workers、Next.js Edge 运行时、Cloudflare Workers，或任何 @clickhouse/client-web 用法。对于浏览器／边缘环境，正确的包是 @clickhouse/client-web。

---

如何使用本技能

1. 确定问题 — 将症状与下方的问题索引匹配，并阅读相应的参考文件。
2. 先说明诊断结果 — 在给出修复方案之前，先解释可能导致问题的原因。
3. 留意版本限制 — 标明修复方案所需的最低客户端版本，并核对是否符合用户提供的版本。
4. 只询问缺失的信息 — 如果修复方案取决于版本，而你不知道用户使用的版本，就询问；否则立即提供帮助。

---

问题索引

从下方列表中确定用户遇到的问题，并阅读对应的参考文件以获取详细的故障排除步骤。

问题	症状	参考文件
Socket 挂起 / ECONNRESET	socket hang up、ECONNRESET、间歇性连接断开、长时间运行的查询超时	reference/socket-hangup.md
数据类型不匹配	大整数以字符串形式返回、十进制精度丢失、插入 Date/DateTime 失败、向 UInt128 列插入 UUID 时出现 CANNOT_PARSE_INPUT_ASSERTION_FAILED	reference/data-types.md
只读用户错误	为 readonly=1 用户使用响应压缩时出错	reference/readonly-users.md
代理 / URL 路径名混淆	选择了错误的数据库、通过带路径前缀的代理发送请求时失败	reference/proxy-pathname.md
TLS / 证书错误	TLS 握手失败、证书验证问题、双向 TLS 设置	reference/tls.md
压缩不起作用	请求或响应未启用 GZIP 压缩	reference/compression.md
未显示任何日志	没有日志输出、需要集成自定义日志记录器	reference/logging.md
未插入查询参数	参数化查询不起作用、SQL 注入问题	reference/query-params.md
FORMAT 子句 / SHOW POLICIES 错误	重复的 FORMAT 导致语法错误，或即使提供了格式，SHOW [ROW] POLICIES 仍失败	reference/query-format-clause.md

---

仍未解决？

• JS 客户端源代码 + 完整示例
• ClickHouse JS 客户端文档
• ClickHouse 支持的格式