美洽 客服視窗不顯示 / 接入報錯 速查

美洽客服視窗不顯示 / 接入報錯速查工具示意圖
圖：美洽客服接入不顯示 / 報錯速查（L1 現象 + L2 深度真因 + 五種接入方式對照）

美洽的網頁客服外掛貼了程式碼卻不顯示、聊天按鈕不出現、主控台報 meiqia.js 被攔、或客服後台收不到對話？先想清三件事——是腳本根本沒載入（程式碼位置 / 廣告攔截 / 快取），還是載入了但被頁面樣式 / 層級蓋住，還是載入正常但設定沒對上（entId / 網域 / SPA 生命週期）。輸入或點選你遇到的症狀或關鍵字（如 不顯示、廣告攔截、entId、SPA、行動版、SDK推播），先看 L1 現象與官方定位，再看 L2 深度真因與排查，最後對照五種接入方式與真實情境。需要安裝 / 教學可到 美洽下載 / 客服系統接入教學。

第一步：先看腳本載入沒、再分四類（別急著重貼程式碼）

美洽客服不顯示，九成落在四類上、先分清誰的鍋：先看腳本到底載入了沒——F12 → Network 搜 meiqia.js，沒有請求或狀態非 200 就是沒載入。① 載入失敗類——程式碼貼錯位置（應在 </body> 前、非 <head>）、被廣告攔截擴充按廣告規則攔（ERR_BLOCKED_BY_CLIENT）、CDN / 瀏覽器快取擋住、HTTPS 憑證 / 混合內容；② 設定授權類——entId 與工作台不一致（腳本能載入但客服收不到對話）、網站網域沒在後台授權；③ 框架整合類——Vue/React/Next 單頁應用路由切換銷毀容器、外掛沒重建；④ 顯示 / 行動 / SDK 類——站點 CSS 把浮窗推到螢幕外 / 第三方外掛改 DOM 蓋住層級、行動版要單獨部署、APP 內要用 SDK。更完整的接入步驟見 美洽網站接入教學。

載入失敗類程式碼位置 · 廣告攔截 · 快取 · HTTPS
把美洽 JS 貼在 前（非 ）；F12 → Network 搜 meiqia.js 看狀態碼（應 200）；被 ERR_BLOCKED_BY_CLIENT 攔多為廣告攔截擴充，用無痕視窗或加白名單復測；發布後清 CDN 快取；確認全站 HTTPS、無混合內容。
設定授權類entId · 網域白名單 · 子渠道
entId 是企業唯一識別，與工作台不一致會「腳本能載入但客服收不到對話」（核對【設定-團隊管理-ID查詢】）；網站網域要在後台「新增接入網站」授權；多業務線用子渠道（探頭）各自獨立設定，別一段程式碼混用。
框架整合類SPA · 路由切換 · 手動初始化
Vue/React/Next 單頁應用路由切換會銷毀 DOM、外掛不會自動重建；用 _MEIQIA('manualInit') 阻止自動初始化，在路由鉤子（如 useEffect / mounted）裡按需 _MEIQIA('init') 重新掛載。
顯示異常類樣式衝突 · 層級覆蓋 · 第三方外掛
腳本已載入但看不到：多為站點全域 CSS 覆蓋了浮窗按鈕位置、或熱圖 / 統計 / SEO 外掛改 DOM 把容器層級蓋住；F12 → Elements 搜 meiqia 容器，看是否被 display:none、z-index 壓住或移到螢幕外。
行動 / SDK 類行動網頁 · AppKey · 推播
行動 / PC 網頁是同一段程式碼但需分別部署接入；APP 內用原生 SDK（先在後台「新增 APP 設定」拿 AppKey）；推播分「不推播」（僅 APP 內收）與「自訂推播伺服器」（離開 APP 也能收）。
介面呼叫類withoutBtn · showPanel · 顧客資訊
想用自己的按鈕：_MEIQIA('withoutBtn') 隱藏自帶按鈕、點擊時呼叫 _MEIQIA('showPanel') 開啟聊天視窗；傳遞 / 同步顧客資訊要在初始化時序內呼叫，否則不生效。
客服視窗 / 按鈕不顯示排查流程（先分兩步：腳本載入了嗎 → 設定對了嗎）客服不顯示先分兩類腳本沒載入 →程式碼位置 · 廣告攔截 · 快取載入了但不顯 / 連不上 →樣式層級 · entId · 網域 · SPA四類根因（逐項看真因 / 排查）① 載入失敗位置 · 攔截 · 快取② 設定授權entId · 網域白名單③ 框架整合SPA 路由 · init④ 顯示 / 行動 / SDK層級 · 行動 · 推播
圖1：美洽客服不顯示排查決策流程——先看腳本載入沒，再分載入失敗 / 設定授權 / 框架 / 顯示四類

第二步：最常被忽略的真因 → L2 深度（網頁外掛 = 第三方外網域 JS 非同步注入）

關鍵認知：美洽網頁外掛不是嵌在你頁面裡的靜態元件，而是一段 meiqia.js 非同步從美洽外網域載入、再動態往你的頁面裡建立客服容器（DOM / iframe），並和美洽伺服器建一條跨網域長連線。這就解釋了大半「玄學」不顯示——① 它是第三方外網域腳本：AdBlock / uBlock 按「第三方追蹤 / 廣告」規則名單直接攔，於是 ERR_BLOCKED_BY_CLIENT、按鈕根本不出現（後台卻顯示正常）；② 它非同步注入 DOM：貼在 <head> 會阻塞、SPA 路由切換銷毀容器後不會自動重建（要 manualInit + _MEIQIA('init')）、其它熱圖 / 統計外掛改 DOM 會蓋住它的層級；③ 它靠 entId 綁企業、靠網域白名單授權：entId 錯或網域沒授權時，腳本能載入、但「連不上對話」；④ 行動版與 PC 是兩套獨立接入，APP 內則是 SDK（AppKey）、推播還分「不推播 / 自訂推播伺服器」兩條鏈路。理解這條注入鏈路，下面每個症狀的排查就有了統一邏輯。下圖是接入自檢面板示意；再往下是五種接入方式對照與 2026 估算。

接入自檢面板示意（綠=已確認 / 紅=易忽略待查）自檢項判斷狀態美洽程式碼貼在 前（非 ）程式碼位置已確認F12 → Network 裡 meiqia.js 狀態 200腳本載入已確認主控台 typeof _MEIQIA 為 function已初始化已確認無痕視窗 / 關廣告攔截能顯示廣告攔截待查entId 與工作台一致 + 網域已授權設定授權已確認SPA 路由切換後重新 init + 無外掛覆蓋層級框架 / 層級待查註：紅 = 最易被忽略兩點——廣告攔截擴充（ERR_BLOCKED_BY_CLIENT）與 框架 / 層級（SPA 切頁、第三方外掛改 DOM）；先按這兩點核。
圖2：美洽接入自檢面板示意（綠=已確認 / 紅=易忽略待查）
美洽接入前自檢面板紅綠項示意圖
圖：先核「程式碼位置 + meiqia.js 200 + 已初始化」，再看「廣告攔截 + 框架/層級」——後兩點最易忽略

全部症狀對照表（L1 現象 / 官方定位 · L2 深度真因）

美洽五種接入方式對照（程式碼 / 難度 / 功能 / 情境 / 生效速度 · 官方口徑）

接入方式程式碼 / 難度功能完整度適用情境生效速度
網頁 JS 外掛一段 JS · 低最全（浮窗 / 彈窗 / 自動迎賓 / 訪客軌跡）PC + 行動官網（官方推薦）約 3–5 分鐘
聊天連結無程式碼 · 最低基礎對話無技術 / 臨時放個客服連結即時
API / WebIM SDK需開發 · 高深度客製（自訂介面 / 系統整合 / 訂單打通）有開發能力做深度融合視開發
APP 原生 SDK整合 SDK · 高APP 內客服 + 訊息推播iOS / Android APP視開發
CMS 快捷設定外掛 / 一鍵 · 低同 JS 外掛WordPress / 凡科 / Shopify 等建站幾分鐘

美洽接入不顯示主因與接入方式對照（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 抓取），隨版本與瀏覽器攔截策略會變；請以美洽最新官方為準。

真實情境速判

相關