ARCore 開發路上最容易踩的五個坑，我全部替你試過了

ARCore 是什麼、能幹嘛、適合誰

說實話，剛接觸 ARCore 的時候我以為它就是 Google 做的一個 AR 開發 SDK，跟蘋果的 ARKit 對標而已。但深入用了才發現，ARCore 的定位其實更像是「把 Android 陣營的 AR 能力串起來的中間層」。它的全名叫 Google Play Services for AR，底層的 SLAM、特徵點提取、IMU 融合這些技術都是 Google 自己做的，然後透過一個統一的 SDK 介面提供給開發者。

具體來說，ARCore 能做幾件事：運動追蹤讓虛擬物體穩定在空間中不飄；環境理解能偵測平面（地板、桌面）和物體邊界；光線估計讓虛擬物體的光影跟真實環境一致；雲端錨點支援多人 AR 互動——兩個人在手機上看到同一個虛擬物體。還有 Augmented Faces，不用深度感應器也能做人臉貼紙和虛擬妝容。

適合誰？如果你是做 Android AR 應用的開發者，或者你的 Unity 專案需要跨平台 AR 能力（Cloud Anchors 只能在 ARCore 之間互通，ARKit 原生錨點不支援），那 ARCore 基本是繞不開的。純 iOS 開發者倒是可以考慮直接走 ARKit，但如果你想做 Android + iOS 的跨平台，ARCore SDK for iOS 是必選之路——這個決策我第一個坑就踩了。

安裝

ARCore 的安裝分兩種情況：終端用戶和開發者。終端用戶比較簡單——只要你的 Android 手機符合 Google Play Services for AR 的相容裝置清單，打開 Google Play 搜尋「ARCore下載」就能裝，安裝包大概 58MB。但如果你的裝置不在清單裡（比如一些地區性的中低端機型），就算你把 APK 側載進去也跑不起來，它會在啟動時檢查裝置相容性然後直接退出，這點很多人踩坑。

開發者安裝的話，Android 端是最直覺的：在 Android Studio 的 SDK Manager 裡勾 ARCore SDK，專案 build.gradle 加一個 dependency 就行。iOS 端就麻煩了——你有兩條路可以選，ARCore SDK for iOS 透過 Swift Package Manager 或 CocoaPods 安裝，或者純 iOS 用 ARFoundation + ARKit。選哪條路取決於你要不要 Cloud Anchors 跨平台共享（這個後面第一個坑會講）。另外 iOS 專案的 Info.plist 必須配置 NSCameraUsageDescription，而且不能寫空字串——App Store 審核會直接拒絕。

還有一個常見的坑是 Cloud Anchors 需要額外的 API Key，得先在 Google Cloud Console 啟用 ARCore Cloud Anchor API，然後把 Key 配置到專案裡。Android 端加在 AndroidManifest.xml，iOS 端加在 Info.plist 的 GARAPIKey 欄位。忘記這步的話，Cloud Anchors 功能調用會直接回傳失敗錯誤，而且錯誤訊息很模糊，第一次碰到我以為是網路問題，排查了半天才發現是 API Key 沒配。

坑一：iOS 上選錯開發路線，Cloud Anchors 怎麼調都不 work

第一次在 iOS 上做 ARCore 專案的時候，我想當然爾覺得 iOS 上最成熟的方案肯定是 ARFoundation + ARKit——畢竟 ARKit 是蘋果原生的，效能好、文件也全。Android 端就用 ARCore SDK，兩邊各跑各的，Unity 跨平台層統一調用。

結果到了測試 Cloud Anchors 的時候崩了。Android 端創建的雲端錨點，iOS 端怎麼都無法解析。反過來也一樣。查了半天才搞清楚：ARKit 的原生錨點和 ARCore 的 Cloud Anchors 是兩個完全不同的系統，它們之間不互通。你在 Android 上用 ARCore 创建的 Cloud Anchor，iOS 上必須用 ARCore SDK for iOS 才能解析，ARFoundation 走 ARKit 路線的話根本連不上 Google 的雲端錨點服務。

解法很簡單：如果你需要 Cloud Anchors 跨平台，iOS 端必須用 ARCore文檔 推薦的 ARCore SDK for iOS，不能走 ARFoundation + ARKit。這意味著你 iOS 端的代碼邏輯跟 Android 端會比較像（因為都是 ARCore API），但 Unity 的跨平台抽象層就用不上了，iOS 部分要自己寫原生綁定。如果不需要 Cloud Anchors，純 iOS 應用還是 ARFoundation + ARKit 更成熟。

坑二：Instant Placement 的預設距離沒調，虛擬物體永遠飄在半空

Instant Placement（即時放置）這個 API 很棒——它讓用戶點螢幕的瞬間就能放一個虛擬物體，不用等 ARCore 慢慢偵測平面。但它有個參數叫 approximateDistanceMeters，預設值是 1.0 米。

問題來了：我做的第一個應用是桌面 AR 遊戲，虛擬物體放在桌上大概 50 公分的距離。但預設值是 1 米，結果每次用戶點螢幕，虛擬物體就「啪」的一下出現在離手機 1 米遠的位置——而用戶的手機正對著自己面前 50 公分的桌子，那個 1 米遠的位置其實是空氣。虛擬物體就這麼懸在半空中，用戶以為自己點錯了。

更坑的是，Instant Placement 會在後台自動修正位置——但前提是 ARCore 得偵測到那個區域的特徵點。如果物體出現在半空（沒有可偵測的表面），後台修正就永遠不會發生，物體就這麼一直飄著。我第一次測的時候以為是 Instant Placement 壞了，調了半天以為是 Session 配置不對，結果就是這一個參數沒設對。

解法：根據你的應用場景合理設 approximateDistanceMeters。家具預覽類的應用設 1.5~2.0 米合理，桌面小遊戲設 0.5~1.0 米，而如果你做的是把手機對著天花板的 AR 應用（比如 AR 星空），那這個參數甚至要設到 3~5 米。另外建議用戶第一次放置失敗時（物體位置明顯不對），提供一個「重新對齊」的按鈕，讓他們重新掃描周圍環境。

坑三：純白牆面或黑暗環境下 SLAM 直接失靈

SLAM 是 ARCore 所有能力的基石，但它的效果高度依賴環境。我第一次帶著 ARCore 應用去一個商場展示的時候，場地是一面純白的活動背板，頂上是強烈的 LED 補光燈。打開應用後——什麼都沒有。虛擬物體放上去就飄，轉一下手機直接消失，TrackingState 從 TRACKING 跳到 STOPPED。

後來查文件才知道，純白牆面沒有紋理特徵點，強光導致快門速度太快圖像模糊，這兩個條件加在一起，ARCore 根本找不到足夠的特徵點來做視覺匹配和 IMU 融合。SLAM 三件套（特徵點提取 + IMU 融合 + 關鍵幀管理）裡的第一環就斷了。

解法有幾個層面。首先是在應用裡做好引導——第一次啟動時給用戶看一個緩動畫，示範「緩慢掃過周圍環境，讓 ARCore 建立地圖」，而不是讓他們一進來就直接放物體。其次是做 TrackingState 的狀態提示，當從 TRACKING 掉到 PAUSED 或 STOPPED 時，在螢幕上顯示一個溫馨提示（比如「請緩慢移動手機，讓我看看周圍環境」），而不是讓虛擬物體憑空消失。最後，極端環境下可以考慮搭配 VPS（Visual Positioning Service，視覺定位服務）或設備的 ToF 深度感應器來補強，但這屬於進階優化了。

坑四：Augmented Faces 的 3D 模型座標沒校準，帽子飛到頭頂三尺高

做 Augmented Faces 人臉特效的時候，我從網上找了一個免費的 3D 帽子模型，導入 Blender 調了調尺寸，然後掛到 face.foreheadCenter 這個關鍵點上。結果預覽的時候帽子確實在額頭的位置——但比預期的高出好幾公分，看起來像是漂浮在頭頂上方，而不是戴在額頭上。

排查了一陣才發現是三個問題疊加：第一，Blender 匯出的模型單位是公分，而 ARCore 關鍵點的座標單位是米——整整差了 100 倍的縮放。第二，模型的 "正面" 朝向了 -Z 方向，而 ARCore 約定的是 +Z 方向，導致帽子的後面朝前、前面朝後。第三，模型的原點（中心點）不在帽子的佩戴位置，而是在帽子的底部中心，所以掛到 foreheadCenter 的時候自然就往上飄了。

解法：匯出 3D 模型時把單位統一為米，Blender 裡把場景設為 Metric 制；確保模型正面朝向 +Z 方向（在 Blender 裡按小鍵盤 1 進入前視圖，確認模型面向你）；最後調整模型原點到實際佩戴位置——帽子的話應該調到帽檐的中心點，而不是帽子底部。Unity 裡有個 ARFaceTemplate 腳本可以幫你在 Blender 中對齊 ARCore 的人臉網格，強烈建議用它。

坑五：Cloud Anchors 的 API Key 忘記配置，錯誤訊息讓你以為網路炸了

最後一個坑比較細但很浪費時間。ARCore 的基礎運動追蹤和平面偵測不需要任何 API Key，但 Cloud Anchors 雲端錨點功能需要——因為它要把你的錨點上傳到 Google 的雲端服務。

流程是這樣的：先在 Google Cloud Console 裡為你的專案啟用 ARCore Cloud Anchor API，然後創建一個 API Key，最後把這個 Key 配置到應用裡。Android 端是在 AndroidManifest.xml 加一個 meta-data，iOS 端是在 Info.plist 加一個 GARAPIKey 鍵值。忘記這步的話，調用 Cloud Anchors 的時候會收到一個失敗錯誤。

坑點在哪裡？那個錯誤訊息很模糊——它大概長這樣：「Cloud Anchor operation failed. Check your network connection and API key configuration.」把網路問題和配置問題混在一起提示了。我第一次碰到時以為是測試環境的網路不穩，斷斷續續排查了好幾個小時，最後才發現是 API Key 根本沒加。而且 Cloud Anchors 的功能在 SDK 裡是預設啟用的，不會有任何編譯時警告或錯誤，只有在你真正調用的時候才會在運行時失敗。

解法：把 Cloud Anchors 的 API Key 配置當成專案初始化的必做項。如果你有多個應用共用同一個 Google Cloud 專案，注意 API Key 可以綁定特定的包名（Android）或 Bundle ID（iOS），建議都綁上，避免 Key 被濫用。另外測試 Cloud Anchors 的時候，提前把網路排除——先確認手機網路正常、其他 API 請求都能通，再去排查配置問題。

避坑要點速查

• iOS 端選 ARCore SDK 還是 ARFoundation？關鍵判據是「要不要 Cloud Anchors 跨平台」，要的話只能選前者
• Instant Placement 的 approximateDistanceMeters 別留預設值，根據應用場景（桌面/手持/大空間）實測調整
• SLAM 效果差的時候先檢查環境：純白牆、強光、黑暗、快速晃動手機都是殺手
• Augmented Faces 的 3D 模型在 Blender 匯出時統一單位為米、確保正面朝向 +Z、調整原點到佩戴位置
• Cloud Anchors 的 API Key 配置是專案初始化必做項，錯誤訊息把網路和配置混在一起容易誤判

說完這些坑，ARCore 還是值得花時間投入的——它在 Android 陣營的 AR 能力上目前還是最好的選擇，而且 Cloud Anchors 的跨平台支援是 ARKit 原生做不到的。踩過這些坑之後，開發體驗其實還是很順暢的。

本文为个人基于网络公开资料整理编写，非官方内容，仅供学习交流参考；软件版权归原作者所有，请支持正版；使用过程中遇到问题请查阅官方渠道，本文不承担任何责任。