# libimobiledevice 使用指南 跨平台開源函式庫，透過原生協定與 iOS 裝置溝通，不需要 iTunes、不需要越獄。 - 官方 GitHub：https://github.com/libimobiledevice/libimobiledevice - 官方網站：https://www.libimobiledevice.org/ --- ## 安裝 ### macOS（Homebrew） ```bash brew install libimobiledevice # 列出 / 安裝 / 移除 App 需要額外安裝 brew install ideviceinstaller ``` ### Linux（Debian / Ubuntu，從原始碼編譯） ```bash # 安裝相依套件 sudo apt install build-essential pkg-config git autoconf automake libtool-bin \ libplist-dev libusbmuxd-dev libimobiledevice-glue-dev libtatsu-dev libssl-dev usbmuxd # 編譯安裝 git clone https://github.com/libimobiledevice/libimobiledevice.git cd libimobiledevice ./autogen.sh make sudo make install ``` --- ## 首次連線設定 用 USB 接上 iPhone 後，需要先建立信任關係： ```bash # 1. 確認裝置已連接 idevice_id -l # 2. 配對（iPhone 會跳出「信任這部電腦？」，點信任並輸入密碼） idevicepair pair # 3. 驗證配對狀態 idevicepair validate ``` > 如果出現 `Invalid HostID` 或 `SSL error` 錯誤，代表尚未配對或配對已失效，重新執行 pair 即可。 > 裝置重開機後需要解鎖螢幕並重新信任。 --- ## 功能實測總表 以 iPhone 15 Pro Max (iOS 26.4.1) 實測，所有功能分為三類： ### 直接可用（USB 連線 + 配對即可） | 功能 | 指令 | 實測結果 | |------|------|----------| | 列出裝置 UDID | `idevice_id -l` | 正常 | | 配對管理 | `idevicepair pair / validate / unpair` | 正常 | | 裝置名稱 | `idevicename` | 正常 | | 裝置資訊 | `ideviceinfo` | 正常，可查型號、iOS 版本、Wi-Fi MAC 等 | | 裝置日期 | `idevicedate` | 正常 | | 電池狀態 | `ideviceinfo -q com.apple.mobile.battery` | 正常，顯示電量%、充電狀態 | | 儲存空間 | `ideviceinfo -q com.apple.disk_usage` | 正常 | | 診斷資訊 | `idevicediagnostics diagnostics All` | 正常，可查電池循環次數(730)、設計容量(4395mAh) | | 系統日誌 | `idevicesyslog` | 正常，即時串流 | | Crash 報告 | `idevicecrashreport -e <目錄>` | 正常，提取 App 當機、Jetsam、Panic 等日誌 | | 已安裝 App 列表 | `ideviceinstaller list --user` | 正常（需另裝 `ideviceinstaller`） | | App 安裝/移除 | `ideviceinstaller install/uninstall` | 正常（需另裝 `ideviceinstaller`） | | 備份/還原 | `idevicebackup2 backup --full <目錄>` | 正常，需在 iPhone 輸入密碼確認 | | Provisioning Profile | `ideviceprovision list` | 正常 | | 同步資料類別查詢 | `ideviceinfo -q com.apple.mobile.sync_data_class` | 正常，顯示支援聯絡人/行事曆/書籤/備忘錄/郵件 | | 裝置通知監聽 | `idevicenotificationproxy observe <事件>` | 正常，持續監聽 | | 藍牙封包擷取 | `idevicebtlogger <檔案>` | 正常，可匯出 PacketLogger 或 pcap 格式 | | Wi-Fi 同步 | `ideviceinfo -q com.apple.mobile.wireless_lockdown` | 裝置支援（SupportsWifiSyncing: true） | | 重新開機 | `idevicediagnostics restart` | 正常（注意：會真的重開機！） | | 關機 | `idevicediagnostics shutdown` | 正常（注意：會真的關機！） | | 睡眠 | `idevicediagnostics sleep` | 正常 | | 開發者模式查詢 | `idevicedevmodectl list` | 正常，可查看是否已開啟 | | 限制查詢 | `ideviceinfo -q com.apple.mobile.restriction` | 正常 | ### 需要 Developer Image（需 Xcode） 這些功能需要先用 Xcode 掛載 Developer Disk Image 才能使用： | 功能 | 指令 | 條件 | |------|------|------| | 螢幕截圖 | `idevicescreenshot <檔案>` | 需掛載 Developer Image | | 遠端除錯 App | `idevicedebug run ` | 需掛載 Developer Image + debugserver | | 除錯伺服器代理 | `idevicedebugserverproxy ` | 需掛載 Developer Image | | 掛載映像檔 | `ideviceimagemounter` | 需要 DeveloperDiskImage.dmg 檔案 | **掛載方式：** 1. 安裝 Xcode 2. 開啟 Xcode > Window > Devices and Simulators 3. 選擇你的裝置，Xcode 會自動掛載 Developer Image 4. 或手動：`ideviceimagemounter ` ### iOS 17+ 不支援 | 功能 | 指令 | 狀態 | |------|------|------| | 模擬 GPS 定位 | `idevicesetlocation <緯度> <經度>` | iOS 17+ 已不支援，工具明確顯示 "not supported on iOS 17+" | > 替代方案：Xcode 內建的 Simulate Location 功能，或使用第三方工具。 ### 未安裝 / 需額外套件 | 功能 | 指令 | 安裝方式 | |------|------|----------| | 裝置啟用 | `ideviceactivation` | 需另外安裝 `brew install libideviceactivation` | | 進入恢復模式 | `ideviceenterrecovery ` | 已安裝（高風險操作，請謹慎使用） | --- ## 常用指令詳解 ### 裝置資訊 ```bash # 裝置名稱 idevicename # 完整資訊 ideviceinfo # 查詢特定欄位 ideviceinfo -k ProductType # 機型（如 iPhone16,2 = iPhone 15 Pro Max） ideviceinfo -k ProductVersion # iOS 版本 ideviceinfo -k DeviceName # 裝置名稱 ideviceinfo -k WiFiAddress # Wi-Fi MAC # 按 domain 查詢 ideviceinfo -q com.apple.mobile.battery # 電池 ideviceinfo -q com.apple.disk_usage # 儲存空間 ideviceinfo -q com.apple.mobile.sync_data_class # 可同步的資料類型 ideviceinfo -q com.apple.mobile.wireless_lockdown # Wi-Fi 同步狀態 ideviceinfo -q com.apple.mobile.internal # 內部版本資訊 ideviceinfo -q com.apple.mobile.restriction # 限制設定 ideviceinfo -q com.apple.mobile.iTunes # 裝置多媒體能力（螢幕解析度、支援編碼等） ``` ### 系統日誌 ```bash # 即時串流 syslog（類似 macOS Console.app） idevicesyslog # 過濾特定關鍵字 idevicesyslog --match "SpringBoard" # Ctrl+C 停止 ``` ### 已安裝 App 列表 ```bash # 列出使用者安裝的 App（需安裝 ideviceinstaller） ideviceinstaller list --user # 列出系統 App ideviceinstaller list --system # 列出全部 ideviceinstaller list --all ``` ### App 安裝 / 移除 ```bash # 安裝 .ipa ideviceinstaller install app.ipa # 移除 App（用 Bundle ID） ideviceinstaller uninstall com.example.app ``` ### Crash Reports ```bash # 從裝置提取 crash log 到本地目錄 mkdir -p ~/iphone_crashlogs idevicecrashreport -e ~/iphone_crashlogs # 常見檔案類型： # ExcUserFault_* — App 例外/當機 # JetsamEvent-* — 記憶體壓力終止 App # Panics/ — 核心 panic # Baseband/ — 基頻 (通訊模組) 日誌 # DiagnosticLogs/ — 診斷日誌 # SiriSearchFeedback-* — Siri 搜尋回饋 ``` ### 裝置診斷 ```bash # 取得所有診斷資訊 idevicediagnostics diagnostics All # 重要欄位： # GasGauge > CycleCount — 電池循環次數 # GasGauge > DesignCapacity — 電池設計容量 (mAh) # HDMI > Connection — HDMI 連接狀態 # 裝置控制（謹慎使用！） idevicediagnostics restart # 重新開機 idevicediagnostics shutdown # 關機 idevicediagnostics sleep # 睡眠 ``` ### 備份 / 還原 ```bash # 完整備份（iPhone 會要求輸入密碼確認） mkdir -p ~/iphone_backup idevicebackup2 backup --full ~/iphone_backup # 還原備份 idevicebackup2 restore ~/iphone_backup ``` > 備份為未加密格式，包含 App 資料、設定等，不含 Keychain 密碼。 > 完整備份視資料量可能需要數十分鐘。 ### 藍牙封包擷取 ```bash # 擷取藍牙 HCI 封包（PacketLogger 格式） idevicebtlogger bt_capture.log # 擷取為 pcap 格式（可用 Wireshark 開啟） idevicebtlogger -f pcap bt_capture.pcap ``` ### 開發者模式 ```bash # 查看開發者模式狀態 idevicedevmodectl list # 開啟開發者模式（裝置需在設定中確認） idevicedevmodectl enable ``` ### 截圖（需 Developer Image） ```bash # 需先用 Xcode 掛載 Developer Disk Image idevicescreenshot screenshot.png ``` > 如果出現 `Invalid service` 錯誤，代表尚未掛載 Developer Image。 --- ## 注意事項 1. **重開機後需重新信任**：iPhone 重啟後，需解鎖螢幕並再次點「信任這部電腦」 2. **密碼鎖定**：配對和備份等操作都需要在 iPhone 上輸入密碼確認 3. **idevicediagnostics restart/shutdown 會真的執行**：測試時請小心 4. **ideviceenterrecovery 是高風險操作**：會讓裝置進入恢復模式，需用 iTunes/Finder 回復 5. **GPS 模擬在 iOS 17+ 已失效**：Apple 移除了 simulatelocation 服務 6. **Developer Image 功能**：截圖、除錯等需要安裝 Xcode 並掛載 Developer Disk Image