雲端 Mac 上的 iOS 下載檔案格式檢核
iOS 下載介面回報成功,預覽頁卻打不開附件:有時拿到的是登入失效後的錯誤頁,有時伺服器把所有內容都標示為通用二進位資料,也可能檔案只下載了一半。在雲端 Mac 上重現這類問題,不必一開始就串接實際服務。先把「宣告了什麼格式、內容看起來像什麼、能否完整解析」分開,以固定測試樣本建立三層驗收,再接回下載流程。
先定義允許接收的格式
假設附件入口只接收 PNG、JPEG 和 PDF。規則應由業務白名單決定,而不是靠檔名猜測。檔名可以顯示給使用者,但不能用來決定要交給哪個解析器,更不能直接拼接成儲存路徑。
驗收順序是:確認 HTTP 狀態符合介面契約、限制實際接收的位元組數、核對回應 MIME 與檔頭,最後執行各格式專屬的解析。Content-Length 只能作為提前拒絕的依據之一;無論它缺失或小於實際大小,都不能取代累計接收位元組數的上限。
檔頭吻合只表示「看起來像這種格式」,不是完整性證明,更不是安全性證明。只有 PNG 簽章的檔案,仍然無法顯示。
如果介面明確約定回傳通用二進位資料,可以針對該入口設定例外;不要讓所有下載都套用同樣寬鬆的規則。以下實作採用嚴格模式,缺少 MIME 或宣告與內容衝突時一律拒絕。
用純函式隔離類型判定
在遠端 macOS 終端機中建立 type-check.swift,儲存以下內容。函式只接收檔頭資料與 MIME,不連線、不存取使用者目錄,方便後續移入應用程式的測試目標。程式碼中的樣本只用來驗證分類規則,不代表有效的圖片或文件。
import Foundation
enum FileKind: String {
case png, jpeg, pdf
var mime: String {
switch self {
case .png: return "image/png"
case .jpeg: return "image/jpeg"
case .pdf: return "application/pdf"
}
}
}
enum TypeFailure: Error {
case unknownHeader
case missingMIME
case conflictingMIME
}
func classify(
prefix: Data,
declaredMIME: String?
) throws -> FileKind {
let bytes = Array(prefix.prefix(8))
let kind: FileKind
if bytes.starts(with: [137, 80, 78, 71, 13, 10, 26, 10]) {
kind = .png
} else if bytes.starts(with: [255, 216, 255]) {
kind = .jpeg
} else if bytes.starts(with: Array("%PDF-".utf8)) {
kind = .pdf
} else {
throw TypeFailure.unknownHeader
}
guard let declaredMIME else {
throw TypeFailure.missingMIME
}
let mime = declaredMIME
.split(separator: ";", omittingEmptySubsequences: false)[0]
.trimmingCharacters(in: .whitespacesAndNewlines)
.lowercased()
guard mime == kind.mime else {
throw TypeFailure.conflictingMIME
}
return kind
}
struct Fixture {
let head: [UInt8]
let mime: String?
let expected: FileKind?
}
let fixtures: [Fixture] = [
.init(
head: [137, 80, 78, 71, 13, 10, 26, 10],
mime: "IMAGE/PNG; charset=binary",
expected: .png
),
.init(head: [255, 216, 255], mime: "image/jpeg", expected: .jpeg),
.init(
head: Array("%PDF-1.7".utf8),
mime: "application/pdf",
expected: .pdf
),
.init(
head: Array("<html>error".utf8),
mime: "application/pdf",
expected: nil
),
.init(head: [137, 80, 78], mime: "image/png", expected: nil),
.init(head: [255, 216, 255], mime: "image/png", expected: nil),
.init(head: [255, 216, 255], mime: nil, expected: nil)
]
for (index, fixture) in fixtures.enumerated() {
let actual = try? classify(
prefix: Data(fixture.head),
declaredMIME: fixture.mime
)
guard actual == fixture.expected else {
fatalError("Fixture mismatch at index \(index)")
}
}
執行 xcrun swift type-check.swift,全部符合預期時不會輸出訊息,直接結束;斷言失敗則以非零狀態碼結束。這裡直接使用標頭字串,是為了涵蓋大小寫與參數的處理;如果應用程式讀取的是已正規化的 MIME,也應保留原始回應標頭以利排查問題,但不要記錄驗證身分所用的欄位。
接入下載時不要將整個檔案讀入記憶體
使用下載任務時,先檢查任務錯誤、回應狀態與暫存檔是否存在,再用 FileHandle 讀取最多八個位元組,交給判定函式。檔案控制代碼使用 defer 關閉。不要為了讀取簽章而執行整個檔案的 Data(contentsOf:),否則大型附件會讓一次簡單檢查造成記憶體用量暴增。
以串流方式接收時,必須累積前八個位元組,不能假設第一次回呼就包含完整簽章;回呼傳入的資料分段與檔案格式邊界無關。收到的資料不足以分類時,應繼續等待,直到收齊八個位元組或傳輸結束,再做判定。
下載任務提供的暫存檔,需要及時移至應用程式控管的暫存目錄。使用內部產生的檔名,通過檢核後才移至正式位置;任何步驟失敗,都要清除暫存檔。使用者提供的名稱,只能經過處理後作為顯示欄位。
為完整解析補上第二組樣本
通過類型識別後,圖片還必須透過 ImageIO 建立影像來源,並實際產生影像。能讀取尺寸或建立影像來源,不代表後續解碼一定成功。應先限制寬高、總像素數與影格數,再觸發所需影格的解碼,避免小型壓縮檔展開成龐大的記憶體物件。
PDF 可以使用 PDFKit 嘗試建立文件,檢查頁數、加密狀態與需要存取的頁面。如果業務需要產生預覽,就應實際繪製目標頁面;成功建立文件物件,不代表每一頁都能正確顯示。
準備真正有效的檔案,以及只保留檔頭、截斷尾端、修改中間位元組的副本。截斷樣本不一定都會遭到底層解析器拒絕:有些解析器具備容錯能力,因此測試應針對「能否完成應用程式要求的操作」設下斷言,而不是假設任何位元組變動都必須導致失敗。
將失敗原因轉成可追查的結果
接入專案的測試目標後,應分別回報傳輸失敗、格式未知、宣告衝突、超出配額與解析失敗。不要一律歸為「檔案損毀」,否則後端 MIME 設定錯誤與用戶端解碼問題就會混在一起。
每次迴歸測試都保留樣本編號、實際位元組數、正規化後的 MIME、候選類型與處理階段。樣本應優先使用人工產生、不含敏感內容的檔案;如果失敗附件含有業務資料,不應隨測試報告自動上傳。
最後檢查三件事:錯誤頁不會進入預覽器、截斷樣本不會被當成已通過完整性驗證的檔案、失敗路徑沒有留下正式附件。雲端 Mac 負責執行固定樣本與模擬器流程;大型檔案在實機上的記憶體表現,仍需另行驗收。兩者分開記錄,才能清楚知道這道檢核關卡究竟證明了什麼。
常見問題
MIME 宣告與檔頭不一致時,應該自動修正格式嗎?
預設拒絕並記錄衝突原因。若業務確實允許通用二進位回應,應只對特定入口建立例外,仍須通過檔頭檢查及完整解析。
檔頭相符就代表檔案沒有損壞嗎?
不是。檔頭只能辨識候選格式,遭截斷的檔案也可能相符。圖片需要完整解碼檢查,PDF 則需要解析及符合業務需求的頁面檢核。
依照專案需求,決定租用哪款 Mac
如果需要原生編譯或使用模擬器除錯,租用一台 Apple Silicon 專屬實體 Mac 進行驗證會很合適;如果是長期全職開發,而且工作地點固定,也可以比較買機的成本。按日租用更有彈性,持續使用則可考慮月租或季租。
租用遠端 Mac