## 一、起点：一份很完整、但没法开工的方案

事情开始于一份别人的对话记录。42 条消息、21 个来回，对面把天气 App 的功能清单、数据源选型、技术栈都聊透了，最后落在 KMP（Kotlin Multiplatform）：一套代码，同时出 Android 和 iOS。

方案本身挑不出毛病。问题在我这边：

- 这台机器上没有 Android SDK，也没有 Xcode；
- 就算装上了，我也没法验证「装到手机上到底能不能用」；
- 而我真正想要的很朴素：一个打开就能看天气、没有广告、不用注册的东西。

**方案是对的，环境不对。** 这两件事经常被混为一谈——方案评估的是「该怎么做」，而落不了地往往是「这里能不能做」。

我把整份对话记录丢进 WorkBuddy，说的第一句话不是「照着写」，而是：

> 这份方案里哪些部分在我这台机器上跑不起来？如果目标是「打开就能用、不用注册任何 Key」，这个方案要怎么改？

下面所有事情，都从这句问话开始。

![WorkBuddy 对话过程](https://developer.qcloudimg.com/http-save/yehe-12738190/816adb06c0980177b2a2248a28d477bc.png)

*把方案丢进 WorkBuddy 后的关键几轮：先判环境（KMP 在这台机器上跑不起来），再定形态（PWA），然后是零 Key 和额度治理——每一步都是先谈约束再动手*

---

## 二、第一步不是写代码，是把 20 多个数据源挨个测一遍

WorkBuddy 先做的事让我有点意外：它没有开始搭界面，而是跑去做了一份调研报告（`docs/免限额天气数据方案调研.html`），把点播接口、整幅图、瓦片、原始 GRIB、自建、共享缓存这六类路线穷举了一遍，**20 多个数据源全部一手实测**——状态码、返回体积、数据滞后多少分钟，一个个记下来。

这份调研直接决定了后面所有的取舍，比如：

| 数据                | 走的路线               | 为什么不这么走不行           |
| ----------------- | ------------------ | ------------------- |
| 预报 / 空气 / 花粉 / 历史 | Open-Meteo 点播      | 免费、无需 Key、字段全       |
| 降水雷达              | RainViewer 瓦片      | 瓦片不按坐标计费            |
| 台风                | 中央气象台 CMA，JMA 交叉校验 | 官方权威，且有 12–120 小时预报 |
| 卫星云图              | NASA GIBS 瓦片       | 零额度，额度打满时的兜底        |
| 全国实况图             | 中央气象台整幅图           | 一张图一次请求，完全不消耗坐标额度   |
| 地震                | USGS GeoJSON       | 免费、无需 Key           |

调研里被划掉的一整类，反而更值得记：商业天气 API（WeatherAPI、VisualCrossing、和风天气、心知天气）**不带 Key 直接打，实测一律被拒**——401、401、403、403。它们都有免费额度（1000 次/日、100 万次/月这类），但都要注册、都有天花板，跟「打开就能用」的目标直接冲突。

划掉它们的代价是分钟级降水这类精细数据拿不到；好处是拿到代码的人不用先花半小时去注册账号——它真的打开就能跑。这个取舍我认。

这一步给我的经验是：**先让 AI 把「哪些能做、哪些不能做」的边界测出来，比让它先写代码重要得多。** 边界不清楚就动手，写到一半才发现某个源要 Key，返工的不只是那个模块，是整条数据链。

---

## 三、方案被改了三次

### 1. KMP → PWA

WorkBuddy 的判断很直接：你要的是「手机上能装、能离线打开」，而不是「上架应用商店」。既然本机没有 Android SDK 和 Xcode，那就不走原生，改成 PWA——原生 ES Module + 原生 CSS，零依赖零构建，写完刷新就能看，浏览器里能验，装到主屏就是独立 App。

这个改动看着是降级，其实是把目标重新定义了一遍：**我要的是「能用」，不是「用原生」。**

### 2. 坚持「零 Key」

所有需要注册、需要填 Key 的接口一律不用。这条线守得很死，代价是某些数据质量要打折（比如分钟级降水），好处是拿到代码的人不用先花半小时注册账号——它真的打开就能跑。

### 3. 额度治理：换数据形态，而不是换供应商

这是整个项目里最花心思的一块。Open-Meteo 免费层是 600/分、5000/时、10000/日，**按出口 IP 算**，而且**多坐标请求里每个坐标都单独计数**（`latitude=a,b,c` 算 3 次，不是 1 次）。

早期版本一次取 169 个坐标、每次平移整屏重取，一天就能把额度打满，之后全站 429，连首页天气都只能吃缓存。

最后落了四层防护：

1. **采样收敛 + 客户端插值**：联网只取 6×6 = 36 个坐标，屏幕上铺成 13×13 的细格子，坐标消耗降到原来的 1/5；
2. **同主机变量合并**：温度和云量合并成一次请求（36 坐标而不是 72）；
3. **按变量差集补取**：先开温度再开云量，只补 `cloud_cover`，温度走缓存——同一视野反复开关图层是 0 次请求；
4. **额度记账 + 冷却分级**：面板底部有进度条，撞到 429 会按官方 reason 判断是分钟级还是日级，**分钟级只等约 65 秒**，早年一律按「到次日」处理，用户看到的就是「勾了图层一点反应都没有」。

另外把图层分成两类，面板上直接标出来，让用户知道额度紧张时该关哪几个：

| 类别            | 图层                 | 额度             |
| ------------- | ------------------ | -------------- |
| 瓦片 / 矢量 / 整幅图 | 降水雷达、台风路径、地震点、卫星云图 | **0**，随便开关随便平移 |
| 格点采样（按坐标计费）   | 温度色块、风场粒子、空气质量、云量  | 一个坐标算一次调用      |

![额度面板](https://developer.qcloudimg.com/http-save/yehe-12738190/b156364e474f1148af3786c0c0e4de31.png)

*图层面板底部的额度条，四个绿色「0 额度」徽标由测试守着*

这里有个通用的思路我后来一直在用：**额度不够用，先别急着换供应商，先看数据形态。** 整幅图和瓦片是静态资源，天生没有「按次」这回事；按坐标点播才天生按次计费。能搬的先搬走，搬不走的再去治理。

---

## 四、六个真踩到的坑

这几个是文章里我最想写的部分——它们都不是写代码时发现的，是跑起来之后才露出来的。

### 坑 1：画出来了，但看不见

风场粒子（canvas 粒子流，不是箭头标记）一直是「正常绘制」的：测试数出 2.8 万个着色像素，一路绿灯。

**现象和断言对不上**：修好之前，用户两次反馈「粒子看不到」，测试却两次都是绿的。

**定位**靠一个笨办法——把地图区域截两次图（藏掉该层 / 显示该层）做**逐字节比对**，遮挡时两张图完全相同，一眼露馅；根因是 canvas 的 z-index 380，被 z-index 400 的 `.leaflet-map-pane` 整个盖住。

**改法**直接：把 canvas 提到 400 以上、挂进地图面板内部，再用逐字节比对守一遍，确认两层不再重叠。

![风场粒子](https://developer.qcloudimg.com/http-save/yehe-12738190/773afab895f53b445a20fb7a3cbfdb25.png)

*修好之后的风场粒子层*

这条教训我记下了：**断言「画出来了」不等于断言「看得见」。** 现在这个方法同时守着风场和卫星云图两个图层。

顺带修掉的另一个坑：网格用的是 `Float32Array`，缺值存的是 `NaN`，而判空写的是 `== null`（`NaN == null` 为 false），NaN 会把粒子坐标污染成 NaN，整片画不出来。

### 坑 2：首屏慢，主因不是代码，是服务方式

（现象 → 定位 → 改法：先以为是体积，查下去发现是 HTTP/1.0 + 不压缩，只换服务、不砍一行业务代码就解决。）

一开始我用 `python -m http.server` 起本地服务。测出来首屏很慢，我以为是体积问题——查下去发现根本不是：

**`python -m http.server` 用的是 HTTP/1.0**，每个请求新建一条 TCP 连接，而且不做压缩。本项目首屏 15 个请求，弱网下光连接建立就吃掉一大截。

同一份代码，只把服务换成项目自带的 `tools/serve.mjs`（gzip + HTTP/1.1 keep-alive）：

| 网络 | 服务方式                | FCP         | load        | 首屏传输         |
| -- | ------------------- | ----------- | ----------- | ------------ |
| 4G | python http.server  | 996 ms      | 2213 ms     | 949.8 KB     |
| 4G | **tools/serve.mjs** | **616 ms**  | **1325 ms** | **359.4 KB** |
| 3G | python http.server  | 2604 ms     | 10604 ms    | 949.8 KB     |
| 3G | **tools/serve.mjs** | **1336 ms** | **4516 ms** | **359.4 KB** |

**先修服务方式，再谈砍体积。** 反过来做等于给一个漏水的桶换水龙头。

### 坑 3：手机走局域网 IP 时，PWA 能力为零

我想当然地以为起个服务、手机连同一个 Wi-Fi 打开就能装主屏。实测：

| 访问方式                      | isSecureContext | `navigator.serviceWorker` | 可注册 SW |
| ------------------------- | --------------- | ------------------------- | ------ |
| `http://127.0.0.1:8777`   | 是               | 存在                        | 是      |
| `http://192.168.x.x:8777` | **否**           | **不存在**                   | **否**  |

局域网 HTTP 下没有离线缓存、装不到主屏、**每次都是完整冷加载**。这不是配置问题，是浏览器的安全上下文规则——只有 localhost 和 HTTPS 被信任。

所以最后必须给它一个 HTTPS 地址，发布成线上站点才拿到完整 PWA 能力。

### 坑 4：官方实况图的三个边界

服务页那四张中央气象台的整幅图（雷达拼图 / 真彩云图 / 气温实况 / 降水实况）是「零额度」的关键——一张图一次请求，服务端按 CDN 资源处理，没有按坐标计次这回事。但三条约束都是实测踩出来的：

1. **文件名是 UTC，图上标的是北京时间。** `202610040424` 那张雷达图上写的是「12:24」，差 8 小时。界面统一按北京时间显示，否则用户会以为时间错了。
2. **CDN 只保留约 24 小时**（回看 24h 还在、48h 已 404），所以时间轴窗口不能超过一天。
3. **必须用 `<img>` 加载，不能 `fetch`。** 跨域静态资源没有 CORS 头，`fetch` 会被浏览器拦掉；「探测最新一档」也只能靠图片的 load/error 事件逐档回退。

![官方实况图](https://developer.qcloudimg.com/http-save/yehe-12738190/796be566acf245b67fb61d4f51c37565.png)

*中央气象台整幅图产品，带时间轴和播放*

### 坑 5：台风接口是 JSONP，字段还是位置数组

CMA 的台风接口返回 JSONP，而且**字段没有名字，是数组下标**。这意味着上游一旦调整字段顺序，解析就出错。做了全字段容错，但这属于免费公开接口的固有风险，只能兜着。

另外 CMA 和 JMA 都是权威机构，但定位取整和判定标准略有差异——实测同一台风两源相差约 50 km，属正常，所以做的是交叉校验而不是「以谁为准」。

![台风](https://developer.qcloudimg.com/http-save/yehe-12738190/e810a2058e4d0fde16f7c5e7b34bab07.png)

*台风实况路径按强度分段着色，虚线是预报路径，另有七级风圈*

台风预警也不是「图标提示」，是按你和台风的**实际距离**定级：已在七级风圈内是红色，未来 120 小时路径最近距离 ≤200 km 是橙色，≤300 km 是黄色。

### 坑 6：开机自启的 bat 文件名不能是中文

做常驻服务时，往启动文件夹放转发脚本，文件名一开始用了中文。结果中文名在「命令行 → 进程」这条链上会被代码页反复转码，**实测连自己的测试脚本都因此报 `FileNotFoundError`**，而同一个文件用 `--status` 却读得到。

自启起不来时没人看得见，所以文件名刻意改成 ASCII（`qingyun-weather.bat`），不留这种脆弱点。

同一个模块里还有一条：常驻进程必须经 **WMI/CIM** 创建，父级是系统服务 `WmiPrvSE.exe`，才活得过启动窗口——`Popen` / `nohup` / `start /min` 都会被回收。这条不是文档里写的，是实测掉过两次服务才试出来的。

---

## 五、把「声称」变成「可断言」

这个项目里我反复跟 WorkBuddy 提的一个要求是：**不许只说「应该没问题」，要么拿数字，要么写测试。**

最后落下来的三招：

1. **请求计数器**：测试里挂一个计数器专门盯 `open-meteo.com`。「浏览官方实况图（翻图 + 播放 + 切产品）期间请求数必须为 0」是硬断言——所以「那四张官方图随便看，一点额度都不花」不是说法，是被测试钉住的事实。
2. **上游桩**：`proxytest` 在本地起一个假的 Open-Meteo 上游，于是「真正打给上游几次」变成可以精确断言的数字：5 个邻近坐标必须只打 1 次、参数换顺序必须命中同一条缓存、4 个并发相同请求必须只打 1 次、429 绝不能被缓存。
3. **截图逐字节比对**：就是前面风场粒子那招，专门抓「画出来了但被挡住」。

还有一条原则：**性能测试只拿确定性量当断言，时间只做报告。** 首屏耗时受机器负载和网络抖动影响，拿它守门必然制造假警报。所以硬断言的是传输字节（≤420 KB）、请求数（≤20）、是否真的压缩过、SW 是否可用——这几个量由文件内容和配置决定，不会骗人；FCP/load 只打印。

同样的原则在定位链路测试里是：**环境问题不许冒充代码问题，代码问题也不许躲在环境后面。** 空气质量域名本机间歇性不可达，这时断言会自动改为验证「优雅降级」并标注，同时用打桩把「接口挂了」和「代码坏了」分开。

最终状态：**437 项测试全部通过**（天气数据层 164、浏览器端 151、台风数据层 42、额度护栏 40、代理与数据源 30、定位链路 5、首屏性能 5），另有模块语法闸门。

![测试终端](https://developer.qcloudimg.com/http-save/yehe-12738190/80b8fd4d7c1b8b35a2a5a1ee99f2c554.png)

*七套测试套件的结果：437 项全部通过。每一套都对应 README 里可复现的一条命令，不是「我测过了」三个字*

![天气页](https://developer.qcloudimg.com/http-save/yehe-12738190/d951882d3c31078f87f4cdab5605389e.png)

*天气页：实时、48 小时逐时、7 天、空气质量、花粉、生活指数、趋势图*

![雷达页](https://developer.qcloudimg.com/http-save/yehe-12738190/507bf1c3bc87a0b25f84f0a893ddbe1f.png)

*雷达页：地图铺满整屏，雷达回放 + 台风 + 8 个可叠加图层*

![AI 播报](https://developer.qcloudimg.com/http-save/yehe-12738190/c53eaf0a23f068a6cd0e9a7afb729306.png)

*顶部那条「AI 播报」是本地规则生成的，刻意不接大模型——它本质是数据摘要，规则算反而更准，也不多花一次请求*

---

## 六、我现在每天在用它

成果长这样：

- **天气页**：实时 / 48 小时逐时 / 7 天 / 空气质量 / 花粉 / 生活指数 / 本地判定的气象预警，右下角还有一只随天气换表情的小挂件（12 种情绪，零额外请求）
- **雷达页**：过去 2 小时降水回放、台风追踪、8 个图层可叠加、风场粒子、卫星云图
- **服务页**：中央气象台四张整幅实况图、路线天气、全球地震、历史回放
- **我**：数据源可切换（官方直连 / 自建 / 共享缓存代理）、额度总览

![手机端](https://developer.qcloudimg.com/http-save/yehe-12738190/530856983e81eb043eb34cd18ddda6de.png)

*手机端，装到主屏后和原生 App 没有区别*

![深色模式](https://developer.qcloudimg.com/http-save/yehe-12738190/487393aaa14f6883950527c7843ae965.png)

*深色模式，底图单独反色，雷达回波颜色不受影响*

线上地址：<https://qingyun-weather.app.workbuddy.host/>，PWA 能力齐全（`isSecureContext = true`，Service Worker 注册成功）。

零依赖、零构建：原生 ES Module + 原生 CSS，不打包不编译，改完刷新即可。地图用的 Leaflet 已经本地内置，不依赖 CDN。

---

## 七、这两天我改变的三个做法

写这篇文章的时候我回头想了想，这轮下来真正留下来的不是那个 App，是三个做法上的变化：

**1. 先让它调研，再让它写代码。** 20 多个数据源挨个实测一遍，只花了一小段时间，但把后面所有的返工都省掉了。我以前是拿到需求就让 AI 开写，结果写到一半才发现某个源要注册、某个方案在本机跑不了。

**2. 把「我感觉没问题」换成「测出来是几」。** 这次立了规矩：凡是「省了额度」「看得见」「没多打请求」这类描述，必须有对应的断言。风场粒子那个 bug（测试绿、用户看不见）是最好的例子——没有断言，就只能等用户来告诉你。

**3. 已知限制照实写进 README。** 现在 README 里明写了 13 条：预警是本地判定的、不能替代气象部门发布的预警；雷达只有过去 2 小时没有未来预报；色块是 6×6 粗网格、不能用于专业分析；卫星云图两套源各有硬伤、只能选……写清楚比装作没有要省事得多，也免得别人拿着它去做专业判断。

---

## 八、如果你也想照着做一遍

源码目录结构（零依赖零构建）：

```
weather-app/
├── index.html          # 应用外壳（天气 / AI 雷达 / 服务 / 我）
├── manifest.json       # PWA 清单
├── sw.js               # Service Worker：只缓存静态资源，天气数据永不缓存
├── js/                 # api / alerts / typhoon / geo / quota / pet / live …
├── data/               # 内置 5909 座城市（离线可用，坐标取自 GeoNames，不依赖运行时地理编码）
├── tools/serve.mjs     # 本地预览服务（gzip + keep-alive）
├── tools/proxy.mjs     # 共享缓存代理，一条命令跑起来
├── tools/build_dist.py # 生成部署副本（复制清单从 sw.js 反推，不手写）
└── selftest.mjs / uitest.cjs / quotatest.cjs / proxytest.cjs / …
```

本机跑起来只要两条命令：

```bash
node tools/serve.mjs                 # 打开 http://127.0.0.1:8777
node selftest.mjs                    # 数据层自检，164 项
```

要在手机上当 App 用，需要 HTTPS：`python tools/build_dist.py` 生成 `dist/` 再发布。

最后一句：**这不是「绕过限制」。** 代理发出去的每一个上游请求都是正常请求，只是把重复的合并掉了，对上游而言请求更少。换 Key 轮换、伪造 UA 那类做法这个项目不做。

> **最值钱的一句话**  
> WorkBuddy 不是把方案「翻译成代码」，而是把方案里「在这台机器上跑不起来」的那部分，换成「打开就能用」的另一条路。AI 接管的是「怎么做」，人该守住的是「这里能不能做」——这两件事分不清，方案再漂亮也只是纸上谈兵。

---

*数据来源：Open-Meteo（预报 / 空气质量 / 花粉 / 历史）、RainViewer（雷达瓦片）、中央气象台 CMA（台风 / 实况图）、JMA（台风校验）、NASA GIBS（卫星云图）、USGS（地震）、GeoNames（城市数据）。全部免费、无需 Key。*


事情开始于一份别人的对话记录。42 条消息、21 个来回，对面把天气 App 的功能清单、数据源选型、技术栈都聊透了，最后落在 KMP（Kotlin Multiplatform）：一套代码，同时出 Android 和 iOS。

我把一份聊了 21 轮却落不了地的天气 App 方案，做成了能装进手机主屏的应用

一份聊了 21 轮、却在本机一行都跑不起来的 KMP 天气方案，被 WorkBuddy 改成了免费、无广告、零依赖、不申请任何 API Key 的天气 PWA，能直接装进手机主屏当 App 用。最终 437 项测试全部通过，首屏从 970KB 压到 359KB，正文复盘了六个真实踩坑。

客户端

前端

开发工具

将方案从KMP转向PWA，实测20+数据源，实现零Key天气应用。通过额度治理、图层分层与437项测试，解决性能与可见性问题。提供完整源码、部署指南，支持PWA安装，数据源免费无Key，打开即用。

代码解释

性能测试

WorkBuddy 

Android

Python

Xcode

JSON

2026上云采购 | AI焕新·智启新局

workbuddy

CDN免费试用


热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

我把一份聊了 21 轮却落不了地的天气 App 方案，做成了能装进手机主屏的应用-腾讯云开发者社区-腾讯云

我把一份聊了 21 轮却落不了地的天气 App 方案，做成了能装进手机主屏的应用

我把一份聊了 21 轮却落不了地的天气 App 方案，做成了能装进手机主屏的应用

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐