Suncalc 完整使用指南：5分钟掌握JavaScript太阳位置计算

2026-02-06 04:28:28作者：苗圣禹Peter

Suncalc是一个轻量级JavaScript开源库，专门用于计算太阳和月亮的位置、光照时段以及月相变化。这个强大的工具由Vladimir Agafonkin开发，广泛应用于地理信息系统、天文学应用和Web开发场景中。

快速入门指南

环境准备与安装

首先需要将Suncalc库添加到你的项目中。可以通过NPM包管理器轻松安装：

npm install suncalc

或者直接通过CDN引入：

<script src="https://cdn.jsdelivr.net/npm/suncalc@1.9.0/suncalc.js"></script>

基础使用示例

让我们从一个简单的例子开始，计算伦敦今天的日出日落时间：

import * as SunCalc from 'suncalc';

// 获取伦敦今日的光照时间
const times = SunCalc.getTimes(new Date(), 51.5, -0.1);

// 格式化日出时间
const sunriseStr = times.sunrise.getHours() + ':' + times.sunrise.getMinutes();

console.log('日出时间:', sunriseStr);
console.log('日落时间:', times.sunset.getHours() + ':' + times.sunset.getMinutes());

核心功能详解

太阳位置计算功能

Suncalc提供了精确的太阳位置计算能力，包括太阳高度角和方位角：

// 计算日出时太阳的位置
const sunrisePos = SunCalc.getPosition(times.sunrise, 51.5, -0.1);

// 将方位角转换为度数
const sunriseAzimuth = sunrisePos.azimuth * 180 / Math.PI;

console.log('太阳高度角:', sunrisePos.altitude);
console.log('太阳方位角:', sunriseAzimuth);

月亮位置与月相功能

除了太阳计算，Suncalc还提供完整的月亮位置和月相计算：

// 获取当前月亮的照明情况
const moonIllumination = SunCalc.getMoonIllumination(new Date());

console.log('月相:', moonIllumination.fraction); // 0.0（新月）到1.0（满月）
console.log('月亮相位:', moonIllumination.phase);

实际应用场景

摄影黄金时段计算

对于摄影师来说，黄金时段是最佳的拍摄时间。Suncalc可以精确计算这些时段：

const times = SunCalc.getTimes(new Date(), 39.9042, 116.4074); // 北京

console.log('早晨黄金时段结束:', times.goldenHourEnd);
console.log('傍晚黄金时段开始:', times.goldenHour);

天文观测时间规划

天文学爱好者可以利用Suncalc规划观测活动：

// 获取月亮升起和降落时间
const moonTimes = SunCalc.getMoonTimes(new Date(), 40.7128, -74.0060); // 纽约

console.log('月亮升起:', moonTimes.rise);
console.log('月亮降落:', moonTimes.set);

高级使用技巧

自定义时间点计算

Suncalc允许你添加自定义的时间计算规则：

// 添加自定义时间：太阳高度达到10度时
SunCalc.addTime(10, 'morningCustom', 'eveningCustom');

const customTimes = SunCalc.getTimes(new Date(), 35.6762, 139.6503); // 东京

console.log('早晨10度时间:', customTimes.morningCustom);
console.log('傍晚10度时间:', customTimes.eveningCustom);