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 Server Components、Server Actions 以及標準 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 |
