iOS Xcode 專案中控制 NSLog 輸出：DEBUG/RELEASE 模式條件編譯最佳實踐

iOS Xcode 專案中控制 NSLog 輸出最佳實踐

開發階段大量使用 NSLog 除錯是常態，但發布版本保留這些日誌會洩露敏感資訊、影響效能、佔用儲存空間。本文介紹透過**巨集定義**與 **Xcode Build Configuration** 實現：Debug 模式完整輸出、Release 模式自動禁用/重導向，且不修改業務代碼。

核心原理：條件編譯巨集

利用 Xcode 預設的 DEBUG=1 (Debug 配置) 與 DEBUG=0 (Release 配置) 差異，定義條件編譯巨集：

方案一：簡易版 (僅控制輸出開關)

// PrefixHeader.pch 或專用 DebugLog.h
#ifdef DEBUG
    #define DLog(fmt, ...) NSLog((@"%s [Line %d] " fmt), __PRETTY_FUNCTION__, __LINE__, ##__VA_ARGS__)
#else
    #define DLog(...) do {} while (0)
#endif

// 保留錯誤日誌永遠輸出
#define ELog(fmt, ...) NSLog((@"[ERROR] %s [Line %d] " fmt), __PRETTY_FUNCTION__, __LINE__, ##__VA_ARGS__)

方案二：進階版 (支援日誌等級、檔案寫入、遠端上傳)

// DDLog.h - 參考 CocoaLumberjack 設計模式
typedef NS_ENUM(NSUInteger, DDLogLevel) {
    DDLogLevelOff     = 0,
    DDLogLevelError   = 1,
    DDLogLevelWarning = 2,
    DDLogLevelInfo    = 3,
    DDLogLevelDebug   = 4,
    DDLogLevelVerbose = 5
};

#ifndef DDLogLevel
    #ifdef DEBUG
        #define DDLogLevel DDLogLevelVerbose
    #else
        #define DDLogLevel DDLogLevelWarning
    #endif
#endif

#define DDLog(level, fmt, ...) \
    do { \
        if (level <= DDLogLevel) { \
            NSLog((@"<%@> %s [Line %d] " fmt), @#level, __PRETTY_FUNCTION__, __LINE__, ##__VA_ARGS__); \
        } \
    } while (0)

// 使用範例
DDLog(DDLogLevelDebug, @"使用者登入: %@", username);
DDLog(DDLogLevelError, @"網路請求失敗: %@", error);

Xcode 專案配置步驟 (圖文對應)

1. 專案導航器 選中專案 → Targets → Build Settings
2. 搜尋 Preprocessor Macros (或 GCC_PREPROCESSOR_DEFINITIONS)
3. Debug 配置：確認包含 DEBUG=1 (Xcode 預設已有)
4. Release 配置：確認 **不包含** DEBUG 或設為 DEBUG=0
5. 若使用 Swift 混編：在 Swift Compiler - Custom Flags → Other Swift Flags 加入 -D DEBUG (Debug) / 留空 (Release)

圖示說明 (對應原文截圖流程)

• 截圖 1：Build Settings 搜尋 Preprocessor Macros 位置
• 截圖 2：Debug 配置展開，顯示 DEBUG=1
• 截圖 3：Release 配置展開，無 DEBUG 定義
• 截圖 4：巨集定義在 .pch 或 .h 檔案中
• 截圖 5：業務代碼中使用 DLog 替代 NSLog
• 截圖 6：Debug 運行時 Console 輸出完整日誌
• 截圖 7：Release 打包後 Console 無除錯輸出

進階：Release 版本保留關鍵日誌至檔案/伺服器

生產環境仍需關鍵錯誤追蹤，建議整合成熟日誌框架：

• CocoaLumberjack：非同步、多目標 (Console/檔案/網路)、日誌等級、自動輪轉
• SwiftyBeaver：Swift 原生、彩色輸出、加密、雲端平台
• XCGLogger：詳細上下文 (執行緒、檔案、行號)、自訂格式化

// CocoaLumberjack 快速整合 (Podfile)
pod 'CocoaLumberjack/Swift'

// AppDelegate.swift
import CocoaLumberjack

DDLog.add(DDOSLogger.sharedInstance)  // Xcode Console
let fileLogger = DDFileLogger()
fileLogger.rollingFrequency = 86400   // 24 小時輪轉
fileLogger.logFileManager.maximumNumberOfLogFiles = 7
DDLog.add(fileLogger)

// 使用
DDLogDebug("除錯資訊")
DDLogError("嚴重錯誤: \(error)")

最佳實踐總結

常見誤區提醒

• ❌ 直接在代碼中 #ifdef DEBUG 包裹每行 NSLog → 維護困難、程式碼雜亂
• ❌ Release 版仍輸出 NSLog → 效能損耗、資安風險、App Store 審核風險
• ❌ 使用 #define NSLog(...) 覆蓋系統函數 → 影響第三方庫、行為不可預期
• ✅ 統一巨集入口、語意化命名 (DLog/ELog)、配合成熟框架