Initial commit: libimobiledevice 操作筆記與參考文件
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
271
libimobiledevice-guide.md
Normal file
271
libimobiledevice-guide.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# 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 <BundleID>` | 需掛載 Developer Image + debugserver |
|
||||
| 除錯伺服器代理 | `idevicedebugserverproxy <port>` | 需掛載 Developer Image |
|
||||
| 掛載映像檔 | `ideviceimagemounter` | 需要 DeveloperDiskImage.dmg 檔案 |
|
||||
|
||||
**掛載方式：**
|
||||
1. 安裝 Xcode
|
||||
2. 開啟 Xcode > Window > Devices and Simulators
|
||||
3. 選擇你的裝置，Xcode 會自動掛載 Developer Image
|
||||
4. 或手動：`ideviceimagemounter <DeveloperDiskImage.dmg>`
|
||||
|
||||
### iOS 17+ 不支援
|
||||
|
||||
| 功能 | 指令 | 狀態 |
|
||||
|------|------|------|
|
||||
| 模擬 GPS 定位 | `idevicesetlocation <緯度> <經度>` | iOS 17+ 已不支援，工具明確顯示 "not supported on iOS 17+" |
|
||||
|
||||
> 替代方案：Xcode 內建的 Simulate Location 功能，或使用第三方工具。
|
||||
|
||||
### 未安裝 / 需額外套件
|
||||
|
||||
| 功能 | 指令 | 安裝方式 |
|
||||
|------|------|----------|
|
||||
| 裝置啟用 | `ideviceactivation` | 需另外安裝 `brew install libideviceactivation` |
|
||||
| 進入恢復模式 | `ideviceenterrecovery <UDID>` | 已安裝（高風險操作，請謹慎使用） |
|
||||
|
||||
---
|
||||
|
||||
## 常用指令詳解
|
||||
|
||||
### 裝置資訊
|
||||
|
||||
```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
|
||||
Reference in New Issue
Block a user