掌握Lunar JavaScript农历工具库：从入门到精通的完全指南

2026-04-27 13:14:40作者：咎岭娴Homer

日历、公历(阳历)、农历(阴历、老黄历)、佛历、道历，支持节假日、星座、儒略日、干支、生肖、节气、节日、彭祖百忌、每日宜忌、吉神宜趋凶煞宜忌、吉神(喜神/福神/财神/阳贵神/阴贵神)方位、胎神方位、冲煞、纳音、星宿、八字、五行、十神、建除十二值星、青龙名堂等十二神、黄道黑道日及吉凶等。lunar is a calendar library for Solar and Chinese Lunar.

项目地址：https://gitcode.com/gh_mirrors/lu/lunar-javascript

🌙 为什么我们需要农历工具库？

在数字化时代，公历已经成为主流的时间计量方式，但农历作为中国传统文化的重要组成部分，仍然在节日庆典、农事安排、传统习俗等方面发挥着不可替代的作用。无论是开发日历应用、传统文化工具，还是节日提醒系统，一个可靠的农历计算库都是必不可少的工具。

Lunar JavaScript就是这样一款专为现代开发打造的农历工具库，它就像一位随身携带的"传统历法专家"，能够轻松解决公历与农历互转、节气查询、传统节日计算等问题，让你的应用瞬间拥有传统文化底蕴！

✨ Lunar JavaScript的核心优势

轻装上阵，无牵无挂

想象一下，你只需要两个文件就能拥有一整套农历计算能力！Lunar JavaScript核心文件仅有两个，不依赖任何第三方库，就像一个轻巧的瑞士军刀，随时可以集成到你的项目中，不会给你的应用增加任何多余负担。

功能齐全，应有尽有

从最基础的公历农历互转，到复杂的干支五行、节气时刻计算，再到传统节日识别和每日宜忌查询，Lunar JavaScript提供了你能想到的所有农历相关功能。它就像一个传统文化数据库，随时为你提供准确的历法信息。

跨平台作战，无处不在

无论你是在Node.js环境下开发后端服务，还是在浏览器中构建前端应用，Lunar JavaScript都能完美适配。一次集成，多端使用，让你的农历功能无处不在。

开源免费，放心使用

采用MIT许可证发布，你可以自由地在个人项目和商业应用中使用、修改和分发，无需担心任何授权问题。

🚀 零基础入门步骤

1. 获取代码库

首先，让我们把Lunar JavaScript请到你的开发环境中：

git clone https://gitcode.com/gh_mirrors/lu/lunar-javascript
cd lunar-javascript
npm install

2. Node.js环境快速上手

创建一个简单的Node.js脚本，体验农历转换的魔力：

const { Solar } = require('./index.js');

// 创建一个公历日期对象（2024年12月29日）
const solar = Solar.fromYmd(2024, 12, 29);

// 输出公历完整信息
console.log(solar.toFullString());

// 转换为农历并输出详细信息
console.log(solar.getLunar().toFullString());

运行这段代码，你将看到公历日期如何神奇地转换为农历日期，包括干支、生肖等传统历法信息。

3. 浏览器环境轻松集成

如果你正在开发网页应用，只需简单几步就能在浏览器中使用Lunar JavaScript：

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>农历转换演示</title>
</head>
<body>
  <script src="lunar.js"></script>
  <script>
    // 使用当前日期生成农历对象
    const lunar = Lunar.fromDate(new Date());
    console.log(lunar.toFullString());
  </script>
</body>
</html>

在浏览器中打开这个HTML文件，控制台就会输出当前日期的农历信息，就是这么简单！

📚 核心功能实战指南

公历与农历互转：时间的双向门

公历转农历：就像把普通话翻译成文言文

const solar = Solar.fromYmd(2024, 1, 1);
const lunar = solar.getLunar();
console.log(`${lunar.getYear()}年${lunar.getMonth()}月${lunar.getDay()}日`);

农历转公历：又像把文言文翻译成普通话

const lunar = Lunar.fromYmd(2024, 11, 1);
const solar = lunar.getSolar();
console.log(solar.toYmd()); // 输出：2024-12-01

常见问题：

Q: 为什么农历月份有时候会有"闰月"？
A: 因为农历是阴阳合历，为了协调太阳和月亮的运行周期，大约每3年会设置一个闰月，来弥补与公历的差距。

节气查询：大自然的时间密码

二十四节气是中国古代农耕文明的智慧结晶，Lunar JavaScript让你轻松获取任意日期的节气信息：

const solar = Solar.fromYmd(2024, 12, 21);
const jieQi = solar.getJieQi();
console.log('当日节气：', jieQi); // 可能输出：冬至

常见问题：

Q: 节气时间是精确到天还是具体时刻？
A: Lunar JavaScript计算的节气时间精确到分钟，反映了太阳到达黄经特定位置的准确时刻。

传统节日识别：文化传承的提醒器

无论是春节、中秋还是端午，Lunar JavaScript都能准确识别：

const lunar = Lunar.fromYmd(2024, 1, 1);
const festivals = lunar.getFestivals();
console.log('传统节日：', festivals); // 输出：春节

常见问题：

Q: 是否支持自定义节日？
A: 目前Lunar JavaScript主要支持传统固定节日，自定义节日可以通过扩展代码实现。

生肖与干支：传统文化的符号系统

想知道某年的生肖和干支？一行代码就能搞定：

const lunar = Lunar.fromYmd(2024, 1, 1);
console.log('生肖：', lunar.getYearShengXiao()); // 输出：龙
console.log('干支：', lunar.getYearInGanZhi()); // 输出：甲辰

干支是什么：干支是中国古代的一种纪年法，由10天干和12地支组合而成，60年一个循环，就像传统文化的"密码本"。

🚀 高级功能应用技巧

每日宜忌：传统智慧的现代应用

想知道今天适合做什么，不适合做什么？Lunar JavaScript能帮你查询传统黄历中的宜忌信息：

const lunar = Lunar.fromDate(new Date());
const yi = lunar.getDayYi(); // 获取今日宜做事项
const ji = lunar.getDayJi(); // 获取今日忌做事项
console.log('今日宜：', yi);
console.log('今日忌：', ji);

应用场景：可以在日程应用中集成宜忌提醒，为用户提供传统文化参考。

吉神方位：传统空间智慧

除了日期，Lunar JavaScript还能计算每日的吉神方位，如喜神、财神方位：

const lunar = Lunar.fromDate(new Date());
console.log('喜神方位：', lunar.getPositionXi());
console.log('财神方位：', lunar.getPositionCai());

常见问题：

Q: 方位是如何计算的？
A: 吉神方位基于传统风水学和天文学知识计算，反映了传统文化中的空间观念。

🔧 开发实战指南

错误处理：让你的应用更健壮

处理无效日期输入是任何日期相关应用都需要考虑的问题：

try {
  const solar = Solar.fromYmd(2024, 2, 30); // 无效日期（2月没有30日）
} catch (error) {
  console.log('日期格式错误：', error.message);
}

性能优化：让计算更高效

对于需要频繁进行日期转换的场景，缓存是个好主意：

// 缓存常用日期计算结果
const dateCache = new Map();
function getLunarInfo(year, month, day) {
  const key = `${year}-${month}-${day}`;
  if (!dateCache.has(key)) {
    dateCache.set(key, Solar.fromYmd(year, month, day).getLunar());
  }
  return dateCache.get(key);
}