clickhouse-js-node-troubleshooting
热门排查并解决 ClickHouse Node.js 客户端（@clickhouse/client）的常见问题。当用户报告涉及 Node.js 客户端的错误、意外行为或配置问题时使用此技能——包括 socket hang-up 错误、Keep-Alive 问题、流处理问题、数据类型不匹配、只读用户限制、代理/TLS 设置问题或长时间运行的查询超时。即使用户没有准确描述问题，只要在 Node.js 上下文中出现诸如“我的插入一直失败”或“连接随机断开”等模糊症状，也应触发此技能。请勿用于浏览器/Web 客户端问题。
排查并解决 ClickHouse Node.js 客户端（@clickhouse/client）的常见问题。 当用户报告涉及 Node.js 客户端的错误、意外行为或配置问题时使用此技能—— 包括 socket hang-up 错误、Keep-Alive 问题、流处理问题、数据类型不匹配、 只读用户限制、代理/TLS 设置问题或长时间运行的查询超时。即使用户没有准确描述问题， 只要在 Node.js 上下文中出现诸如“我的插入一直失败”或“连接随机断开”等模糊症状， 也应触发此技能。请勿用于浏览器/Web 客户端问题。
ClickHouse Node.js 客户端故障排除
参考文档：https://clickhouse.com/docs/integrations/javascript
⚠️ 仅限 Node.js 运行时。 本技能仅涵盖在 Node.js 运行时 中运行的
@clickhouse/client包——包括 Next.js Node 运行时 API 路由、React 服务器组件、服务器操作以及标准 Node.js 进程。请不要将此技能应用于浏览器客户端组件、Web Workers、Next.js Edge 运行时、Cloudflare Workers 或任何使用@clickhouse/client-web的场景。对于浏览器/边缘环境，正确的包是@clickhouse/client-web。
如何使用本技能
- 识别问题 — 将症状与下方的问题索引匹配，并阅读相应的参考文件。
- 先给出诊断 — 在给出修复方法之前，先解释可能导致问题的原因。
- 注意版本限制 — 如果修复需要最低客户端版本，请标记并检查用户提供的版本。
- 仅询问缺失信息 — 如果修复依赖于版本且您不知道用户的版本，请询问；否则立即提供帮助。
问题索引
从下方列表中识别用户的问题，并阅读相应的参考文件以获取详细的故障排除步骤。
| 问题 | 症状 | 参考文件 |
|---|---|---|
| Socket Hang-Up / ECONNRESET | socket hang up、ECONNRESET、间歇性连接断开、长时间运行的查询超时 |
reference/socket-hangup.md |
| 数据类型不匹配 | 大整数以字符串形式返回、十进制精度丢失、Date/DateTime 插入失败、将 UUID 插入 UInt128 列时出现 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 |
