把首页那个节日日历插件开源了：农历节气靠算，图片零外链

2026年10月1日站点日志 997

AI 摘要997笔记AI

一款零依赖的 WordPress 节日插件已开源，支持农历、公历节日与二十四节气，自动生成卡片、横幅和动态 SVG 节日图，采用天文算法计算节气与农历，零外链、零数据库。修复国庆当天倒计时“还有 1 天”的差一错误，改为显示“今天 · 国庆节”，并提供下载与短代码用法。

此内容由AI根据文章内容自动生成。

如果你点开过本站的首页，侧边栏里有一张「节日卡片」：公历日期、星期、农历、二十四节气，还有距离下一个节日的倒计时。国庆节那天它还差点闹了笑话——当天显示「距国庆节还有 1 天」。这个 bug 修完之后，我决定把整个插件整理开源。

先看效果

下面这张图就是插件实时生成的 SVG 节日图（不是截图、不是图片文件，是 PHP 当场画出来的矢量图）：

997节日日历插件生成的国庆节 SVG 节日图，红色渐变底

功能	说明
三类节日识别	农历传统节日（春节、端午、中秋、除夕…）、公历节日（元旦、国庆…）、二十四节气，按「传统 > 公历 > 节气」定优先级
节日卡片	自动挂到侧边栏：公历日期、星期、农历、节气、下一个节日倒计时
节日横幅	页面顶部横幅，按节日自动配色（国庆红金、圣诞红绿…），可一键关闭
动态 SVG 节日图	PHP 直接拼 SVG 字符串输出，不外链图片、不产生文件
短代码	三个短代码，可插到任意文章、页面、小工具
按天缓存	当日计算结果存 transient，同一天只算一次

市面上的同类方案基本两条路，各有一个坑：

一是外链图。很多插件或教程直接引用节假日 API 的图片或网图，图床说挂就挂，还有版权风险。本站的图片 SEO 做了很久，我很清楚「图挂了」是什么体验，所以节日图必须是插件自己生成的。

二是硬编码节日表。常见做法是把「2030 年之前的中秋是哪天」写成数组，年份一过就全错。这个插件用的是天文算法：按太阳黄经计算出二十四节气的精确时刻，再由「节」划分农历月份，闰月按无中气规则插入——覆盖公历 -1000 到 3000 年，我活不到它出错的那天。

另外它零依赖：不用 composer、不建数据库表、不调外部接口，一个目录传上去启用就能跑。

开源前修的最后一个 bug 值得单独讲。10 月 1 日当天，卡片显示的是「距国庆节还有 1 天」，指向 10 月 2 日。原因在倒计时的过滤条件：

// 修复前：只取"明天及以后"的节日
if ( $c['ts'] >= $today_start + DAY_IN_SECONDS )

国庆节是 1~7 号连放的，插件会把假期每一天都生成一个候选。把「今天」排除后，第一个候选就变成了 10 月 2 日——还是叫国庆节，于是倒计时永远是 1。

修复方案是把过滤条件改成包含今天，并且在渲染时对 days = 0 的情况单独处理：节日当天显示「今天 · 国庆节」，而不是一个别扭的「还有 0 天」。

写倒计时代码时，「今天算不算在内」是最高频的差一错误（off-by-one）。判断依据不是数格子，而是问业务语义：当天正在过节，倒计时还有意义吗？——对节日来说，答案是把”今天”单独作为一种状态展示。

不想自动挂载的话，把开关关掉后用短代码手动放：

[n997_festival]        // 完整节日卡片
[n997_festival_img]     // SVG 节日图
[n997_festival_text]    // 纯文本，如「国庆节 · 农历八月廿一」

环境要求：WordPress 5.6+，PHP 7.4+（推荐 8.0+）
历法核心：liujiawm/php-calendar（Apache-2.0），已随包附带在 lib/php-calendar/，算法出自 Jean Meeus《Astronomical Algorithms》
主程序许可证：GPL-2.0 or later，与 WordPress 一致
包内含 GitHub 就绪的 README、LICENSE、第三方声明，克隆上去就是一个标准仓库

下载直链：n997-festival-1.0.0.zip。GitHub 仓库整理好后地址会更新在这里。如果你用上了，或者发现了 bug，欢迎在评论区说一声。