R CMD check 在 Mac 上怎麼做？2026 科研包驗收

開始前：建立可複核的 macOS arm64 基線

R CMD check 的結果會受到 R 版本、執行架構、系統函式庫、編譯器與專案內容影響。若只留下「通過」截圖，日後很難分辨問題是由程式碼變更、依賴更新，還是工具鏈差異引起。因此，開始驗收前先固定檢查對象，並將環境資訊和專案提交版本一併記錄。

在終端機執行以下指令，將結果存入驗收紀錄：

R --version
Rscript -e 'cat(R.version$platform, "\n")'
sw_vers
xcode-select -p
git rev-parse HEAD

這些命令分別協助確認 R 版本、R 回報的平台資訊、macOS 版本、目前選用的開發者工具目錄，以及 Git 專案提交識別碼。R.version$platform 可用來確認目前執行的 R 所屬平台；macOS 上的 R 安裝與平台細節，應對照 R 官方安裝與管理手冊。若無法從紀錄判定實際使用的架構，先釐清 R 的安裝來源及啟動方式，不要只根據 Mac 機型推定檢查架構。

在 Mac 上執行檢查前要先準備什麼？至少要有乾淨的專案副本、可辨識的提交版本、R 環境紀錄，以及與套件編譯需求相符的命令列工具。若要檢查外部系統函式庫，也要記下其安裝方式及版本，避免把某台機器上的私有設定誤當成專案必要條件。

Apple Command Line Tools 與完整 Xcode 並非可任意互換的名稱。依套件需要，確認編譯器、標頭檔及連結工具是否可用；Apple 說明了命令列工具的安裝方式及選擇命令列工具目錄的設定方式。可先用 xcode-select -p 檢查目前選用位置；若目錄不符，再按 Apple 文件核對可選工具及切換方式，不要在不了解專案依賴前直接安裝或更換整套工具。

先封裝：檢查真正要交付的原始碼包

只在工作目錄內執行測試，無法充分證明最後要交給合作者或發布的原始碼包包含必要檔案。資料檔、文件、範例，甚至某些程式碼，都可能因忽略規則或封裝設定而沒有進入成品。較穩妥的順序是先建置來源套件，再對建置完成的檔案執行檢查。

R CMD build path/to/package
R CMD check package_版本.tar.gz

將 path/to/package 換成套件目錄，並把第二行的檔名換成實際產生的來源套件檔。R CMD build 與 R CMD check 的用途及呼叫方式，應以 R 官方套件建置與檢查說明及 Writing R Extensions 手冊為準；實際選項可能隨 R 發行版本或專案需求改變。

建置後保留來源套件、終端機完整輸出與檢查目錄，並確認檢查所用的檔案確實是剛建置的那一份。不要只記錄最後一行摘要：需要交接時，檢查目錄中的失敗步驟、測試輸出與警告內容，才足以供其他維護者重現。

執行 R CMD check Mac：判讀結果與保留紀錄

不同級別的提示不能被簡化成「成功」或「失敗」。先依檢查輸出中的 ERROR、WARNING、NOTE 分類，再閱讀其對應步驟及細節；這些標記代表不同類型的檢查結果，但實際處理方式仍取決於報告內容、套件用途及目標平台。R 手冊說明了 R CMD check 的執行流程與檢查項目，可用來核對特定訊息來自哪個階段。

例如，可在驗收紀錄中逐項列出：

• 檢查命令、來源套件檔名，以及套件版本或提交識別碼。
• 執行環境的 R、macOS、平台與命令列工具目錄資訊。
• ERROR、WARNING、NOTE 的原文摘要、出現步驟及處理結果。
• 尚未處理的項目、已知限制，以及計畫另行檢查的平台。

若要套用較接近提交情境的檢查，可依 R 手冊確認 --as-cran 的用途及目前選項，再以適用的命令執行；它仍不是 CRAN 接收保證，也不能代替其他平台的實際檢查。CRAN 的提交與維護要求可能會更新，交付或送件前應再次比對現行 CRAN Repository Policy，不要以某次本機結果推定符合所有政策。

編譯階段：從失敗步驟追查工具鏈與依賴

含有 C、C++、Fortran 程式碼，或連結外部系統函式庫的科研包，可能在不同平台遇到編譯器、標頭檔、函式庫名稱或架構不一致等問題。遇到編譯錯誤時，先看完整紀錄中第一個實際失敗的編譯或連結命令，而不是從最後一段摘要反向猜測。

Mac 上 R 包編譯錯誤應先看哪裡？先依序核對套件要求的編譯工具是否存在、錯誤訊息提到的標頭檔是否可找到、連結階段是否缺少函式庫，再檢查該函式庫是否與正在執行的 R 架構相符。命令列工具的選擇及環境設定可參照 Apple 的工具目錄設定文件；R 在 macOS 上的建置與安裝細節則可查閱 R 官方管理手冊。

定位時使用乾淨的專案副本，將錯誤分成三類：套件程式碼無法編譯、外部依賴未安裝或未被找到、工具鏈本身不可用或選擇不正確。接著只重現失敗步驟，記錄修改前後的命令與輸出。不要把「安裝完整 Xcode」或「更換編譯器」當成所有套件共用的修復方式；有些問題只需修正套件的依賴宣告或路徑，盲目更換工具反而會讓原本的環境難以重現。

測試與文件：在乾淨工作階段確認科研流程

套件通過一般測試，不一定代表範例、vignette 或說明文件也能在另一位使用者的環境順利執行。測試應以乾淨工作階段開始，檢查是否有程式依賴個人工作目錄、未提交的資料檔、預先載入的套件，或本機才存在的設定。對已安裝套件進行測試時，可依需求查閱 tools 對已安裝套件測試的說明，並將結果與原始碼檢查紀錄分開保存。

文件或 vignette 檢查失敗時，怎樣縮小範圍？先從錯誤所屬的文件或範例開始，確認必要資料是否已隨來源套件封裝、程式碼區塊是否依賴互動式工作階段，以及產生文件所需的套件或系統工具是否已列入依賴。再單獨重跑該段內容，對照完整檢查日誌；不要為了讓檢查通過而直接略過文件執行，除非專案已明確評估其影響並留下理由。

科研程式也要特別留意隨機數、浮點計算與不同平台的結果差異。預期輸出及允許誤差應由專案根據演算法與科研用途事先定義，而不是照搬沒有依據的通用數值門檻。若差異涉及科學結論，應保留輸入資料、執行環境與比較方法，交由套件維護者判斷是否屬於合理的平台差異。

交接前：把平台範圍寫清楚

交付前可用以下對照表決定下一步。表中的「已檢查」只代表完成相應環境中的驗收，不應延伸解讀成其他平台或發布機構已認可。

Mac 檢查通過，就等於 Windows 和 Linux 都能用嗎？不等於。作業系統、編譯工具與系統依賴可能不同；若套件宣稱支援這些平台，就要在相應環境執行檢查並記錄結果。若目標是提交 CRAN，還應將實際檢查範圍和未涵蓋平台寫入交接資料，並依現行 CRAN 政策重新核對提交要求。

實驗室沒有本地 Mac，怎樣完成 macOS 驗收？可先在現有 Windows 或 Linux 環境檢查與平台無關的程式碼，再安排能提供原生 macOS 的驗收環境，重跑封裝、編譯與完整測試。若專案依賴圖形介面或 Mac 特有元件，純粹檢視程式碼或使用非 macOS 環境都無法代替該平台的實際驗證。評估遠端 macOS 時，可先參考遠端 Mac 使用方案；若要了解其他相關資源，也可由NodeMini 網站入口查看。

交接紀錄至少要能回答：檢查的是哪個提交與來源套件、使用什麼 R 和 macOS 環境、哪些錯誤已處理、哪些平台尚未覆蓋，以及後續由誰完成驗收。這樣接手者才能判斷結果的適用範圍，而不會把一次 macOS arm64 的 R CMD check 誤當成整個發布流程已完成。

若目前依靠借用同事的 Mac，常見限制是排期不固定、環境狀態難以重現，而且實驗室 HPC 通常不能直接代替 macOS；只有自動化檢查時，也可能不方便互動式排查本機工具鏈問題。對偶爾需要完成發布前驗收的課題組，按專案週期租用真實 Mac，能讓維護者在 macOS 環境內重跑檢查並保留紀錄；若長期持續使用，或需要特定實體介面與固定工作站，則應另行評估自購設備是否更合適。

下一步：若實驗室暫時沒有 Mac，可先依NodeMini 的遠端 Mac 方案安排一次符合專案需要的 macOS 驗收，再按發布週期決定是否需要持續租用。完成 R CMD check Mac 檢查後，仍要依套件支援目標補做 Windows、Linux 或 CRAN 相關核對。