C# 編譯器 CSC.exe 完整參數指南：從原始碼到 IL 的建構過程與常用選項詳解

C# 編譯模型：兩階段編譯架構

C# 編譯器 csc.exe 執行第一階段：原始碼 → IL 組件；第二階段：執行時由 JIT 編譯器將 IL → 機器碼。本文專注第一階段的命令列控制。

核心編譯流程

csc [選項] [回應檔] [原始碼檔案]
# 範例
csc /target:exe /out:MyApp.exe /reference:Lib.dll Program.cs Utils.cs

常用選項速查表（按字母序）

關鍵選項深度解析

/target：決定輸出檔性質

• /target:exe：主控台應用程式（預設）
• /target:winexe：Windows GUI 應用程式（無主控台視窗）
• /target:library：類別庫 DLL
• /target:module：.netmodule（無組件資訊，供 /addmodule 合併）

/reference：組件相依性解析

csc /r:System.dll /r:MyLib.dll /r:..\bin\Other.dll Program.cs
# 可用分號或逗號分隔多個組件

專案建議：使用 .csproj 管理參考，避免命令列參考路徑硬編碼。

/debug：偵錯資訊類型

• /debug+ 或 /debug:full：完整偵錯資訊（預設）
• /debug:pdbonly：僅產生 .pdb，不影響 JIT 優化
• /debug-：不產生偵錯資訊（Release 預設）

/define：條件編譯控制

#define DEBUG // 原始碼中
// 或
csc /d:DEBUG /d:TRACE Program.cs
// 原始碼
#if DEBUG
Console.WriteLine("Debug mode");
#endif

/doc：XML 文件自動產生

/// 
計算總和
public int Add(int a, int b) => a + b;

// 編譯
csc /doc:MyLib.xml MyLib.cs
// 產生 MyLib.xml，供 IntelliSense、文件產生器使用

/optimize：程式碼優化

• 啟用：移除無用程式碼、內聯方法、調整指令順序 → 較小、較快的 IL
• Release 建議 /optimize+，Debug 建議 /optimize- 保留對應關係

/checked：整數溢位語意

• /checked+：非 checked/unchecked 區塊的溢位拋 OverflowException
• /checked-：溢位悄悄截斷（預設）
• 建議：明確在程式碼使用 checked { } 區塊，而非仰賴編譯器全域開關

回應檔：管理複雜編譯命令

# MyProject.rsp
/target:library
/out:MyLib.dll
/r:System.Data.dll
/r:Newtonsoft.Json.dll
/define:RELEASE
/optimize+
/warn:4
/warnaserror+
# 來源檔案
Sources\Core\*.cs
Sources\Utils\*.cs

# 執行
csc @MyProject.rsp

• 可包含多個 @file.rsp 串聯
• # 開頭為註解
• Visual Studio 專案實際上即產生回應檔傳給 csc.exe

現代建構系統整合

雖然掌握 csc.exe 參數有助於理解建構本質，但實務專案請使用：

• MSBuild / .csproj：標準專案格式，支援多目標、NuGet、增量建構
• dotnet CLI：dotnet build、dotnet publish 封裝 MSBuild
• IDE 整合：Visual Studio、VS Code、Rider 透過專案系統間接呼叫 csc.exe

理解 csc.exe 參數如同理解編譯器引擎蓋，能在診斷建構錯誤、自訂建構流程、遷移舊專案時發揮關鍵作用。