Initial commit: libimobiledevice 操作筆記與參考文件

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 13:25:54 +08:00
commit 4feb33f514
5 changed files with 449 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,17 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 專案概述
+
+這是一個 libimobiledevice 的操作筆記與參考文件目錄，記錄在 macOS 上透過 libimobiledevice 與 iOS 裝置互動的實測結果。
+
+## 測試環境
+
+- macOS (Homebrew 安裝)
+- 測試裝置：iPhone 15 Pro Max (iPhone16,2)，iOS 26.4.1
+- 已安裝：`libimobiledevice` 1.4.0、`ideviceinstaller` 1.2.0
+
+## 文件
+
+- `libimobiledevice-guide.md` — 完整使用指南，含安裝步驟、功能實測總表、各指令詳解
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -0,0 +1,69 @@
+# 快速上手
+
+從零開始，5 分鐘完成安裝並與 iPhone 通訊。
+
+## 1. 安裝
+
+```bash
+brew install libimobiledevice ideviceinstaller
+```
+
+## 2. 接上 iPhone
+
+用 USB 線接上 iPhone，確認偵測到裝置：
+
+```bash
+idevice_id -l
+```
+
+應該會顯示一串 UDID，例如 `00008130-000249A4046B8D3A`。
+
+## 3. 配對
+
+```bash
+idevicepair pair
+```
+
+iPhone 螢幕會跳出「信任這部電腦？」：
+1. 點「信任」
+2. 輸入密碼確認
+
+驗證配對成功：
+
+```bash
+idevicepair validate
+```
+
+## 4. 試試看
+
+```bash
+# 看裝置是什麼型號、跑什麼 iOS
+ideviceinfo -k ProductType
+ideviceinfo -k ProductVersion
+
+# 電池狀態
+ideviceinfo -q com.apple.mobile.battery
+
+# 電池循環次數
+idevicediagnostics diagnostics All
+
+# 列出你裝了哪些 App
+ideviceinstaller list --user
+
+# 即時系統日誌（Ctrl+C 停止）
+idevicesyslog
+```
+
+## 常見問題
+
+**Q: 出現 `Invalid HostID` 或 `SSL error`**
+A: 重新執行 `idevicepair pair`，在 iPhone 上點信任。
+
+**Q: 出現 `Mux error`**
+A: iPhone 剛重開機需要先解鎖螢幕，再重新配對。
+
+**Q: 截圖 `Invalid service`**
+A: 需要用 Xcode 掛載 Developer Image，詳見 [完整指南](libimobiledevice-guide.md)。
+
+**Q: GPS 模擬失敗**
+A: iOS 17+ 已不支援 `idevicesetlocation`。
--- a/README.md
+++ b/README.md
@@ -0,0 +1,28 @@
+# libimobiledevice 筆記
+
+在 macOS 上使用 [libimobiledevice](https://github.com/libimobiledevice/libimobiledevice) 與 iOS 裝置溝通的操作紀錄。
+
+不需要 iTunes、不需要越獄，透過 USB 即可存取裝置資訊、備份還原、App 管理、系統日誌等功能。
+
+## 測試環境
+
+| 項目 | 內容 |
+|------|------|
+| 電腦 | macOS (Homebrew) |
+| 裝置 | iPhone 15 Pro Max (iPhone16,2) |
+| iOS | 26.4.1 |
+| libimobiledevice | 1.4.0 |
+| ideviceinstaller | 1.2.0 |
+
+## 文件索引
+
+| 文件 | 說明 |
+|------|------|
+| [QUICKSTART.md](QUICKSTART.md) | 快速上手，5 分鐘內完成安裝與連線 |
+| [SUMMARY.md](SUMMARY.md) | 功能總表，一覽哪些能用、哪些不行、需要什麼條件 |
+| [libimobiledevice-guide.md](libimobiledevice-guide.md) | 完整指南，所有指令的詳細用法與實測結果 |
+
+## 相關連結
+
+- [libimobiledevice GitHub](https://github.com/libimobiledevice/libimobiledevice)
+- [官方網站](https://www.libimobiledevice.org/)
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -0,0 +1,64 @@
+# 功能總表
+
+以 iPhone 15 Pro Max (iOS 26.4.1) 實測結果。
+
+## 直接可用
+
+USB 連線 + 配對即可，不需要額外條件。
+
+| 功能 | 指令 | 備註 |
+|------|------|------|
+| 列出裝置 | `idevice_id -l` | |
+| 配對管理 | `idevicepair pair/validate/unpair` | iPhone 需解鎖並點信任 |
+| 裝置名稱 | `idevicename` | |
+| 裝置資訊 | `ideviceinfo` | 型號、iOS 版本、Wi-Fi MAC 等 |
+| 裝置日期 | `idevicedate` | |
+| 電池狀態 | `ideviceinfo -q com.apple.mobile.battery` | 電量%、充電狀態 |
+| 儲存空間 | `ideviceinfo -q com.apple.disk_usage` | |
+| 診斷資訊 | `idevicediagnostics diagnostics All` | 電池循環次數、設計容量 |
+| 系統日誌 | `idevicesyslog` | 即時串流，Ctrl+C 停止 |
+| Crash 報告 | `idevicecrashreport -e <目錄>` | App 當機、Jetsam、Panic 等 |
+| App 列表 | `ideviceinstaller list --user` | 需另裝 `ideviceinstaller` |
+| App 安裝 | `ideviceinstaller install <ipa>` | 需另裝 `ideviceinstaller` |
+| App 移除 | `ideviceinstaller uninstall <BundleID>` | 需另裝 `ideviceinstaller` |
+| 備份 | `idevicebackup2 backup --full <目錄>` | iPhone 需輸入密碼確認 |
+| 還原 | `idevicebackup2 restore <目錄>` | |
+| Provisioning Profile | `ideviceprovision list` | |
+| 同步資料查詢 | `ideviceinfo -q com.apple.mobile.sync_data_class` | 聯絡人/行事曆/書籤/備忘錄 |
+| 通知監聽 | `idevicenotificationproxy observe <事件>` | |
+| 藍牙封包擷取 | `idevicebtlogger <檔案>` | 可輸出 pcap 給 Wireshark |
+| Wi-Fi 同步查詢 | `ideviceinfo -q com.apple.mobile.wireless_lockdown` | |
+| 開發者模式查詢 | `idevicedevmodectl list` | |
+| 限制查詢 | `ideviceinfo -q com.apple.mobile.restriction` | |
+| 重新開機 | `idevicediagnostics restart` | 會真的重開機 |
+| 關機 | `idevicediagnostics shutdown` | 會真的關機 |
+| 睡眠 | `idevicediagnostics sleep` | |
+
+## 需要 Developer Image
+
+需先安裝 Xcode 並掛載 Developer Disk Image。
+
+| 功能 | 指令 | 掛載方式 |
+|------|------|----------|
+| 螢幕截圖 | `idevicescreenshot <檔案>` | Xcode > Devices and Simulators 開啟裝置 |
+| 遠端除錯 | `idevicedebug run <BundleID>` | 同上 |
+| 除錯伺服器代理 | `idevicedebugserverproxy <port>` | 同上 |
+| 掛載映像檔 | `ideviceimagemounter <dmg>` | 需要 DeveloperDiskImage.dmg |
+
+## iOS 17+ 不支援
+
+| 功能 | 指令 | 說明 |
+|------|------|------|
+| GPS 模擬定位 | `idevicesetlocation <緯度> <經度>` | Apple 已移除 simulatelocation 服務 |
+
+> 替代方案：Xcode 內建 Simulate Location 或第三方工具。
+
+## 高風險操作
+
+以下指令請謹慎使用：
+
+| 指令 | 風險 |
+|------|------|
+| `idevicediagnostics restart` | 裝置立即重開機，重開後需重新解鎖並配對 |
+| `idevicediagnostics shutdown` | 裝置立即關機 |
+| `ideviceenterrecovery <UDID>` | 進入恢復模式，需用 iTunes/Finder 回復 |
--- a/libimobiledevice-guide.md
+++ b/libimobiledevice-guide.md
@@ -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