先講結論:taiwan-lunar-cal 上線第一天就進廠維修。國曆轉農曆(1900-2100,含閏月)九個錨點全過、毫髮無傷,出包的是二十四節氣——我寫了網路上到處抄的那個「通用公式」,當天回頭對中央氣象署的官方日曆才發現:2024 年 24 個節氣,它錯 21 個。
先看那個公式,大家在用的都是它:
日 = int(Y * 0.2422 + C) - int((Y-1) // 4)(Y = 年 % 100,C 是每個節氣的常數)
我當時測了 2026 年:清明 4/5 對、夏至 6/21 對、冬至 12/22 對,就放心收工了。這是這顆雷最賤的地方:非閏年它大部分時候是對的。回頭把氣象署《日曆資料表》2023-2027 的 PDF 全抓下來逐年對帳:2023 錯 2 個、2024 錯 21 個、2025 錯 1 個、2026 錯 3 個、2027 錯 2 個。閏年節氣普遍提早一天,公式的閏年修正慢半拍,2024 年從驚蟄一路錯到冬至。原本文件裡那句「罕見 ±1 天例外」根本自我感覺良好。
不想玩例外表通靈,直接回到定義:節氣是太陽視黃經每 15° 一個(春分 0°、清明 15°……)。用 Meeus 低精度式算視黃經(加章動與光行差修正,誤差約 0.01°),在預估日期前後五天掃描、二分逼近交節時刻到分,再換成台灣時間。日期變成時刻的副產品,反而更準。
驗證用同一份官方資料:2023-2027 五年共 120 個節氣,日期全對,交節時刻最大差 13 分鐘(2024 春分官方 11:06、我算 11:04;2026 清明官方 02:40、我算 02:28)。順帶一顆小雷:那個 PDF 是兩欄排版,月份標記有時自己獨立一行,pdftotext 剖析時月份歸屬會錯亂,最後用「每個節氣的月份本來就固定」當 sanity check,只對日期。
誠實條款照列:時刻誤差約 ±15 分鐘,交節落在午夜前後 15 分鐘內時日期可能差一天,祭典或正式文件還是要對氣象署。但「今年清明哪一天」這種問題,現在本地零網路直接給答案。農曆換算維持原樣:公開的 1900-2100 壓縮表,2026-02-17 丙午年正月初一、2025 年閏六月、2026-02-16 除夕小月,九個錨點全過。
這顆雷給地雷圖鑑添一條:「只驗一年就收工」。曆法相關的測試錨點一定要含閏年,而且要對官方來源逐年對帳,不能只看幾個順眼的年份。CHANGELOG 記 0.7.1。