commit 4feb33f51484e71bf02dbec311f0a879c0b40b36 Author: Timmy Date: Wed Apr 15 13:25:54 2026 +0800 Initial commit: libimobiledevice 操作筆記與參考文件 Co-Authored-By: Claude Opus 4.6 (1M context) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..70df066 --- /dev/null +++ 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` — 完整使用指南，含安裝步驟、功能實測總表、各指令詳解 diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..ff2aa5c --- /dev/null +++ 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`。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..cf26f6d --- /dev/null +++ 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/) diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..56787e5 --- /dev/null +++ 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 ` | 需另裝 `ideviceinstaller` | +| App 移除 | `ideviceinstaller uninstall ` | 需另裝 `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 ` | 同上 | +| 除錯伺服器代理 | `idevicedebugserverproxy ` | 同上 | +| 掛載映像檔 | `ideviceimagemounter ` | 需要 DeveloperDiskImage.dmg | + +## iOS 17+ 不支援 + +| 功能 | 指令 | 說明 | +|------|------|------| +| GPS 模擬定位 | `idevicesetlocation <緯度> <經度>` | Apple 已移除 simulatelocation 服務 | + +> 替代方案：Xcode 內建 Simulate Location 或第三方工具。 + +## 高風險操作 + +以下指令請謹慎使用： + +| 指令 | 風險 | +|------|------| +| `idevicediagnostics restart` | 裝置立即重開機，重開後需重新解鎖並配對 | +| `idevicediagnostics shutdown` | 裝置立即關機 | +| `ideviceenterrecovery ` | 進入恢復模式，需用 iTunes/Finder 回復 | diff --git a/libimobiledevice-guide.md b/libimobiledevice-guide.md new file mode 100644 index 0000000..3417084 --- /dev/null +++ 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 ` | 需掛載 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