把外部檔案或資料夾拖進 Xcode 專案時,會跳出對話框讓你選擇 Create groups 還是 Create folder references。這個選擇會直接影響檔案是否被編譯,選錯了會出現「找不到符號」或「檔案沒有被處理」的狀況。
我們可以在專案中手動新增群組(右鍵 > New Group),但手動新增的群組實際上並不存在於專案對應的實體目錄中,被加入群組的檔案仍留在它原本的位置。從外部匯入的群組也遵循同樣邏輯:它只是 Xcode 專案檔裡的一個組織結構,與磁碟上的目錄結構不必然一致。
群組一律以黃色資料夾圖示呈現。這種模式下,群組內的原始碼檔案會被正常編譯,因此當你要使用某個類別時,直接 #import 它的標頭檔即可,不需要額外設定 header search path。
這種方式只是把整個資料夾建立一個「引用」,在專案中以藍色資料夾圖示顯示。
關鍵差異在於:資料夾參照內的檔案不會被編譯。因此如果你匯入的是程式碼檔案,使用時必須自行加入檔案路徑,否則會出現引用資料為空、符號找不到的錯誤。
資料夾參照的真正價值是「資源的整體同步」:因為它連接到了實體目錄,你在 Finder 中往該資料夾新增或刪除檔案時,Xcode 會自動反映這些變動,不必反覆手動加入專案。所以它是管理圖片、字型、設定檔這類資源的理想選擇。
一個常見的排查思路:如果某個類別明明存在、標頭檔也 import 了,卻一直報「file not found」或符號未定義,先去 Build Phases > Compile Sources 確認該 .m 檔是否真的在編譯清單裡——十次有九次就是匯入時選錯了類型。