從雲端 Mac 檢查 iOS Universal Links 關聯檔案

發布分支的商品連結在瀏覽器裡正常，裝到測試裝置後卻始終只開啟網頁。這時直接修改 App 的連結處理程式碼，往往會跳過真正的問題：裝置必須先取得網域提供的關聯檔案，確認該網域允許指定 App 接管對應路徑。可以先在雲端 Mac 查清檔案的傳遞鏈路，再讓裝置重新測試。把兩邊的證據分開記錄，比反覆點擊連結更有效。

先固定一個失敗案例

記錄完整連結、預期開啟的 App、實際開啟方式、裝置系統版本與 App 建置版本。至少準備兩條連結：一條應由 App 接管，另一條應留在網頁中。不要只寫「所有連結都不行」；網域、路徑和查詢參數不同，可能會命中完全不同的規則。

也要確認測試方式：點擊連結與在瀏覽器網址列手動輸入網址，不是同一種驗證方式。團隊重新測試時，應使用相同的進入方式。若正式環境和預備環境使用不同網域，應分別建立記錄，不能用一個網域的檔案解釋另一個網域的表現。

把「伺服器目前回傳什麼」和「這台裝置目前如何開啟連結」分成兩欄記錄。前者可以立即複查，後者可能受安裝狀態與快取影響。

檢查檔案是否直接送達

在雲端 Mac 的終端機設定團隊實際控制的網域，不要把 App 的套件識別碼當成網域。關聯檔案應能從 /.well-known/apple-app-site-association 直接取得；檢查時不要讓指令自動跟隨重新導向，否則容易把重新導向後的成功回應，誤判為檔案直接送達。

export APP_DOMAIN='填入团队实际控制的域名'
test "$APP_DOMAIN" != '填入团队实际控制的域名' || exit 1
curl -sS -D aasa-headers.txt \
  -o aasa-body.json \
  "https://${APP_DOMAIN}/.well-known/apple-app-site-association"
cat aasa-headers.txt
wc -c aasa-body.json
plutil -lint -- aasa-body.json

確認 HTTP 回應狀態為 200，沒有指向登入頁或其他路徑的 Location，回應內容不是 HTML 錯誤頁，且 Content-Type 為 application/json。plutil 通過只能證明語法可解析，不能證明規則正確。如果指令因網路錯誤而結束，先檢查網域解析與 TLS 連線；不要把磁碟上舊的 aasa-body.json 當作這次的結果。檢查時可以先刪除舊檔再執行一次，並一併保存回應標頭與內容。

不要只測一個網路入口

若檔案經過快取或反向代理，分別從團隊常用的網路和雲端 Mac 請求同一個網址，比對回應內容及標頭中的快取資訊。如果兩個入口的結果不同，先檢查發布路徑、快取鍵與清除快取的流程。不要靠放寬所有快取規則來掩蓋問題；目標是讓同一網域的關聯檔案穩定回傳預期內容。

核對識別碼與路徑規則

找到 JSON 中 applinks.details 對應的項目，逐字核對由團隊識別碼與 App 套件識別碼組成的 appID。接著把失敗案例的 URL 路徑逐一套入規則。路徑是否區分大小寫、結尾是否有斜線、排除規則是否會先於較廣泛的規則產生影響，都應依檔案實際採用的規則格式逐項驗證；不要因為網頁路由可存取，就推斷 App 一定能接管。

查詢參數可以協助 App 開啟後定位內容，但不能取代 URL 路徑的比對檢查。若團隊正從舊版 paths 遷移到 components，先確認目標裝置的系統支援所採用的寫法，再用實際測試連結驗收；不要在沒有對照案例的情況下，同時修改識別碼、規則和 App 程式碼。

再檢查建置產物與裝置

確認伺服器檔案正確後，核對 App 建置時使用的關聯網域設定。網域項目應指向實際提供該檔案的主機名稱；不能預設不同子網域彼此等價。確認裝到裝置上的確實是剛才檢查的建置版本，而不是另一個發布分支的版本。修改設定後，必須重新建置並安裝；只更新伺服器檔案，不會改變已安裝 App 的設定。

在測試裝置上保留一份「修改前」記錄，再安裝新的建置版本，從相同來源點擊同一條連結。若伺服器已回傳新規則，裝置卻仍維持舊有表現，可以重新安裝 App 後再測，並記錄兩次結果。不應假設關聯檔案會立即完成取得與驗證；不要只憑一次點擊，就斷定某次伺服器修改無效。

依邊界定位，不要全部一起重試

檔案無法取得或回傳重新導向，就處理檔案傳遞鏈路；檔案可以取得，但識別碼或路徑不符，就處理規則或建置設定；兩者都吻合而只有單台裝置失敗，再比較安裝歷程、裝置版本與連結的進入方式。每次只修改一個層面，保留修改前後的回應標頭、檔案內容、建置識別碼和裝置觀察結果，才能確認是哪項修改發揮作用。

把檢查納入發布流程

可以在發布作業中加入一項簡單檢查：請求正式網域的關聯檔案，確認沒有重新導向、狀態正確、JSON 可解析，並用一條應由 App 接管及一條不應接管的路徑核對規則。自動檢查只能涵蓋伺服器與靜態設定；裝置上「點擊後由誰開啟」，仍須用安裝後的建置版本驗收。

最後，把失敗案例、實際回應、比對到的規則和裝置重新測試的結果放在同一份記錄中。下次發生「網頁能開、App 不開」時，值班同事就能從最近一次已確認正常的邊界繼續查，而不必先猜是連結程式碼還是快取。

常見問題