8.5 KiB
8.5 KiB
libimobiledevice 使用指南
跨平台開源函式庫，透過原生協定與 iOS 裝置溝通，不需要 iTunes、不需要越獄。
- 官方 GitHub：https://github.com/libimobiledevice/libimobiledevice
- 官方網站：https://www.libimobiledevice.org/
安裝
macOS（Homebrew）
brew install libimobiledevice
# 列出 / 安裝 / 移除 App 需要額外安裝
brew install ideviceinstaller
Linux（Debian / Ubuntu，從原始碼編譯）
# 安裝相依套件
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 後，需要先建立信任關係：
# 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 <BundleID> |
需掛載 Developer Image + debugserver |
| 除錯伺服器代理 | idevicedebugserverproxy <port> |
需掛載 Developer Image |
| 掛載映像檔 | ideviceimagemounter |
需要 DeveloperDiskImage.dmg 檔案 |
掛載方式：
- 安裝 Xcode
- 開啟 Xcode > Window > Devices and Simulators
- 選擇你的裝置，Xcode 會自動掛載 Developer Image
- 或手動：
ideviceimagemounter <DeveloperDiskImage.dmg>
iOS 17+ 不支援
| 功能 | 指令 | 狀態 |
|---|---|---|
| 模擬 GPS 定位 | idevicesetlocation <緯度> <經度> |
iOS 17+ 已不支援，工具明確顯示 "not supported on iOS 17+" |
替代方案：Xcode 內建的 Simulate Location 功能，或使用第三方工具。
未安裝 / 需額外套件
| 功能 | 指令 | 安裝方式 |
|---|---|---|
| 裝置啟用 | ideviceactivation |
需另外安裝 brew install libideviceactivation |
| 進入恢復模式 | ideviceenterrecovery <UDID> |
已安裝（高風險操作，請謹慎使用） |
常用指令詳解
裝置資訊
# 裝置名稱
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 # 裝置多媒體能力（螢幕解析度、支援編碼等）
系統日誌
# 即時串流 syslog（類似 macOS Console.app）
idevicesyslog
# 過濾特定關鍵字
idevicesyslog --match "SpringBoard"
# Ctrl+C 停止
已安裝 App 列表
# 列出使用者安裝的 App（需安裝 ideviceinstaller）
ideviceinstaller list --user
# 列出系統 App
ideviceinstaller list --system
# 列出全部
ideviceinstaller list --all
App 安裝 / 移除
# 安裝 .ipa
ideviceinstaller install app.ipa
# 移除 App（用 Bundle ID）
ideviceinstaller uninstall com.example.app
Crash Reports
# 從裝置提取 crash log 到本地目錄
mkdir -p ~/iphone_crashlogs
idevicecrashreport -e ~/iphone_crashlogs
# 常見檔案類型：
# ExcUserFault_* — App 例外/當機
# JetsamEvent-* — 記憶體壓力終止 App
# Panics/ — 核心 panic
# Baseband/ — 基頻 (通訊模組) 日誌
# DiagnosticLogs/ — 診斷日誌
# SiriSearchFeedback-* — Siri 搜尋回饋
裝置診斷
# 取得所有診斷資訊
idevicediagnostics diagnostics All
# 重要欄位：
# GasGauge > CycleCount — 電池循環次數
# GasGauge > DesignCapacity — 電池設計容量 (mAh)
# HDMI > Connection — HDMI 連接狀態
# 裝置控制（謹慎使用！）
idevicediagnostics restart # 重新開機
idevicediagnostics shutdown # 關機
idevicediagnostics sleep # 睡眠
備份 / 還原
# 完整備份（iPhone 會要求輸入密碼確認）
mkdir -p ~/iphone_backup
idevicebackup2 backup --full ~/iphone_backup
# 還原備份
idevicebackup2 restore ~/iphone_backup
備份為未加密格式，包含 App 資料、設定等，不含 Keychain 密碼。 完整備份視資料量可能需要數十分鐘。
藍牙封包擷取
# 擷取藍牙 HCI 封包（PacketLogger 格式）
idevicebtlogger bt_capture.log
# 擷取為 pcap 格式（可用 Wireshark 開啟）
idevicebtlogger -f pcap bt_capture.pcap
開發者模式
# 查看開發者模式狀態
idevicedevmodectl list
# 開啟開發者模式（裝置需在設定中確認）
idevicedevmodectl enable
截圖（需 Developer Image）
# 需先用 Xcode 掛載 Developer Disk Image
idevicescreenshot screenshot.png
如果出現
Invalid service錯誤，代表尚未掛載 Developer Image。
注意事項
- 重開機後需重新信任：iPhone 重啟後，需解鎖螢幕並再次點「信任這部電腦」
- 密碼鎖定：配對和備份等操作都需要在 iPhone 上輸入密碼確認
- idevicediagnostics restart/shutdown 會真的執行：測試時請小心
- ideviceenterrecovery 是高風險操作：會讓裝置進入恢復模式，需用 iTunes/Finder 回復
- GPS 模擬在 iOS 17+ 已失效：Apple 移除了 simulatelocation 服務
- Developer Image 功能：截圖、除錯等需要安裝 Xcode 並掛載 Developer Disk Image