常見錯誤
10 個 常見問題與解法
從現實案例整理：Widget 不顯示、CORS 擋住、SPA 切頁消失、popup 衝突、訊息送不出去等。每題給明確的修法步驟，不打高空。
右下角看不到聊天按鈕？
依序檢查：
- F12 Network 看
loader.js是否 200 OK；若 404 / CORS error → 確認嵌入代碼網址沒被改 - F12 Console 看有沒有紅色錯誤（CSP / 跨域 / token 格式錯）
- 確認嵌入代碼貼在
</body>前一行，不是<head>內 - 檢查網站是否有 CSP 政策擋住外部 script — 參考 Widget 嵌入指南的「CSP 設定」章節
- 到後台「🔍 連線診斷」按「⚡ 立即測試連線」主動驗證
改了主色 / 文字後，網站還是舊樣式？
在訪客瀏覽器強制重整一次（Ctrl/Cmd + Shift + R）。Widget 每次載入會即時拉最新設定，不需要重貼代碼。若仍是舊樣式，看 F12 Network 的
/api/widget/config response 是否回的是新值。訊息送不出去 / 顯示「網路錯誤」？
確認 token 沒被改過；確認後台尚未停用此機器人（
enabled=false 會回 200 + "客服暫停服務中"）；若有公司網路防火牆，請放行 aibot.chungtair.com 網域。看 Debug 面板的 POST /api/widget/message response 可秒看是哪一種失敗。F12 看到 CSP 錯誤怎麼辦？
錯誤訊息會像
Refused to load the script ... violates the following Content Security Policy directive。解法：在您網站的 CSP 設定加入 script-src https://aibot.chungtair.com; frame-src https://aibot.chungtair.com; connect-src https://aibot.chungtair.com; img-src https://aibot.chungtair.com data:;。完整對照表看 Widget 嵌入指南的 CSP 章節。Next.js / Vue Router 切換頁面後 widget 消失？
通常是因為 SPA framework 把整個
<body> 重渲染，把 widget 注入的 DOM 一併清掉。解法：把嵌入代碼放到根 layout 而不是個別頁面（Next.js 的 app/layout.tsx、Nuxt 的 nuxt.config.ts），這樣 SPA 切頁時根 layout 不重 render，widget 保留。Widget 跟我網站的 popup / 浮動按鈕重疊？
到後台「Widget 設定」可切換按鈕位置（右下 / 左下）。如果還是重疊，看自家 popup 的 z-index — widget 的 iframe 預設 z-index 為 999999，提高自家元件不太實際；建議把自家元件挪位置或在出現 widget 時隱藏。
WordPress 貼上代碼後 token 跑掉變奇怪字串？
WordPress 預設會把貼到 footer.php 的 HTML 經過 wpautop / wptexturize 過濾，可能把
" 變成全形引號。解法：用「Insert Headers and Footers」外掛把代碼貼到 Footer Scripts 欄位，這個欄位不會被過濾。Shopify 貼到 theme.liquid 但沒生效？
確認貼在
</body> 前一行（不是 </html> 前）。某些 Shopify 主題會用自家的 footer.liquid，要找到實際渲染最後 </body> 的檔案。可以在瀏覽器 view-source 找 </body> 的位置確認。訪客看不到 widget，但後台 Debug 面板有 ping 紀錄？
代表 widget 有載入（ping 進來了），但訪客那邊 UI 被擋住。常見原因：
- 網站 CSS 全域有
iframe { display: none }或* { pointer-events: none }等規則 - 有 cookie 同意彈窗占滿畫面、把 widget 蓋住
- 訪客用了廣告攔截擴充程式（uBlock 等）擋住第三方 iframe
chungtair-widget 容器是否有被 hide。我有多個網站要嵌入同一個 bot 怎麼辦？
直接複製同一段嵌入代碼貼到每個網站。Widget token 不限定網域，多個網域共用 OK。Debug 面板的「最後一次成功 ping」會顯示最近一個 ping 過的網域（不是全部）。如果想分別追蹤每個網域的對話，建議建多個 Bot 各用獨立 token。