前阵子做一个小工具，需要在页面上显示农历和节气，找了一圈万年历接口。免费的有不少，但质量差别很大，有的字段缺、有的限流狠、还有的过一段时间就停了。下面把选型时要看的几点整理一下。

先明确要哪些数据

「万年历」听着简单，实际包含好几类信息，不同接口覆盖范围不同：

  • 公历农历转换：最基本的，某天的农历日期、干支、生肖。
  • 节气与节日：二十四节气的具体时刻，传统节日和法定假日。
  • 宜忌、值神：黄历类信息，做日历工具一般用不上。
  • 节假日调休：哪天上班、哪天放假，这个对排班类应用很关键。

只显示农历的话，前两项就够；要做考勤、排班，第四项必须有，而且每年国务院公布后才会更新，接口得跟着维护。

调用形式基本都差不多

curl "https://api.example.com/calendar/day?date=2026-10-21&key=YOUR_KEY"

返回通常是 JSON，字段里带 lunar、term、festival 之类。有的接口按天查，有的支持按月批量返回，做日历页面时批量接口能省很多次请求。

免费额度和稳定性

免费接口一般会给每天几百到几千次的额度，个人项目够用，上线产品就要注意。建议做两层缓存：本地把查询过的日期结果存下来，农历数据本身不会变，缓存一年也没问题；再加一层服务端缓存，避免同一时刻被重复请求打满。

另外留意接口的更新频率。节气时刻每年固定，但节假日安排每年变，如果接口一年没更新，基本可以放弃了。

几个容易踩的坑

  • 时区：农历换日按北京时间，服务器在 UTC 时直接取当天日期会差一天。
  • 闰月：农历有闰月，字段里一般会标明，展示时别漏掉「闰」字。
  • 编码：部分接口返回 GBK，前端直接解析会乱码，注意看响应头。
  • HTTPS：页面是 https 时调 http 接口会被浏览器拦，选型时先确认支持 https。

最后给个务实建议：如果只需要公历转农历，本地存一张几十 KB 的对照表就能算，没必要依赖网络接口。接口的价值主要在节气和节假日这些需要持续维护的数据上。