关于 clickhouse-js-node-troubleshooting
面向使用 Node.js 运行时中 @clickhouse/client 的开发者，按症状索引 ClickHouse 客户端故障排查说明。内容涵盖连接、类型、代理、TLS、压缩、日志和查询参数等问题，并提示版本限制。
主要功能
- 01按症状索引故障
- 02涵盖连接与类型问题
- 03提供 TLS 和代理排查
- 04说明压缩与日志问题
- 05标注版本相关注意事项
适用场景
- 01排查 ECONNRESET 或查询超时
- 02诊断日期、数字或 UUID 类型错误
- 03处理代理路径或 TLS 证书故障
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/clickhouse-js-node-troubleshooting确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
reference/compression.mddata-types.mdlogging.mdproxy-pathname.mdquery-format-clause.mdquery-params.mdreadonly-users.mdsocket-hangup.mdtls.md详细介绍
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。
如何使用本技能
- 确定问题 — 将症状与下方的问题索引匹配，并阅读相应的参考文件。
- 先说明诊断结果 — 在给出修复方案之前，先解释可能导致问题的原因。
- 留意版本限制 — 标明修复方案所需的最低客户端版本，并核对是否符合用户提供的版本。
- 只询问缺失的信息 — 如果修复方案取决于版本，而你不知道用户使用的版本，就询问；否则立即提供帮助。
问题索引
从下方列表中确定用户遇到的问题，并阅读对应的参考文件以获取详细的故障排除步骤。
| 问题 | 症状 | 参考文件 |
|---|---|---|
| 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 |
仍未解决？
评论
支持 Markdown