文章同步發表在我的個人 Blog

第一次把 App 裝到真的 iPhone：描述檔要綁裝置，以及實機才找得到的問題

準備好的裝機腳本，第一次跑就失敗，會是哪裡出問題？

Day 15 到 17 都預告過要裝到真的 iPhone，今天終於接上手機。

先講結果：App 已經裝到兩支 iPhone 上，連同 Share Extension 一起簽章安裝，兩支手機也加入了同一個家庭。過程中失敗了三次，每一次的原因都不一樣。實際用過之後，還發現一個模擬器和測試都沒找到的問題。

1. 裝機腳本做了什麼

腳本是 scripts/reinstall-devices.sh，主要做三件事：

xcodegen generate --quiet
xcodebuild -scheme Teammate -configuration Release \
  -destination 'generic/platform=iOS' \
  -allowProvisioningUpdates build            # 1. build and sign
xcrun devicectl device install app \
  --device "$UDID" "$APP"                    # 2. install on each phone

免費 Apple 帳號簽出來的 App，7 天後會失效，要重新簽章再裝一次，所以腳本寫成可以重複執行。裝置的 ID 寫在 Config/devices.txt，這個檔案不進版控。

2. 第一次失敗：Xcode 裡的 Apple ID 登入失效

Unable to log in with account '…'. The login details for account '…' were rejected.
No profiles for 'com.….teammate' were found

Xcode → Settings → Accounts 裡，帳號還在，但帳號底下的 Teams 是空的。我推測是登入狀態過期了，Xcode 拿不到簽章要用的 Personal Team，所以找不到描述檔。

處理方式：先 Sign Out，再 Add Apple Account 重新登入。登入後 Teams 底下出現 Personal Team，才算恢復。

3. 第二次失敗：描述檔要綁裝置，Team 底下一支手機都沒有

重新登入後再跑一次，錯誤換了：

Communication with Apple failed: Your team has no devices from which to
generate a provisioning profile. Connect a device to use or manually add
device IDs in Certificates, Identifiers & Profiles.

開發用的描述檔（provisioning profile）會寫明「這個 App 可以裝在哪些裝置上」，所以 Team 底下至少要有一支登記過的裝置，Xcode 才產得出描述檔。Team 頁面也寫著 0 Provisioned Devices。

腳本用的建置目標是 generic/platform=iOS，意思是「任何 iOS 裝置」，沒有指定是哪一支手機。我的判斷是，這樣 Xcode 沒有東西可以登記進 Team；不過這一點我沒有單獨驗證，原因寫在第 6 節。

4. 第三次失敗：開發者模式沒開

把建置目標改成指定手機：

xcodebuild -scheme Teammate -configuration Release \
  -destination "id=<device-udid>" \
  -allowProvisioningUpdates -allowProvisioningDeviceRegistration build

這次錯誤變成：

Developer Mode disabled
To use imsyuan14 for development, enable Developer Mode in Settings → Privacy & Security.

手機接著線，xcrun devicectl list devices 也看得到，狀態是 connected，但開發者模式沒開，就不能拿來當建置目標。看得到裝置，不代表能用。

開啟的步驟，Apple 文件是這樣寫的：在「Privacy & Security」設定裡打開 Developer Mode，跳出警告時按 Restart；重新開機後會再跳出一次確認，在 iOS 上要往上滑、按 Enable、輸入手機密碼。

5. 成功：App 和 Share Extension 都裝進去了

開發者模式打開後，同一個指令就建置成功，再用 devicectl 安裝：

xcrun devicectl device install app --device <device-id> Teammate.app

建置出來的 Teammate.app 裡，PlugIns/TeammateShare.appex 也一起簽章了。第一次打開 App 之前，還要到「設定 → 一般 → VPN 與裝置管理」信任開發者，沒做這一步，App 打不開。

第二支手機是太太的 iPhone 16 Pro。同樣開啟開發者模式、接上 Mac，這次一次就裝成功。Team 底下已經登記過裝置，簽章流程就順了。

免費帳號有幾個數字限制，Apple 的說明寫得很清楚：

You can register up to 3 devices, which expire after 7 days. You can install up to 3 apps per device. Provisioning profiles that enable apps to be installed on a device will expire 7 days from issuance.

也就是最多登記 3 支裝置、每支裝置最多裝 3 個 App，描述檔 7 天後失效。神隊友的 App 加 Share Extension 要兩個 App ID，兩支手機都在上限之內；7 天後要重新建置、重新安裝，這就是腳本要能重複執行的原因。

裝好之後，我這支先建立家庭、拿到邀請碼，太太那支輸入邀請碼加入。

接著是通知權限的說明頁。神隊友沒有遠端推播，所以這一頁先說明：打開 App 一定看得到，想更早知道才需要通知和背景重新整理。

進到首頁，右上角有兩個頭像，代表兩支手機已經在同一個家庭裡：

6. 有一點我沒有驗證

第三次失敗之後，我同時改了兩個地方：建置目標從 generic 換成指定的裝置，也加上 -allowProvisioningDeviceRegistration。手機登記進 Team 之後，就沒辦法再重現第二次的錯誤，所以我不知道只改其中一個行不行。

目前能確定的只有：Team 底下沒有裝置時，用 generic/platform=iOS 建置會失敗；指定手機、開了開發者模式之後，建置成功。

7. 實際用過才發現的第一個問題

在手機上實際操作時發現：我丟一件事，沒設時間，也沒指定誰負責；太太按「知道了」，我再按「我來」認領之後，這張卡片就從我的首頁消失了。

原因是首頁只有三個地方會列卡片：

認領之後，卡片「沒有時間」又「已經有人負責」，三個條件都不符合，就沒有地方顯示。

為什麼模擬器和測試都沒找到？測試只驗證寫在驗收條件裡的情境，這個組合沒有人寫過；模擬器上的示範資料也沒有這種卡片。直到自己在手機上用過一次，才碰到。

修正照 Day 16 的流程走：先寫規格，再寫測試，最後實作。首頁新增一區「還沒排時間」，列出沒有時間、負責人已決定的卡片。新增了 6 個邏輯測試和 3 個畫面測試，完整的 verify.sh 通過，修正後的版本也已經重新裝到兩支手機。

8. 目前的狀態

還沒做的部分：

• 修好的版本，用同一個流程在兩支手機上重測一次
• reinstall-devices.sh 要修：第一次裝機改用指定裝置建置

明天

Day 19 繼續在兩支 iPhone 上實際使用，遇到什麼問題就修什麼。

參考資源

官方文件

• Enabling Developer Mode on a device：Apple，開啟開發者模式的步驟（Privacy & Security、重新開機、再確認一次）
• Developer account overview：Apple，免費帳號（Personal Team）的限制：3 支裝置、每支 3 個 App、描述檔 7 天失效