chinese-lunar-date

高精度农历历法库 — 干支 · 生肖 · 节气 · 节日 · 格式化 · 多语言

基于天文算法的农历计算，支持中国、日本、韩国、越南四种农历变体，以及简体中文、繁體中文（台灣/香港）、日本語、한국어、Tiếng Việt 六种语言。

import { ChineseDate } from 'chinese-lunar-date'

const date = ChineseDate.fromGregorian(2024, 6, 21)

date.yearGanZhi    // "甲辰"
date.zodiac        // "龙"
date.zodiacEmoji   // "🐉"
date.formatFull()  // "甲辰龙年 五月初六"

本项目独创

• 自研轻量天文模块 — 基于 VSOP87 行星理论截断数据（1e-7 阈值，仅保留 220/2564 项），替代笨重的 astronomia 库，IIFE 体积从 ~350 KB 降至 ~47 KB（gzip ~16 KB），精度无损
• 四种历法统一架构 — 中/日/韩/越四种农历变体通过 CalendarConfig 配置驱动，同一套算法适配不同纪元和时区历史，而非四套独立实现
• 不可变值对象 + 纯函数双模式 — 高层 API（ChineseDate 等）为不可变值对象，底层算法全部为纯函数，两种模式可独立使用
• 繁体中文地区差异化 — zh-TW 与 zh-HK 不仅用字不同（如"龍/龍"），节日名称也有区分（如"春節/農曆新年"），非简单繁简映射

为什么选择 chinese-lunar-date？

特性

• 天文级精度 — 基于 VSOP87 行星理论，自研轻量天文模块替代笨重的第三方库
• 不可变值对象 — 所有实例创建后不可修改，with() / addDays() 返回新实例
• 天干地支 — 年柱、月柱、日柱，六十甲子序号与字符串互转
• 生肖 — 12 生肖多语言名称 + Emoji
• 24 节气 — 精确到天的节气计算，区分中气与节气
• 传统节日 — 13 个内置节日，按地区自动筛选
• 多语言 / 多地区 — zh-CN / zh-TW / zh-HK / ja-JP / ko-KR / vi-VN
• 格式化 — 内置 5 种格式 + 自定义模式串
• 多历法 — 中 / 日 / 韩 / 越四种历法配置（不同纪元、不同时区历史）
• TypeScript 优先 — 完整类型定义，编译输出 ESM / CJS / IIFE
• 轻量 — IIFE 压缩后仅 ~47 KB（gzip ~16 KB）

安装

npm install chinese-lunar-date

快速开始

创建日期

import { ChineseDate } from 'chinese-lunar-date'

// 从公历创建
const date = ChineseDate.fromGregorian(2024, 6, 21)

// 从 JavaScript Date 创建
const date2 = ChineseDate.fromDate(new Date(2024, 5, 21))

// 今天的农历
const today = ChineseDate.today()

// 从 LunarDateValue 创建
const date3 = ChineseDate.fromValue({ cycle: 78, year: 34, month: 5, leap: false, day: 6 })

读取属性

const date = ChineseDate.fromGregorian(2024, 6, 21)

// 农历日期
date.cycle           // 78      — 六十甲子周期序号
date.year            // 34      — 周期内年序（34 → 甲辰）
date.month           // 5       — 五月
date.leap            // false   — 非闰月
date.day             // 6       — 初六
date.gregorianYear   // 2024

// 天干地支
date.yearGanZhi      // "甲辰"
date.monthGanZhi     // "庚午"
date.dayGanZhi       // "甲寅"
date.ganZhiInfo      // { year: {gan:0,zhi:4}, month: {gan:6,zhi:6}, day: {gan:0,zhi:2} }

// 生肖
date.zodiac          // "龙"
date.zodiacEmoji     // "🐉"
date.zodiacIndex     // 4

// 节日 & 节气
date.festivals       // []  — 这天没有节日
date.getSolarTermName('zh-CN')  // null  — 这天不是节气

格式化

const date = ChineseDate.fromGregorian(2024, 6, 21)

// 内置格式
date.formatFull()          // "甲辰龙年 五月初六"
date.formatFull('zh-TW')   // "甲辰龍年 五月初六"
date.formatFull('ja-JP')   // "甲辰辰年 五月初六"
date.formatGanZhi()        // "甲辰年 庚午月 甲寅日"
date.formatCompact()       // "78/34/5/0/6"
date.formatISO()           // "78-34-5-0-6"

// 自定义模式
date.format('{Ygz}{Z}年 {Mname}{Dname}', 'zh-CN')   // "甲辰龙年 五月初六"
date.format('{Ygz}{Z}年 {Mname}{Dname}', 'zh-TW')   // "甲辰龍年 五月初六"
date.format('{GY}年{GM}月{GD}日', 'zh-CN')           // "2024年6月21日"

日期运算

const date = ChineseDate.fromGregorian(2024, 6, 21)

// 日期加减 — 返回新实例，原实例不变
const tomorrow = date.addDays(1)
const yesterday = date.addDays(-1)
const nextMonth = date.addMonths(1)
const lastYear = date.addYears(-1)

// 修改部分字段
const firstDay = date.with({ day: 1 })  // 五月初一

// 比较
tomorrow.isAfter(date)     // true
yesterday.isBefore(date)   // true
date.equals(tomorrow)      // false

转换

const date = ChineseDate.fromGregorian(2024, 6, 21)

// 转为公历
date.toGregorian()  // { year: 2024, month: 6, day: 21 }

// 转为 JavaScript Date
date.toDate()       // Date object

// 序列化
date.toJSON()       // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
JSON.stringify(date)  // '{"cycle":78,"year":34,"month":5,"leap":false,"day":6}'

多历法

四种农历变体，各有不同的纪元和时区历史：

import { ChineseDate, JapaneseDate, KoreanDate, VietnameseDate } from 'chinese-lunar-date'

// 中国农历 (UTC+8)
const cn = ChineseDate.fromGregorian(2024, 6, 21)
cn.yearGanZhi  // "甲辰"

// 日本旧历 (UTC+9)
const jp = JapaneseDate.fromGregorian(2024, 6, 21)
jp.yearGanZhi  // "甲辰"  — 同一天可能因时区差异而不同

// 韩国农历 (UTC+8:30/9，檀君纪元)
const kr = KoreanDate.fromGregorian(2024, 6, 21)

// 越南农历 (UTC+7/8)
const vn = VietnameseDate.fromGregorian(2024, 6, 21)

注意：由于时区差异，同一公历日期在不同历法中可能对应不同的农历日期。例如，当新月发生在 UTC+8 的午夜附近时，日本 (UTC+9) 可能已经进入下一天。

24 节气

import { ChineseDate, solarTermName } from 'chinese-lunar-date'

// 获取指定节气的公历日期
ChineseDate.solarTerm(5, 2024)   // { year: 2024, month: 4, day: 4 } — 清明
ChineseDate.qingming(2024)        // 同上

// 全年 24 节气
ChineseDate.solarTermsInYear(2024, 'zh-CN')
// [
//   { index: 1, name: "立春", date: { year: 2024, month: 2, day: 4 }, jde: ... },
//   { index: 2, name: "雨水", date: { year: 2024, month: 2, day: 19 }, jde: ... },
//   ...
// ]

// 节气名称 — 6 种语言
solarTermName(3, 'zh-CN')  // "惊蛰"
solarTermName(3, 'zh-TW')  // "驚蟄"
solarTermName(3, 'zh-HK')  // "驚蟄"
solarTermName(3, 'ja-JP')  // "啓蟄"
solarTermName(3, 'ko-KR')  // "경칩"
solarTermName(3, 'vi-VN')  // "Kinh trập"

// 查找某日是否为节气
const date = ChineseDate.fromGregorian(2024, 4, 4)
date.getSolarTermName('zh-CN')  // "清明"

传统节日

import { ChineseDate } from 'chinese-lunar-date'

// 获取指定节日的公历日期
ChineseDate.festivalDate('spring', 2024)      // { year: 2024, month: 2, day: 10 }
ChineseDate.festivalDate('mid-autumn', 2024)  // { year: 2024, month: 9, day: 17 }

// 全年节日 — 按地区自动筛选
ChineseDate.festivalsInYear(2024, 'zh-CN')
// [{ name: "春节", key: "spring", date: {...} }, ...]

ChineseDate.festivalsInYear(2024, 'zh-HK')
// [{ name: "農曆新年", key: "spring", date: {...} }, ...]  — 香港称「農曆新年」

// 查看某日是否为节日
const date = ChineseDate.fromGregorian(2024, 2, 10)
date.getFestivals('zh-CN')  // [{ name: "春节", key: "spring", ... }]
date.getFestivals('zh-HK')  // [{ name: "農曆新年", key: "spring", ... }]

内置节日列表

多语言 / 多地区

import { getLocale, availableLocales, isLocaleSupported } from 'chinese-lunar-date'

availableLocales()  // ["zh-CN", "zh-TW", "zh-HK", "ja-JP", "ko-KR", "vi-VN"]
isLocaleSupported('zh-MO')  // false

const loc = getLocale('ja-JP')
loc.gan           // ["甲", "乙", "丙", ...]
loc.zhi           // ["子", "丑", "寅", ...]
loc.zodiac        // ["鼠", "牛", "虎", "兔", "竜", "蛇", "馬", "羊", "猿", "鶏", "犬", "猪"]
loc.monthNames(12, false)  // "師走"
loc.dayNames(15)           // "十五"
loc.solarTerms             // ["立春", "雨水", "啓蟄", ...]

繁体中文地区差异

天干地支

import {
  yearGanZhi, monthGanZhi, dayGanZhi,
  formatGanZhi, parseGanZhi, allGanZhi, ganZhiToCycleIndex
} from 'chinese-lunar-date'

// 获取干支索引对
const pair = yearGanZhi({ cycle: 78, year: 34, month: 7, leap: false, day: 28 })
// { gan: 3, zhi: 9 } → 丁酉

// 格式化
formatGanZhi(pair)  // "丁酉"

// 解析
parseGanZhi('甲子')  // { gan: 0, zhi: 0 }

// 六十甲子序号
ganZhiToCycleIndex(parseGanZhi('甲子'))  // 1
ganZhiToCycleIndex(parseGanZhi('癸亥'))  // 60

// 六十甲子表
allGanZhi()  // ["甲子", "乙丑", ..., "癸亥"]

生肖

import { zodiac, zodiacEmoji, zodiacFromGregorianYear, zodiacList } from 'chinese-lunar-date'

// 多语言生肖名称
zodiac({ cycle: 78, year: 34, month: 7, leap: false, day: 28 }, 'zh-CN')  // "鸡"
zodiac({ cycle: 78, year: 34, month: 7, leap: false, day: 28 }, 'zh-TW')  // "雞"
zodiac({ cycle: 78, year: 34, month: 7, leap: false, day: 28 }, 'ja-JP')  // "鶏"
zodiac({ cycle: 78, year: 34, month: 7, leap: false, day: 28 }, 'ko-KR')  // "닭"
zodiac({ cycle: 78, year: 34, month: 7, leap: false, day: 28 }, 'vi-VN')  // "Dậu"

// Emoji
zodiacEmoji({ cycle: 78, year: 34, month: 7, leap: false, day: 28 })  // "🐔"

// 从公历年快速获取
zodiacFromGregorianYear(2024, 'zh-CN')  // "龙"

// 生肖列表
zodiacList('zh-CN')  // ["鼠", "牛", "虎", "兔", "龙", "蛇", "马", "羊", "猴", "鸡", "狗", "猪"]
zodiacList('ko-KR')  // ["쥐", "소", "호랑이", "토끼", "용", "뱀", "말", "양", "원숭이", "닭", "개", "돼지"]

格式化

自定义模式

const date = ChineseDate.fromGregorian(2024, 7, 3)

date.format('{Ygz}{Z}年 {Mname}{Dname}', 'zh-CN')
// "甲辰龙年 五月廿八"

date.format('{Ygz}{Z}年 {Mname}{Dname}', 'zh-TW')
// "甲辰龍年 五月廿八"

解析

import { parseCompact, parseISO } from 'chinese-lunar-date'

parseCompact('78/34/5/0/6')   // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
parseCompact('78/34/2/1/15')  // { cycle: 78, year: 34, month: 2, leap: true, day: 15 }
parseISO('78-34-5-0-6')       // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
parseISO('invalid')           // null

低级 API

如需更细粒度的控制，可直接使用核心算法函数：

import {
  gregorianToLunar, lunarToGregorian, lunarToJDE, fromJDE,
  newYear, yearFromEpochCycle, solarTermJDE,
  nextNewMoon, previousNewMoon, midnight,
  inMajorSolarTerm, isLeapMonth,
  CHINESE_CONFIG, JAPANESE_CONFIG, KOREAN_CONFIG, VIETNAMESE_CONFIG
} from 'chinese-lunar-date'

// 公历 → 农历
const lunar = gregorianToLunar(CHINESE_CONFIG, 2024, 6, 21)
// { cycle: 78, year: 34, month: 5, leap: false, day: 6 }

// 农历 → 公历
const greg = lunarToGregorian(CHINESE_CONFIG, lunar)
// { year: 2024, month: 6, day: 21 }

// 使用不同历法配置
const jpLunar = gregorianToLunar(JAPANESE_CONFIG, 2024, 6, 21)
const krLunar = gregorianToLunar(KOREAN_CONFIG, 2024, 6, 21)
const vnLunar = gregorianToLunar(VIETNAMESE_CONFIG, 2024, 6, 21)

// 春节 JDE
const nyJDE = newYear(CHINESE_CONFIG, 2024)

浏览器使用（IIFE）

<script src="dist/chinese-lunar-date.iife.js"></script>
<script>
  // 所有 API 挂载在全局 ChineseLunarDate 对象上
  const date = ChineseLunarDate.ChineseDate.fromGregorian(2024, 6, 21)

  console.log(date.formatFull())         // "甲辰龙年 五月初六"
  console.log(date.formatFull('zh-TW'))  // "甲辰龍年 五月初六"
  console.log(date.zodiac)               // "龙"
  console.log(date.zodiacEmoji)          // "🐉"

  // 低级 API 同样可用
  const lunar = ChineseLunarDate.gregorianToLunar(ChineseLunarDate.CHINESE_CONFIG, 2024, 6, 21)
  console.log(lunar)  // { cycle: 78, year: 34, month: 5, leap: false, day: 6 }
</script>

API 参考

值对象类

`ChineseDate` / `JapaneseDate` / `KoreanDate` / `VietnameseDate`

不可变农历日期对象，继承自 LunarDate 基类。

静态构造方法

实例属性

实例方法

静态方法（历法相关）

类型定义

interface LunarDateValue {
  cycle: number   // 六十甲子周期序号（1 起始）
  year: number    // 周期内年序（1-60）
  month: number   // 月（1-12）
  leap: boolean   // 是否闰月
  day: number     // 日（1-30）
}

interface GregorianDate {
  year: number
  month: number
  day: number
}

type CalendarType = 'chinese' | 'korean' | 'japanese' | 'vietnamese'

interface GanZhiPair {
  gan: number   // 天干索引（0-9）
  zhi: number   // 地支索引（0-11）
}

interface GanZhiInfo {
  year: GanZhiPair
  month: GanZhiPair
  day: GanZhiPair
}

interface SolarTermInfo {
  index: number           // 节气序号（1-24）
  date: GregorianDate     // 公历日期
  jde: number             // 儒略日
}

interface FestivalInfo {
  name: string            // 节日名称（本地化）
  key: string             // 节日标识
  month: number           // 农历月
  day: number             // 农历日
  leap: boolean           // 是否闰月
}

type LocaleCode = 'zh-CN' | 'zh-TW' | 'zh-HK' | 'ja-JP' | 'ko-KR' | 'vi-VN'

构建

npm run build        # 编译 ESM + CJS + IIFE
npm run build:types  # 生成 .d.ts 类型声明
npm run test         # 运行测试
npm run clean        # 清除 dist

架构

src/
├── types.ts              # 核心类型定义
├── core/
│   ├── astronomy-lite.ts # 自研轻量天文模块（VSOP87 截断数据）
│   ├── config.ts         # 四种历法配置（纪元 + 时区历史）
│   └── algorithm.ts      # 核心算法（公历 ↔ 农历转换）
├── ganzhi.ts             # 天干地支
├── zodiac.ts             # 生肖
├── solar-term.ts         # 24 节气
├── festival.ts           # 传统节日
├── locale.ts             # 多语言 / 多地区
├── format.ts             # 格式化 + 解析
├── chinese-numerals.ts   # 中文数字
├── lunar-date.ts         # 不可变值对象 API
└── index.ts              # 主入口

设计原则

• 不可变值对象 — 实例创建后不可修改，with() / addDays() 返回新实例
• 纯函数核心 — 底层算法全部为纯函数，无副作用，便于测试
• 配置驱动 — 不同历法通过 CalendarConfig 区分（纪元年、时区历史规则）
• 缓存优化 — 天文计算结果自动缓存，避免重复计算

反馈与协作

如果您在使用过程中遇到问题，或有功能建议、商务合作等需求，欢迎通过邮件联系我们：

📧 gyfinjava@163.com

License

MIT License

Copyright (c) 2025 北京锋通科技有限公司 (郭玉峰, 吴琼)