# @happyvertical/weather 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/weather/

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:03:04.872Z
中文译文更新时间：2026-11-17T14:22:53.468Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/weather
原文对照：https://npmcn.com/package/%40happyvertical/weather/?lang=original
项目主页：https://github.com/happyvertical/sdk#readme
源码仓库：https://github.com/happyvertical/sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：57.7 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-23T08:14:21.909Z
- 最新版本发布：2026-11-17T00:03:04.524Z
- 近 30 天下载量：5162（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：131（近 12 个月 131 个）

## 中文简介

HappyVertical SDK 的天气数据提供者抽象

## 安装

```sh
npm install @happyvertical/weather
```

也可以使用：`pnpm add @happyvertical/weather`、`yarn add @happyvertical/weather`、`bun add @happyvertical/weather`

## README

# @ 喜悦的垂直/ 天气

HappyVertical SDK的天气数据提供者抽象.

## 概览

这个 `@happyvertical/weather` 软件包为从多个供应商获取天气预报提供了统一的接口。 它遵循的建筑模式与 `@happyvertical/ai`, (中文(简体) ), `@happyvertical/files`,以及 `@happyvertical/sql`。 。 。 .

## 支持供应商

-   **加拿大环境部** - 为加拿大各地提供政府气象服务(免费)
-   **打开WeatherMap** - 免费和付费的全球气象数据
    -   标准API:5天/3小时预报(免费分级)
    -   1呼叫API 3.0:48小时+8天每日预报(付费级)

## 安装

```bash
pnpm add @happyvertical/weather
```

## Claude 代码背景

为 AI 辅助开发安装 Claude 代码上下文文件 :

```bash
npx have-weather-context
```

这个复制包 `AGENT.md` 文献和记录 `metadata.json` 元数据到您的项目 `.claude/` 目录,使克洛德能够在使用该套件时提供更好的帮助.

## 使用量

### 基本示例

```typescript
import { getWeatherAdapter } from '@happyvertical/weather';

// Create adapter for Environment Canada
const weather = await getWeatherAdapter({
  provider: 'environment-canada'
});

// Fetch forecast for a location (latitude, longitude)
const forecasts = await weather.fetchForLocation(51.0447, -114.0719);

forecasts.forEach(forecast => {
  console.log(`${forecast.timestamp}: ${forecast.temperature}°C - ${forecast.conditions}`);
});
```

### 打开WeatherMap( 自由地层)

```typescript
const weather = await getWeatherAdapter({
  provider: 'openweathermap',
  apiKey: process.env.OPENWEATHER_API_KEY
});

const forecasts = await weather.fetchForLocation(51.0447, -114.0719);
```

### OpenWeatherMap 一个呼叫( 援助级别)

```typescript
const weather = await getWeatherAdapter({
  provider: 'openweathermap-onecall',
  apiKey: process.env.OPENWEATHER_API_KEY
});

const forecasts = await weather.fetchForLocation(51.0447, -114.0719);
```

### 环境可变配置

```bash
# .env
HAVE_WEATHER_PROVIDER=openweathermap
OPENWEATHER_API_KEY=your-api-key-here
HAVE_WEATHER_TIMEOUT=15000
```

```typescript
// Automatically uses environment variables
const weather = await getWeatherAdapter();
const forecasts = await weather.fetchForLocation(51.0447, -114.0719);
```

## API 参考

### `getWeatherAdapter(options?): Promise<IWeatherAdapter>`

工厂用于创建天气适配器的功能.

**选项 :**

-   `provider`数字 : `'environment-canada' | 'openweathermap' | 'openweathermap-onecall'`
-   `apiKey`: API 密钥( OpenWeatherMap 提供者需要此密钥)
-   `timeout`: 请求超时, 以毫秒计( 默认: 1 000)

### `IWeatherAdapter`

```typescript
interface IWeatherAdapter {
  fetchForLocation(
    latitude: number,
    longitude: number,
    options?: FetchOptions
  ): Promise<WeatherForecast[]>

  testConnection(): Promise<boolean>

  supportsLocation(latitude: number, longitude: number): Promise<boolean>
}
```

### `WeatherForecast`

```typescript
interface WeatherForecast {
  timestamp: Date
  temperature: number      // °C
  feelsLike?: number       // °C
  temperatureMin?: number  // °C
  temperatureMax?: number  // °C
  conditions: string       // Human-readable description
  humidity: number         // Percentage 0-100
  windSpeed: number        // km/h
  windDirection?: number   // Degrees 0-360
  windGust?: number        // km/h
  pressure?: number        // hPa
  cloudCover?: number      // Percentage 0-100
  visibility?: number      // km
  precipProbability?: number  // Percentage 0-100
  precipAmount?: number    // mm
  confidence?: number      // Provider's confidence 0-100
  raw: any                 // Provider-specific raw data
}
```

## 环境变量

| 变量 | 类型 | 说明 |
| --- | --- | --- |
| `HAVE_WEATHER_PROVIDER` | 字符串 | 提供者名称 |
| `OPENWEATHER_API_KEY` | 字符串 | 打开WeatherMap API 密钥 |
| `HAVE_WEATHER_TIMEOUT` | 编号 | 请求超时( 毫秒) |

## 测试

默认的套房是离线的和决定性的,有一个按键的例外. 提供方的答复来自所记录的固定装置 `src/__tests__/fixtures/`这样 没有在清洁环境中试验 `test` 到达网络 :

```bash
pnpm turbo run test --filter=@happyvertical/weather
```

例外的是 `google-weather.spec.ts`打开门 `GOOGLE_API_KEY`按 寄存器 : 已存在 —— 见“ 默认套房中的网络隔离 ” `.github/CI.md`与 键未设置, 它的活块跳过, 离线保证 中情局负责 随密钥导出, 它调用实时 Google Weather API from `test`。 。 。 .

其他现场服务的覆盖率 `*.optional.test.ts` 已经 跳过,除非你选择加入。 在其 API 密钥上打开 WeatherMap 门; 环境 加拿大不需要钥匙,所以它在一面明快的旗帜上登出大门:

```bash
ENVIRONMENT_CANADA_INTEGRATION=1 pnpm --filter @happyvertical/weather test:optional
```

在重新录制固定装置后运行活套房,以确认上游有效载荷 仍然符合离线套房的形状。 见 `src/__tests__/fixtures/README.md` 记录每个固定.

## 提供者比较

| 特性 | 加拿大环境部 | 打开WeatherMap | OWM 一通电话 |
| --- | --- | --- | --- |
| **费用** | 免费 | 可自由分级 | 已支付 |
| **覆盖范围** | 仅加拿大 | 全球 | 全球 |
| **预测** | 每日/夜间 | 3小时5天 | 小时+每日 |
| **API 密钥** | 无需 | 需求 | 需求 |
| **更新频率** | ~小时~ | 3小时 | 小时 |

## 许可证

麻省理工学院

## 常见问题

### @happyvertical/weather 是什么？

HappyVertical SDK 的天气数据提供者抽象

### 如何安装 @happyvertical/weather？

在项目目录运行 npm install @happyvertical/weather，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-weather-context，可以用 npx have-weather-context 直接运行。

### @happyvertical/weather 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/weather 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/weather 可以商用吗？

@happyvertical/weather 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/weather 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/weather 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,162 次，日均约 172 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/weather 还在维护吗？

最新版本 0\.113\.1 发布于 2026/11/17（今天）；至今共发布 131 个版本，其中过去 12 个月发布了 131 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

