在多人合作的 iOS 專案中,工程檔案常需要依不同開發者環境調整。例如變更證書、Bundle Identifier、Build Settings,或移除暫時無法編譯的 target。若每次都手動修改,不僅繁瑣,也容易出錯。
pbxprojHelper 的目標,是把工程檔案的常見修改記錄下來,並在需要時快速套用。它支援將修改存成 JSON 設定檔,下次只要匯入設定,就能自動套用到目前的工程檔案。
除了圖形介面版本,它也提供命令列工具,方便在自動化流程或終端機中使用。
常見痛點包括:第一次取得新分支時需要重新設定;修改程式碼前後暫存 project.pbxproj,導致本地設定被還原;多人協作時不同分支需要不同編譯選項;CI 打包時需要固定證書與參數。
這些操作本身不難,但重複性高。pbxprojHelper 把這些設定抽象成可重複使用的配置,大幅降低人工操作成本。
Xcode 工程檔的核心是 project.pbxproj。它本質上是一種屬性列表格式,可視為由字典與陣列組成的樹狀結構。工具要做的是比較兩個工程檔的差異,找出新增、刪除與修改的節點。
比較時會遞歸走訪每個節點。若節點是字典,就比較鍵與子節點;若節點是陣列,則比較元素差異。最終會產生包含 insert、remove、modify 三種操作的 JSON 設定。
套用 JSON 設定時,工具會解析路徑,例如某個 build setting 的層級位置,然後沿著路徑找到目標節點。到達終點後,再依操作類型進行新增、刪除或替換。
這種設計讓設定檔可以跨分支使用。只要專案結構相近,就能把同一份個人化配置套用到不同分支或不同工作副本。
工程檔內容龐雜,直接閱讀並不友善。pbxprojHelper 提供樹狀預覽,讓使用者能快速瀏覽工程結構。若需要尋找特定設定,也可透過關鍵字過濾。

pbxprojHelper 主視窗與過濾功能
過濾時會遞歸搜尋節點與子節點,忽略大小寫,讓使用者能迅速定位 build settings、檔案引用或 target 設定。
因為工具會修改工程檔,所以備份機制很重要。pbxprojHelper 會在修改前備份 project.pbxproj,讓使用者在必要時能還原。
考量到大型工程檔備份會佔用空間,工具通常只保留最近一次備份,而不是無限累積歷史版本。
命令列版本提供 compare、apply、revert、convert 等指令。compare 可比較修改後的工程檔並產生 JSON;apply 可將 JSON 套用到工程檔;revert 可還原備份;convert 則可將屬性列表轉為 XML 格式。
命令列工具適合用於腳本或自動化流程。例如,在 CI 中先用固定 JSON 設定套用證書與編譯參數,再進行打包。
這個工具一開始是為了解決個人痛點,因此需求並非一次到位,而是在使用中逐步調整。例如,如何比較工程檔、如何表示路徑、如何套用修改、如何處理中文編碼,都需要反覆驗證。
在處理 project.pbxproj 時,也要特別注意編碼與格式。若直接寫入,中文可能出現亂碼,因此需要將非 ASCII 字元轉為適當表示方式。
pbxprojHelper 的價值不在於功能多麼龐大,而在於它把重複且易錯的工程配置變成可重複使用的流程。對於需要频繁切換分支、修改編譯參數或維護多人專案的開發者來說,它能顯著提升效率。