C# DateTime 格式化完全指南：標準、自訂、最佳實務

前言

日期時間格式化是每位 C# 開發者的必修課。本文系統整理 DateTime.ToString 的標準格式字串、自訂格式模式、文化特性控制、效能技巧與常見陷阱，並提供可直接複製的速查表。

一、標準格式字串（Standard Format Strings）

單一字元指定符，對應 DateTimeFormatInfo 屬性，受 CultureInfo 影響。

二、自訂格式模式（Custom Format Patterns）

組合下列模式字元構建任意格式，區分大小寫。

常用組合範例

var dt = new DateTime(2024, 6, 15, 15, 30, 45, 123, DateTimeKind.Local);

dt.ToString("yyyy-MM-dd")           // 2024-06-15
dt.ToString("yyyy/MM/dd HH:mm:ss")  // 2024/06/15 15:30:45
dt.ToString("yyyy年MM月dd日")        // 2024年06月15日 (需配合 zh-TW culture)
dt.ToString("HH:mm:ss.fff")         // 15:30:45.123
dt.ToString("o")                    // 2024-06-15T15:30:45.1230000+08:00 (往返/序列化最佳)

三、文化特性控制 (IFormatProvider)

// 明確指定文化特性，避免伺服器預設文化導致輸出不一致
var tw = new CultureInfo("zh-TW");
var us = CultureInfo.InvariantCulture; // 固定不變文化，適合日誌、API、資料庫

dt.ToString("D", tw)   // 2024年6月15日
dt.ToString("D", us)   // Saturday, 15 June 2024 (Invariant 以英文為基準)

最佳實務：所有對外輸出（API JSON、資料庫儲存、日誌）一律使用 CultureInfo.InvariantCulture 或 ISO 8601 (o/O/s/u)；僅 UI 顯示才套用使用者文化特性。

四、DateTime 實用屬性與方法速查

var now = DateTime.Now;
now.Year / now.Month / now.Day / now.Hour / now.Minute / now.Second / now.Millisecond
now.DayOfWeek / now.DayOfYear / now.Ticks / now.TimeOfDay
now.Date                     // 日期部分 (時間歸零)
now.ToLocalTime() / now.ToUniversalTime()
now.AddDays(7) / now.AddHours(-3) / now.AddMonths(1)
now.Subtract(other).TotalDays
DateTime.DaysInMonth(2024, 2) // 29

五、格式化效能優化

1. 快取 FormatProvider：static readonly CultureInfo Invariant = CultureInfo.InvariantCulture;
2. 避免 Box/Unbox：string.Format("{0:yyyy-MM-dd}", dt) 較 dt.ToString("yyyy-MM-dd") 稍慢（需裝箱）。
3. 高頻熱路徑：考慮手寫 span.Format 或使用 Utf8Formatter (System.Buffers.Text) 直接寫入 Span<byte>，避免字串配置。
4. 預編譯格式字串：.NET 6+ DateTimeFormatInfo.GetFormat 內部已優化，無需額外處理。

六、常見陷阱

• M vs m：M = 月，m = 分。寫錯會產生離譜結果。
• yyyy vs YYYY：YYYY 非標準模式，會被視為常值字串 "YYYY"。
• 單引號未閉合："yyyy'年'MM'月'" 若漏掉尾單引號會拋 FormatException。
• Kind 未指定：DateTime.Parse("2024-06-15") 產生 Unspecified，後續 ToUniversalTime() 行為不可預期。建議 DateTime.SpecifyKind(dt, DateTimeKind.Local) 或改用 DateTimeOffset。

七、現代化替代方案：DateTimeOffset & NodaTime

• DateTimeOffset：內建 Offset，解決時區歧義，序列化含時區資訊，適合分散式系統。
• NodaTime：Google 開源，提供 Instant、ZonedDateTime、LocalDateTime 等豐富型別，正規處理夏令時、閏秒、歷史時區變更，強烈建議新專案採用。

總結

熟練掌握標準/自訂格式字串、善用 InvariantCulture、警惕 DateTime.Kind，即能寫出正確、高效、可國際化的日期時間輸出。若專案涉及跨時區、排程、歷史資料，請優先評估 DateTimeOffset 或 NodaTime。