简介这份资源是面向Python开发者、日历应用与传统文化类项目开发者的中国农历与节日计算工具库适合需要处理公历农历转换、节气查询、传统节日识别的中初级程序员。包内共123个文件以72个py源码模块为核心辅以30个md说明文档、6张png示意图以及yml、csv、toml、cfg等配置与数据文件压缩包约918KB结构清晰便于按模块查阅。资源围绕农历转换、农历信息查询、节日计算、二十四节气推算及API设计等方向展开配套文档覆盖lunardate、festivals等主题并附有changelog与开发说明便于理解库的演进与集成方式。目前已有162人学习下载读者可借此掌握农历与节日功能的实现思路快速将相关能力接入日历、提醒或文化教育类应用同时参考其测试与兼容性处理方式提升工具库的工程化实践水平。1. 农历转换这件事为什么总在节日当天翻车每年春节、中秋前一周总有人在群里问为什么我的倒计时脚本去年跑得好好的今年日期差了一天答案往往藏在农历的“闰月”和“大小月”里。公历是纯数学的太阳历农历却是阴阳合历——既要跟月亮朔望对齐又要用闰月把节气拉回季节。这意味着农历不是一张固定公式能算出来的表而是一套带天文修正的历法规则。Python 里做中国农历、节日、节气、干支、生肖的工具库解决的就是把“农历日期”和“公历日期”双向可靠映射再叠加节日与节气查询。它适合做日历应用、排班系统、传统节日提醒、命理排盘的开发者也适合只想在脚本里加一句“今天是不是腊八”的运维。核心诉求就一个别在节日当天才发现日期错了。2. 选型与数据源农历库到底在算什么2.1 农历不是查表是天文算法加修正表很多人以为农历库就是一张几万行的对照表其实主流实现走的是“天文算法 修正数据”的路线。月亮绕地球的朔望月平均 29.53 天所以农历月要么 29 天要么 30 天这叫大小月。太阳两次经过春分点之间的回归年是 365.2422 天12 个朔望月只有约 354 天每年差出 11 天左右攒够约 3 年就得塞一个闰月这就是“十九年七闰”的由来。闰月插在哪个月之后取决于该月里有没有“中气”——二十四节气里排在偶数位的那些。没有中气的月就定为闰月。所以一个靠谱的农历库底层要么内置了朔望和节气的天文计算要么内置了经过权威校正的压缩数据表。你调用lunar_date Lunar.fromSolar(2025, 1, 29)时它背后在算的是日月黄经差和节气时刻不是简单查字典。2.2 常见库的取舍纯算法、数据表、还是混合市面上能用的方案大致三类。第一类是纯天文算法库比如基于 VSOP87 或 ELP2000 简化模型自己算朔气和节气优点是覆盖年份广、不依赖外部数据缺点是代码重、边界年份精度需要自己验证。第二类是数据表驱动把 1900 到 2100 这类常用区间的农历数据压缩成整数数组查表快、结果稳缺点是超出区间就抓瞎。第三类是混合方案常用区间查表超区间回退到算法。我一般会选混合方案因为业务里 99% 的查询落在 1900 到 2100但偶尔有人输入 1850 年的生日纯查表库会直接抛异常。选型时先问自己三个问题需要覆盖的年份范围是多少要不要节气精确到分钟要不要干支、生肖、宜忌这些衍生字段把这三个问题答清楚库的选择基本就定了。2.3 最小可跑装库、转日期、查节日先跑通最小闭环再谈扩展。下面这段代码演示公历转农历、农历转公历、查节日和节气四个基本动作。注意不同库的 API 命名差异较大这里用常见的lunar_python风格接口示意实际以你选定的库文档为准。# 安装pip install lunar_python from lunar_python import Solar, Lunar # 公历 2025-01-29 转农历 solar Solar.fromYmd(2025, 1, 29) lunar solar.getLunar() print(lunar.toString()) # 二〇二五年正月初一 print(lunar.getYearInGanZhi()) # 乙巳 print(lunar.getYearShengXiao()) # 蛇 # 农历转公历二〇二五年八月十五 lunar2 Lunar.fromYmd(2025, 8, 15) print(lunar2.getSolar().toYmd()) # 2025-10-06 # 查节日先看公历节日再看农历节日 print(solar.getFestivals()) # [] print(lunar.getFestivals()) # [春节] # 查节气当天或最近节气 print(lunar.getJieQi()) # 立春 或空字符串逻辑说明Solar.fromYmd构造公历对象getLunar()拿到对应农历Lunar.fromYmd反向构造getSolar()拿回公历。getFestivals()返回列表是因为一天可能撞多个节日比如某些年份中秋和国庆重叠。getJieQi()只在当天恰好是节气时返回名称否则返回空串这点和很多人“查最近节气”的预期不同需要额外用getJieQiTable()拿全年节气表再比对。参数上年份用四位整数月份 1 到 12日期 1 到 31闰月需要用库提供的闰月标记接口不能直接传 13。3. 把节日和节气接进业务从查询到提醒3.1 节日分三类别混在一个列表里农历库返回的节日通常分三类公历固定节日元旦、劳动节、农历固定节日春节、端午、中秋、节气型节日清明、冬至。这三类的计算路径完全不同。公历节日直接比对月日农历节日要先把公历转农历再比对清明和冬至本质是节气必须走节气表。很多翻车案例是把清明当农历节日去查结果永远查不到。正确做法是分别处理最后合并去重。下面这段代码演示三类节日的统一查询。from lunar_python import Solar def get_all_festivals(year, month, day): solar Solar.fromYmd(year, month, day) lunar solar.getLunar() result set() # 1. 公历固定节日 result.update(solar.getFestivals()) # 2. 农历固定节日 result.update(lunar.getFestivals()) # 3. 节气型节日清明、冬至等 jieqi lunar.getJieQi() if jieqi in (清明, 冬至): result.add(jieqi) return sorted(result) print(get_all_festivals(2025, 4, 4)) # [清明] print(get_all_festivals(2025, 10, 6)) # [中秋节]逻辑说明用set去重是因为中秋和国庆可能同一天返回列表里不该出现重复项。getJieQi()只在当天是节气时命中所以清明当天能拿到“清明”。参数上年份范围受库支持区间限制超出会抛异常或返回空业务层要加 try 捕获。如果要做“距离下一个节日还有几天”不能只查今天要循环往后推 400 天逐个比对因为农历节日在公历里是浮动的。3.2 节气表怎么拿为什么不能只查当天做提醒功能时用户要的是“下一个节气还有几天”而不是“今天是不是节气”。这时候要用全年节气表。多数库提供getJieQiTable()返回一个字典键是节气名值是公历日期。拿到表之后排序比对即可。注意节气表里同一个节气名可能出现两次因为有些库把“立春”和“立春前一天”都标了实际使用时按日期过滤。from lunar_python import Solar from datetime import date def next_jieqi(year, month, day): solar Solar.fromYmd(year, month, day) table solar.getLunar().getJieQiTable() today date(year, month, day) future [] for name, s in table.items(): d date(s.getYear(), s.getMonth(), s.getDay()) if d today: future.append((d, name)) future.sort() return future[0] if future else None print(next_jieqi(2025, 3, 1)) # (datetime.date(2025, 3, 5), 惊蛰)逻辑说明getJieQiTable()返回的 value 是 Solar 对象需要取出年月日再和今天比较。排序后取第一个就是下一个节气。参数上如果查询日期接近年末当年表里可能没有未来的节气需要把年份加一再查一次否则会返回 None。这个边界在跨年提醒场景里很常见血泪经验是别忘了补一年。3.3 干支、生肖、宜忌衍生字段的取值边界干支和生肖是农历库的高频衍生字段。天干十个、地支十二个组合成六十甲子年份干支按立春还是按正月初一切换不同库默认不同。有的库按正月初一换年有的按立春换年命理场景通常要求按立春。选库时一定要确认这个默认行为否则排盘结果会差一年。生肖同理跟着干支走。宜忌字段则依赖库内置的规则表不同库结果可能不一致业务上如果只是展示选一个稳定的即可如果要做决策参考得先验证规则来源。下面表格对比几个关键字段的常见取值方式。字段常见接口切换基准注意点年干支getYearInGanZhi正月初一或立春命理场景需按立春月干支getMonthInGanZhi节气月柱按节气换月日干支getDayInGanZhi子时换日晚子时归属有争议生肖getYearShengXiao跟随年干支与干支基准一致宜忌getDayYi / getDayJi内置规则不同库结果可能不同参数说明干支接口通常还提供getYearInGanZhiByLiChun()这类显式方法做命理时优先用带基准后缀的接口别用默认的。日干支的“晚子时”问题指的是 23 点后算今天还是明天不同流派不同代码里要按业务需求显式处理不能指望库替你决定。4. 避坑与排查农历开发里最容易踩的五个坑4.1 闰月传参错误导致日期整体偏移现象用户输入“闰六月十五”转换结果却是普通六月十五差了一个月。原因多数库的Lunar.fromYmd第三个参数是月份闰月需要用负数或单独的闰月标记直接传 6 会被当成普通六月。解决查库文档确认闰月表示法常见的是月份传负数表示闰月比如 -6 表示闰六月。转换前先判断该年是否有闰月没有闰月却传闰月标记会抛异常业务层要捕获并提示用户。4.2 年份超出库支持区间静默返回错误现象查询 1800 年的农历返回一个看似合理但实际错误的日期。原因数据表驱动的库在超区间时可能不抛异常而是回退到某个默认值或做近似计算。解决调用前先检查库的MIN_YEAR和MAX_YEAR常量超出就明确报错。混合方案虽然能回退到算法但算法在远年份的精度也需要验证别默认它一定对。4.3 节气时刻跨日导致日期差一天现象某年清明在公历 4 月 4 日 23 点多脚本按日期比对却算成了 4 月 5 日。原因节气是精确到分钟的天文时刻如果只取日期部分而忽略时刻跨日边界就会错。解决需要精确到日的场景用库返回的日期即可需要精确到时刻的取完整时间戳再判断。做“节气当天提醒”时建议按库返回的日期为准不要自己用天文公式重算。4.4 节日列表为空不等于没有节日现象查某天节日返回空列表但用户说那天是“寒食节”。原因寒食节在清明前一二日属于节气衍生节日很多库不内置。解决这类节日要自己按规则计算比如寒食 清明前一天。别指望库覆盖所有民俗节日库通常只覆盖主流固定节日。业务上如果需要冷门节日维护一张自定义规则表按节气或农历日期偏移计算。4.5 时区问题让“今天”变成“昨天”现象服务器在 UTC 时区用户在东八区晚上 8 点后查询“今天农历”结果差一天。原因date.today()取的是服务器本地日期UTC 下比东八区晚 8 小时。解决所有日期计算显式指定时区用zoneinfo或pytz把用户时区转成目标日期再传给农历库。农历库本身通常不处理时区它只认你传进去的年月日所以时区转换必须在调用之前完成。5. 进阶把农历库包成可复用的服务与校验习惯做到这里单次查询已经没问题了。但如果你要把农历能力接进多个项目建议包一层薄服务把时区、闰月、超区间这些边界统一收口。我一般会写一个LunarService类对外只暴露solar_to_lunar、lunar_to_solar、get_festivals、next_jieqi四个方法内部统一做时区转换和异常处理。这样业务代码不用关心库的 API 差异换库时只改一个文件。from datetime import date, datetime from zoneinfo import ZoneInfo from lunar_python import Solar, Lunar class LunarService: def __init__(self, tzAsia/Shanghai): self.tz ZoneInfo(tz) def _today(self): return datetime.now(self.tz).date() def solar_to_lunar(self, y, m, d): try: lunar Solar.fromYmd(y, m, d).getLunar() return { text: lunar.toString(), ganzhi: lunar.getYearInGanZhi(), shengxiao: lunar.getYearShengXiao(), festivals: lunar.getFestivals(), } except Exception as e: return {error: str(e)} def next_jieqi(self): today self._today() table Solar.fromYmd(today.year, today.month, today.day).getLunar().getJieQiTable() future [] for name, s in table.items(): d date(s.getYear(), s.getMonth(), s.getDay()) if d today: future.append((d, name)) if not future: # 跨年补查 table Solar.fromYmd(today.year 1, 1, 1).getLunar().getJieQiTable() for name, s in table.items(): d date(s.getYear(), s.getMonth(), s.getDay()) future.append((d, name)) future.sort() return future[0] if future else None逻辑说明_today用显式时区取日期避免服务器时区干扰。solar_to_lunar把异常收成字典返回调用方不用写 try。next_jieqi处理了年末跨年补查这是前面提到的边界。参数上时区默认东八区海外业务传入对应时区即可。这个类不依赖具体库的全局状态方便测试。验证习惯上我固定做两件事。第一拿已知的春节日期做回归测试比如 2025 年春节是 1 月 29 日、2026 年是 2 月 17 日写进单元测试换库或升级版本时跑一遍。第二随机抽 100 个日期做公历转农历再转回公历断言结果一致这能抓出大部分闰月和边界 bug。这两条习惯帮我省过好几次线上事故农历这东西宁可多测一轮也别等用户来报错。希望帮到你。本文还有配套的精品资源点击获取