解锁传统文化工具：零基础掌握Lunar JavaScript农历算法

2026-04-27 12:40:05作者：田桥桑Industrious

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

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

Lunar JavaScript是一款轻量级传统文化工具库，提供公历农历互转、节气查询、节日计算等功能，无第三方依赖，支持Node.js和浏览器环境，帮助开发者快速集成传统历法功能，让应用轻松拥有文化底蕴。

🌙 为什么选择这款传统文化工具？

在数字化时代，我们时常需要在现代应用中融入传统历法元素。Lunar JavaScript就像一位"时间翻译官"，能轻松实现公历与农历的双向转换，还能查询节气、节日等传统文化信息。它体积小巧，核心文件仅两个，加载速度快，无论是开发日历应用还是传统文化工具，都是理想选择。

与同类工具对比

特性	Lunar JavaScript	其他农历工具
体积大小	轻量（核心仅2个文件）	通常包含多个依赖文件
兼容性	支持Node.js和浏览器	部分仅支持单一环境
功能完整性	公历农历互转、节气、节日等	功能相对单一
学习成本	低，API简洁易懂	较高，配置复杂

📅 3步实现节气查询

环境搭建

首先获取项目源码：

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

基础使用示例

Node.js环境使用：

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

// 创建公历日期对象
const solarDate = Solar.fromYmd(2024, 12, 29);

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

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

浏览器环境使用：

直接在HTML文件中引入：

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

生肖计算避坑指南

在使用生肖计算功能时，需要注意农历新年和公历新年的时间差。例如，2024年2月10日前属于癸卯年（兔年），之后才是甲辰年（龙年）。

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

文化背景小知识：生肖是中国与十二地支相配以人出生年份的十二种动物，包括鼠、牛、虎、兔、龙、蛇、马、羊、猴、鸡、狗、猪。生肖文化是中国传统文化的重要组成部分。

🔍 常见场景+解决方案

场景一：日历应用开发

解决方案：使用Lunar JavaScript的公历农历互转功能，为应用添加农历显示。

// 获取当前日期的农历信息
const today = new Date();
const lunarToday = Lunar.fromDate(today);
// 在页面上显示农历信息
document.getElementById('lunar-date').textContent = `${lunarToday.getYear()}年${lunarToday.getMonth()}月${lunarToday.getDay()}日`;

场景二：传统节日提醒

解决方案：利用节日查询功能，设置节日提醒。

const lunar = Lunar.fromYmd(2024, 1, 1);
const festivals = lunar.getFestivals();
if (festivals.length > 0) {
  console.log(`今天是${festivals[0]}，记得庆祝哦！`);
}

💡 高级功能应用

每日宜忌查询

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

吉神方位计算

核心算法实现：lunar.js

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

🚀 5分钟上手配置指南

克隆项目到本地：git clone https://gitcode.com/gh_mirrors/lu/lunar-javascript
进入项目目录：cd lunar-javascript
安装依赖：npm install
在Node.js中使用：const { Solar, Lunar } = require('./index.js')
在浏览器中使用：<script src="lunar.js"></script>

❓ 常见问题解答

Q: 如何处理时区问题？

A: 工具库默认使用本地时区，如需指定时区，可通过 Solar.fromYmdHms() 方法的参数设置。

Q: 是否支持旧版浏览器？

A: 支持现代浏览器，如需在IE等旧浏览器中使用，建议使用Babel等工具进行语法转换。

总结

Lunar JavaScript作为一款优秀的传统文化工具，为开发者提供了便捷的农历算法和传统文化API。无论是开发日历应用、节日提醒系统，还是传统文化工具，它都能满足需求。通过本文的介绍，相信你已经对Lunar JavaScript有了全面的了解，现在就开始使用它，为你的项目添加丰富的传统文化功能吧！

lunar-javascript