方法与准确性
Qelunai 的农历计算代码已拆分为开源库 qelunai-lunar。本页概述该库的计算方法、哪些结果已与公开的越南历书核对、哪些尚未核对。
农历如何计算
越南历是阴阳历。每个农历月从当地时间的朔日（新月）开始；农历日 = 自不晚于该日的最近朔日起的天数，加 1。
- 公历日期按 Fliegel 与 Van Flandern（1968）的公式换算为儒略日数（JDN），见 Meeus《Astronomical Algorithms》（第 2 版，1998）。
- 朔：以平均朔望月 29.530588853 日为基础，加上简化的周期项，再减去多项式形式的 ΔT 近似值。
- 太阳黄经：简化的三项级数，不做章动和光行差改正。
- 换算结构（朔、十一月、闰月）采用 Ho Ngoc Duc 公布的越南农历算法，许多库都在使用。
- 默认时区为 UTC+7（越南时间），与设备时区无关。当朔或中气临近午夜时，中国（UTC+8）或韩国（UTC+9）的农历可能相差一天，进而相差一个月或一年。
- 只使用公历：1582-10-15 之前的日期按外推公历计算。
闰月
- 十一月是包含冬至的农历月。
- 若从上一个十一月初到下一个十一月初超过 365 天，该年有 13 个农历月。
- 此时闰月是十一月之后第一个不含中气的月。闰月沿用前一个月的月份数；例如农历 2025 年有闰六月。
- 农历年在正月初一更替。
如果查询该年并不存在的闰月（例如 2026 年闰六月），库会返回无此日期。
节气
- 二十四节气把太阳黄经分为 24 段，每段 15°：春分在 0°，冬至在 270°。
- 某一天所属的节气，以当地时间当天零点时生效的节气为准，因此交节当天是前一个节气的最后一天。在历法事件列表中，新节气的名称写在交节当天，与印刷历书一致。
干支
- 日：天干 = (JDN + 9) mod 10，地支 = (JDN + 1) mod 12。基准：2024-02-10 为甲辰日。
- 农历年：1984 年为甲子年；天干地支按距 1984 年的年数推算。
- 农历月：按五虎遁规则，正月天干由年干推出，每月递进一干；地支固定，正月为寅……腊月为丑。闰月沿用同号月份的干支。
黄道日与黄道时辰
- 十二值神的固定顺序：青龙、明堂、天刑、朱雀、金匮、宝光、白虎、玉堂、天牢、玄武、司命、勾陈。六个黄道神：青龙、明堂、金匮、宝光、玉堂、司命。
- 采用越南万年历逐日刊印的黄道黑道表：寅/申 → 青龙在子；卯/酉 → 寅；辰/戌 → 辰；巳/亥 → 午；午/子 → 申；未/丑 → 戌；其余值神按地支顺序排列。
- 黄道日按农历月的地支；闰月使用同号月份的地支。在农历月与节气月结果不同的 9 天里，所核对的越南万年历全部按农历月。
- 黄道时辰按日支；十二时辰为民用钟点：子时 23–1 点，丑时 1–3 点……亥时 21–23 点。23:00–24:00 属于当天还是次日的子时，各派说法不一；本库算作当天。
- 十二建除（建、除、满、平、定、执、破、危、成、收、开、闭）按节气月：在每个节交替（立春 → 寅，惊蛰 → 卯……），而不是在朔日交替。
核对：换算与干支
本库的测试（75 项）核对以下数值。“来源”一栏如实照录测试代码中的记录。
| 内容 | 核对数值 | 测试中记录的来源 |
|---|---|---|
| 越南春节（正月初一） | 2023-01-22、2024-02-10、2025-01-29、2026-02-17、2027-02-06 | 多家独立的越南新闻来源（未注明网址） |
| 雄王祭祖日（三月初十） | 2024-04-18、2025-04-07 | 未注明网址 |
| 存在闰月 | 农历 2023 年有闰二月；2025 年有闰六月（只核对是否存在，未核对起始日） | 公开资料（未注明网址） |
| 年干支 | 2023 癸卯、2024 甲辰、2025 乙巳、2026 丙午、2027 丁未 | 上述春节的年份名称 |
| 日干支 | 2024-02-10 为甲辰 | 多种越南万年历（未注明网址） |
| 月干支 | 2024 年正月为丙寅 | 未单独注明来源 |
| 内部一致性 | 1900–2100 年间每一天做公历 → 农历 → 公历换算都回到原日期 | 无外部来源 |
核对：黄道日、建除、节气
值日神与历法网站核对，访问日期 2026-10-28。这 9 天都是农历月与节气月结果不同的日子。
| 日期 | 干支 | 值日神 | 来源 |
|---|---|---|---|
| 2025-02-01 | 辛丑 | 明堂 | baoquocte.vn |
| 2025-05-01 | 庚午 | 青龙 | vtcnews.vn |
| 2025-08-14（农历闰六月廿一） | 乙卯 | 宝光 | ngaydep.com |
| 2026-02-10 | 乙卯 | 宝光 | ngaydep.com |
| 2026-06-10 | 乙卯 | 玄武 | ngaydep.com |
| 2026-08-09 | 乙卯 | 宝光 | ngaydep.com |
| 2026-10-09 | 丙辰 | 天刑 | ngaydep.com、xemlicham.com |
| 2026-11-08 | 丙戌 | 白虎 | ngaydep.com、xemlicham.com |
| 2026-12-08 | 丙辰 | 司命 | ngaydep.com |
黄道时辰已核对：2025-02-01（全部 12 个时辰，baoquocte.vn）、2025-05-01（vtcnews.vn、baolamdong.vn）、2026-02-10（xemlicham.com、baohatinh.vn、ngaydep.com）、2026-10-09（xemlicham.com、ngaydep.com）和 2026-10-28（xemlicham.com）。对 2025–2026 年的每一天，测试都检查恰好有 6 个黄道时辰。
建除：2026-10-28 和 2026-02-10 为“除”（xemlicham.com、ngaydep.com）。2026-02-10 是农历腊月廿三，但已过立春：按节气月为“除”，按农历月则为“满”。
节气：对 2026–2027 年的每一天，节气区间长 14–16 天，边界正是节气交替处；这是内部一致性检查。本库尚未将交节日期与官方天文资料核对。Qelunai 应用曾用美国海军天文台公布的 2024 年春分、夏至、秋分、冬至时刻检查太阳黄经函数。
测试中的其他样例日期（初一、十五、忌日样例、2025 年闰六月的起始日）是算法计算出的值，尚未与外部来源核对。
局限
- 已与公开历书核对的：上述日期，范围在 2023–2027 年。此范围以外的结果用相同方法计算，但未经核对。
- “约 1200–3000 年可靠”的说法来自另一个使用同类算法的库；qelunai-lunar 尚未自行验证。
- 简化级数和 ΔT 近似在少数情况下可能把朔或节气推过午夜，使月份边界偏差一天。
- 尚无将越南农历与中国或韩国农历对比的测试。
- 不适用于高精度天文计算。
文化内容仅供参考
黄道日、黄道时辰、十二建除和忌日都是传统惯例。本库遵循测试中核对过的越南历书；其他传统可能不同。
忌日规则由本库自行选定，未与外部来源核对：闰月去世者在同号的正常月份做忌；三十日去世者，大月在三十日、小月在二十九日做忌。
这些内容仅供文化参考，不构成专业建议。
开源库
qelunai-lunar 以纯 Dart 编写，从 Qelunai 应用中拆分出来，采用 MIT 许可证发布。源代码、测试和完整的方法说明：https://github.com/qelunai/qelunai-lunar