第一步：按四類分流（載入 / 設定 / 框架 / 顯示）
不管是哪種「客服沒出來」，先把範圍縮到四類——這一步能省一大半彎路。流程圖把決策畫清楚：先看腳本到底載入了沒（F12 看 meiqia.js），再看是設定、框架還是顯示層的問題。更基礎的接入步驟見 美洽網站接入教學。
接入的原理：為什麼這段 JS 注入會失敗 / 被攔
理解一句話就夠：美洽網頁外掛不是你頁面裡的靜態元件，而是一段 meiqia.js 從美洽外網域非同步載入、動態往你頁面注入客服容器（DOM / iframe）、再和美洽伺服器建跨網域長連線。注入要成功，得「腳本先載入到（位置對、沒被廣告攔）、容器沒被站點 CSS / 其它外掛蓋住、entId 與網域配對得上、SPA 切頁後重新掛載」。下圖把這條鏈路和四個常見攔截點畫出來——這正是同一段程式碼在不同站點 / 框架裡時靈時不靈的根因。
程式碼都貼對了仍不顯示：先過一遍接入自檢面板
如果程式碼位置、meiqia.js 200、entId 都確認了還不顯示，問題基本在「廣告攔截」或「框架 / 層級」上。下面的自檢面板按重要性排了序：綠的通常沒問題，紅的（廣告攔截、SPA / 第三方外掛層級）才是高發坑。對著逐項核，定位會快很多。
全量症狀對照表（現象 / 官方定位 · L2 深度真因）
下表把常見的接入不顯示 / 報錯症狀一次列全，每條給出官方定位與 L2 深度真因。上面的查詢框就是用這張表的資料驅動的，可直接搜你遇到的關鍵字。
| 症狀 | 分類 | L1 現象 / 官方定位 | L2 深度真因 |
|---|---|---|---|
| 客服視窗 / 浮窗整體不顯示 | 載入失敗類 | 美洽網頁外掛只需複製一段專屬 JS 程式碼貼到網站頁面即可載入浮動客服視窗；需確認程式碼已正確嵌入且接入網站已在後台設定。 | 網頁外掛是 meiqia.js 非同步載入後動態注入 DOM 的，整體不顯示通常意味著「腳本根本沒載入成功」——程式碼沒貼對位置、被廣告攔截 / 快取擋住、或網域 / entId 沒配對，導致注入這一步沒發生。 |
| 腳本載入了但聊天按鈕不出現 | 顯示異常類 | 網頁外掛程式碼會自動適配網站樣式並顯示聊天按鈕；如顯示異常可檢查是否被樣式隱藏或腳本執行被中斷。 | 腳本載入成功但按鈕不出現，多是「顯示層」問題：站點全域 CSS 覆蓋了按鈕定位 / 把它 display:none、z-index 被壓、或被其它固定定位元素蓋住；也可能頁面裡另一個 JS 報錯中斷了初始化。 |
| meiqia.js 被廣告攔截擴充攔截 | 載入失敗類 | 美洽客服腳本來自第三方網域；若瀏覽器安裝了攔截類擴充，可能將其識別為廣告 / 追蹤而阻止載入，建議關閉攔截或加入白名單。 | ERR_BLOCKED_BY_CLIENT 是瀏覽器擴充（AdBlock / uBlock / AdGuard）按其過濾規則名單攔截了請求。美洽腳本是「第三方外網域 + 即時通訊」，常被這類規則誤判為廣告 / 追蹤而攔，造成「後台資料正常、使用者側不顯示」的假失敗。 |
| meiqia.js 請求 404 / 狀態異常 / 混合內容 | 載入失敗類 | 部署後可在開發者工具 Network 面板搜尋 meiqia.js，狀態碼 200 表示腳本位置正確、已正常載入。 | 非 200 的常見原因：程式碼被頁面快取 / CDN 快取擋住（發布後沒重新整理）、HTTP 頁面下載入 / 憑證鏈不全觸發混合內容攔截、或程式碼被改壞 / 複製不全。腳本這一步失敗，後面的注入與連線都不會發生。 |
| 程式碼貼錯位置（head 阻塞 / 不生效） | 載入失敗類 | 美洽官方建議把程式碼貼到網站頁面底部、</body> 標籤之前；外掛程式碼會在頁面主要內容載入完成後執行。 | 網頁外掛需在 DOM 就緒後再注入容器。貼在 <head> 會阻塞渲染（弱網先白屏）、或在 DOM 未就緒時執行導致注入失敗；貼進某些非同步 / 模組作用域裡也可能載入順序錯亂。 |
| 聊天視窗 / 按鈕樣式錯亂 | 顯示異常類 | 網頁外掛會動態插入自身樣式並自動適配網站；若與站點全域樣式衝突，可能出現外觀異常。 | 美洽腳本執行時動態插入 CSS；如果站點全域樣式（萬用選擇器 / 高優先規則 / reset）先覆蓋了它的類別，按鈕位置、層級、字體就會錯亂——這是「動態注入 + 共享同一文件樣式空間」的副作用。 |
| 按鈕跑到螢幕外 / 被遮擋 | 顯示異常類 | 外掛按鈕以固定定位浮窗形式出現在頁面；如被其它固定元素遮擋可調整層級或位置。 | 站點裡其它 position:fixed 元素（回到頂部、懸浮廣告、客服條）z-index 更高把美洽按鈕蓋住，或主題樣式把它的定位座標算偏，按鈕就「在螢幕外 / 被遮」。 |
| 第三方外掛 / 統計改 DOM 衝突 | 顯示異常類 | 頁面中其它腳本若修改 DOM 結構或攔截請求，可能影響美洽外掛的正常載入與顯示。 | 熱圖 / 統計 / 轉換類腳本會改寫 DOM、注入遮罩層或攔請求；它們與美洽都往同一文件注入元素，層級 / 事件互相干擾，導致美洽容器被覆蓋或初始化被打斷。 |
| SPA 路由切換後外掛消失 | 框架整合類 | 對於單頁應用（SPA），可借助框架路由鉤子動態載入 / 初始化美洽外掛，以適配前端路由切換。 | SPA 用前端路由切換視圖、會銷毀 / 重建 DOM，但 meiqia.js 預設只在首次載入注入一次、不會隨路由自動重建，於是「換頁客服就沒了」。 |
| 需手動初始化（manualInit / init） | 框架整合類 | 在美洽嵌入程式碼後加入 _MEIQIA('manualInit') 可阻止外掛下載完成後自動初始化；需要時再呼叫 _MEIQIA('init') 手動初始化。 | 預設美洽下載完即自動初始化；當你需要先準備好容器 / 傳完顧客資訊 / 等路由就緒再顯示時，自動時機就「太早」——這時要改成手動初始化自己控制時序。 |
| entId 不一致 / 客服收不到對話 | 設定授權類 | 程式碼中 entId 後的數字為企業唯一識別，若與客服工作台不一致會導致客服無法接待對話；可在【設定-團隊管理-ID查詢】查看企業 ID。 | entId 把這段外掛綁定到具體企業帳號。複製了別人 / 別的環境的程式碼、或多帳號搞混時，前端能載入彈窗、但訊息發到了「別的企業」，本工作台自然收不到——這是「顯示正常卻收不到」的典型。 |
| 網站網域未在後台授權 | 設定授權類 | 美洽後台可「新增接入網站」，每個接入網站有獨立設定；新網站需在後台設定後才能正常接入。 | 美洽按「接入網站」管理多站點，網域要先在後台登記 / 授權才被認。換了正式網域卻沒在後台新增，腳本就可能不被認、或歸不到對的設定上。 |
| 多站點 / 子渠道（探頭）設定串台 | 設定授權類 | 美洽支援對多個網站部署不同的網頁外掛和聊天連結（網站子渠道 / 探頭功能），除預設接入網站外還可增加多個，每個有獨立設定。 | 多業務線需要不同的接待客服組 / 自動訊息，但若各站共用同一段預設程式碼，就分不出來源、設定互相串台。子渠道（探頭）就是為「一個企業、多入口分流」設計的。 |
| 行動版網頁客服不顯示 / 需分別部署 | 行動 / SDK 類 | 網頁外掛程式碼自動適配網站樣式，行動 / PC 網站為同一段程式碼，但需要分別部署。 | 很多團隊 PC 與行動是兩套頁面 / 模板，只在 PC 模板裡貼了程式碼。外掛程式碼雖同一段、能自適配，但「貼」這一步要在行動模板裡也做一次，漏了行動端自然沒有。 |
| APP 原生 SDK 接入 / AppKey | 行動 / SDK 類 | APP 內接入需在美洽工作台【設定-接入-SDK】「新增 APP 設定」取得 AppKey，由開發人員參照官方文件與 Demo 整合 iOS / Android SDK。 | APP 裡用的不是網頁 JS 而是原生 SDK：要先在後台「新增 APP 設定」拿 AppKey，再按平台整合 SDK 實現聊天介面、未讀訊息、推播等——和網頁外掛是兩條完全不同的接入鏈路。 |
| SDK 訊息推播收不到 | 行動 / SDK 類 | 美洽 SDK 推播分兩種：「不推播」時客服訊息僅推播到 APP 內（需開啟 APP 才能收）；設定「自訂推播伺服器」後，使用者離開 APP 也能收到推播到手機。 | 收不到「離線推播」往往是推播方式選了「不推播」、或沒配自訂推播伺服器 / 各平台推播憑證。推播鏈路是「美洽端 → APP 伺服器 → 使用者手機」，少一環就只能 APP 內收。 |
| 隱藏預設按鈕 / 自訂入口 | 介面呼叫類 | 呼叫 _MEIQIA('withoutBtn') 可不顯示美洽自帶聊天按鈕；初始化成功後呼叫 _MEIQIA('showPanel') 可開啟聊天視窗。 | 預設會渲染美洽自帶浮動按鈕；要換成自己的入口，需要在初始化前 / 時宣告不要自帶按鈕，再把「開啟聊天」動作綁到自己的元素上——這是介面時序問題，不是「按鈕壞了」。 |
| 傳遞 / 同步顧客資訊不生效 | 介面呼叫類 | 美洽網頁外掛提供「傳遞顧客資訊」「同步顧客身分」「新增顧客自訂事件資訊」等介面，用於把訪客資訊帶入會話。 | 這些介面要在正確的初始化時序內呼叫：在外掛初始化成功後（或配合 manualInit + init 的時機）設定，太早 / 太晚或欄位格式不對都會「設了不生效」。 |
美洽接入不顯示主因與接入方式對照（2026 估算）
以下為綜合美洽官方說明（接入渠道 / JavaScript 網頁外掛介面）與公開接入排錯經驗的 2026 估算（非廠商承諾值、非一手實測，僅供參考；隨版本與瀏覽器策略變化）：
| 維度 | 估算 / 對照 |
|---|---|
| 接入不顯示主因占比（社群 / 工單經驗 · 估算） | 程式碼位置 / 未載入 ≈ 35% > 廣告攔截 / 瀏覽器擴充 ≈ 25% > 設定授權（entId / 網域）≈ 20% > 框架整合（SPA）≈ 12% > 樣式 / 第三方外掛衝突 ≈ 8% |
| 接入技術本質 | 網頁外掛 = 第三方外網域非同步 JS 注入 DOM + 跨網域長連線（非內嵌靜態元件）；故受程式碼位置、廣告攔截規則、頁面 CSS 層級、SPA 生命週期影響 |
| 各端接入方式（估算） | PC / 行動網頁 = JS 外掛（同程式碼、分別部署）；APP = 原生 SDK（AppKey）；微信 / 抖音 / 小紅書 = 渠道授權接入 |
| 廣告攔截影響（估算） | PC 端約 30–40% 使用者裝廣告攔截擴充 → 第三方客服腳本被按廣告規則攔（ERR_BLOCKED_BY_CLIENT），是「後台正常、使用者側不顯示」的高發因 |
| JS 外掛生效速度（官方口徑） | 複製專屬 JS 程式碼貼到頁面底部，約 3–5 分鐘生效；entId 為企業唯一識別，與工作台不一致則客服收不到對話 |
估算口徑：信源基線 + 時間外推（綜合 meiqia.com/help 接入渠道 / JavaScript 網頁外掛、meiqia.im 接入官網指南、公開接入排錯帖 2026 抓取），隨版本與瀏覽器攔截策略會變；請以美洽最新官方為準。
美洽五種接入方式對照（程式碼 / 難度 / 功能 / 情境 / 生效速度）
選哪種接入方式？下面這張對照綜合美洽官方口徑，給一個快速橫向參考（程式碼量、功能完整度、適用情境、生效速度）。多數官網首選「網頁 JS 外掛」。
| 接入方式 | 程式碼 / 難度 | 功能完整度 | 適用情境 | 生效速度 |
|---|---|---|---|---|
| 網頁 JS 外掛 | 一段 JS · 低 | 最全（浮窗 / 彈窗 / 自動迎賓 / 訪客軌跡） | PC + 行動官網（官方推薦） | 約 3–5 分鐘 |
| 聊天連結 | 無程式碼 · 最低 | 基礎對話 | 無技術 / 臨時放個客服連結 | 即時 |
| API / WebIM SDK | 需開發 · 高 | 深度客製（自訂介面 / 系統整合 / 訂單打通） | 有開發能力做深度融合 | 視開發 |
| APP 原生 SDK | 整合 SDK · 高 | APP 內客服 + 訊息推播 | iOS / Android APP | 視開發 |
| CMS 快捷設定 | 外掛 / 一鍵 · 低 | 同 JS 外掛 | WordPress / 凡科 / Shopify 等建站 | 幾分鐘 |
渠道 / 情境 → 接入成敗映射
同一個美洽，在不同渠道 / 情境裡接入方式不同。下圖把常見渠道的接入成敗畫成映射，綠=貼對即可、黃=需設定（分別部署 / init / 白名單）、紅=預設要換方式（廣告攔截 / entId / APP 用 SDK）。
常見問題
美洽客服視窗 / 浮窗整體不顯示怎麼解決？
美洽網頁外掛只需複製一段專屬 JS 程式碼貼到網站頁面即可載入浮動客服視窗；需確認程式碼已正確嵌入且接入網站已在後台設定。 網頁外掛是 meiqia.js 非同步載入後動態注入 DOM 的，整體不顯示通常意味著「腳本根本沒載入成功」——程式碼沒貼對位置、被廣告攔截 / 快取擋住、或網域 / entId 沒配對，導致注入這一步沒發生。 F12 → Network 搜 meiqia.js：沒有請求→程式碼沒生效（查位置 / 清快取）；有請求但非 200→被攔或路徑問題；都正常仍不顯示→看 entId / 網域授權與下面各分類。
美洽腳本載入了但聊天按鈕不出現怎麼解決？
網頁外掛程式碼會自動適配網站樣式並顯示聊天按鈕；如顯示異常可檢查是否被樣式隱藏或腳本執行被中斷。 腳本載入成功但按鈕不出現，多是「顯示層」問題：站點全域 CSS 覆蓋了按鈕定位 / 把它 display:none、z-index 被壓、或被其它固定定位元素蓋住；也可能頁面裡另一個 JS 報錯中斷了初始化。 F12 → Elements 搜美洽容器看是否存在、是否被隱藏 / 移到螢幕外；暫時停用站點自訂 CSS / 其它腳本復測；主控台看有無報錯中斷執行。
美洽meiqia.js 被廣告攔截擴充攔截怎麼解決？
美洽客服腳本來自第三方網域；若瀏覽器安裝了攔截類擴充，可能將其識別為廣告 / 追蹤而阻止載入，建議關閉攔截或加入白名單。 ERR_BLOCKED_BY_CLIENT 是瀏覽器擴充（AdBlock / uBlock / AdGuard）按其過濾規則名單攔截了請求。美洽腳本是「第三方外網域 + 即時通訊」，常被這類規則誤判為廣告 / 追蹤而攔，造成「後台資料正常、使用者側不顯示」的假失敗。 無痕視窗或關閉廣告攔截擴充復測——能顯示即為攔截所致；引導使用者把站點加白名單；前端可對客服腳本做延遲 / 條件載入以繞過部分自動規則。
美洽meiqia.js 請求 404 / 狀態異常 / 混合內容怎麼解決？
部署後可在開發者工具 Network 面板搜尋 meiqia.js，狀態碼 200 表示腳本位置正確、已正常載入。 非 200 的常見原因：程式碼被頁面快取 / CDN 快取擋住（發布後沒重新整理）、HTTP 頁面下載入 / 憑證鏈不全觸發混合內容攔截、或程式碼被改壞 / 複製不全。腳本這一步失敗，後面的注入與連線都不會發生。 發布後清 CDN / 瀏覽器快取或用無痕視窗；確保全站 HTTPS、憑證鏈完整、無混合內容；核對複製的程式碼完整無缺、未被轉義。
美洽程式碼貼錯位置（head 阻塞 / 不生效）怎麼解決？
美洽官方建議把程式碼貼到網站頁面底部、</body> 標籤之前；外掛程式碼會在頁面主要內容載入完成後執行。 網頁外掛需在 DOM 就緒後再注入容器。貼在 <head> 會阻塞渲染（弱網先白屏）、或在 DOM 未就緒時執行導致注入失敗；貼進某些非同步 / 模組作用域裡也可能載入順序錯亂。 把美洽 JS 放到所有頁面的公共底部、</body> 之前；SPA 見「SPA 路由」一條用 manualInit；確保它不被打包工具 tree-shaking 掉。
美洽聊天視窗 / 按鈕樣式錯亂怎麼解決？
網頁外掛會動態插入自身樣式並自動適配網站；若與站點全域樣式衝突，可能出現外觀異常。 美洽腳本執行時動態插入 CSS；如果站點全域樣式（萬用選擇器 / 高優先規則 / reset）先覆蓋了它的類別，按鈕位置、層級、字體就會錯亂——這是「動態注入 + 共享同一文件樣式空間」的副作用。 F12 看是哪條站點規則覆蓋了美洽容器，給站點全域樣式收窄作用域 / 降低對通用類別的影響；必要時聯絡美洽調整容器層級。
美洽按鈕跑到螢幕外 / 被遮擋怎麼解決？
外掛按鈕以固定定位浮窗形式出現在頁面；如被其它固定元素遮擋可調整層級或位置。 站點裡其它 position:fixed 元素（回到頂部、懸浮廣告、客服條）z-index 更高把美洽按鈕蓋住，或主題樣式把它的定位座標算偏，按鈕就「在螢幕外 / 被遮」。 F12 選中美洽容器看實際座標 / z-index；調高它或調低遮擋元素層級；避免多個固定浮窗疊在同一角落。
美洽第三方外掛 / 統計改 DOM 衝突怎麼解決？
頁面中其它腳本若修改 DOM 結構或攔截請求，可能影響美洽外掛的正常載入與顯示。 熱圖 / 統計 / 轉換類腳本會改寫 DOM、注入遮罩層或攔請求；它們與美洽都往同一文件注入元素，層級 / 事件互相干擾，導致美洽容器被覆蓋或初始化被打斷。 逐個暫時停用可疑外掛復測定位衝突源；調整載入順序 / 容器層級；讓熱圖等避開美洽容器區域。
美洽SPA 路由切換後外掛消失怎麼解決？
對於單頁應用（SPA），可借助框架路由鉤子動態載入 / 初始化美洽外掛，以適配前端路由切換。 SPA 用前端路由切換視圖、會銷毀 / 重建 DOM，但 meiqia.js 預設只在首次載入注入一次、不會隨路由自動重建，於是「換頁客服就沒了」。 用 _MEIQIA('manualInit') 阻止自動初始化，在路由切換鉤子（React useEffect / Vue mounted / 路由 afterEach）裡按需呼叫 _MEIQIA('init') 重新掛載；避免重複初始化多個實例。
美洽需手動初始化（manualInit / init）怎麼解決？
在美洽嵌入程式碼後加入 _MEIQIA('manualInit') 可阻止外掛下載完成後自動初始化；需要時再呼叫 _MEIQIA('init') 手動初始化。 預設美洽下載完即自動初始化；當你需要先準備好容器 / 傳完顧客資訊 / 等路由就緒再顯示時，自動時機就「太早」——這時要改成手動初始化自己控制時序。 在嵌入程式碼後加 _MEIQIA('manualInit')；待條件就緒（DOM / 登入態 / 路由）再 _MEIQIA('init')；顧客資訊等介面要在 init 時序內按文件順序呼叫。
更多接入設定見 美洽網站接入教學、APP SDK 接入；新手上手見 美洽使用教學。完整可查詢版（含本工具）也在 美洽接入排錯速查（GitHub Pages）。