墨迹天气 API 常见错误与排错指南

原创于 2026-07-07 06:25:44 发布 · 47 阅读

2 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

后端开发

适用场景

当你的应用需要获取全国 3 万+ 城市的实时天气、未来 7 天预报、24 小时逐小时趋势、空气质量指数（AQI）、9 项生活指数（穿衣、防晒、限行等）以及气象预警与农历信息时，墨迹天气 API 是一个一站式的选择。它支持按城市名或内部 ID 查询，也提供历史天气追溯功能。然而，在实际接入过程中，由于参数拼写错误、查询模式混用、鉴权配置不当等原因，开发者可能会遇到各种返回错误。本文将从实战角度出发，系统梳理这些常见问题及其排查方法。

接口能力边界

在开始排错前，你需要理解该接口的核心规则：

请求方法：GET
基准地址：https://v1.apizero.cn/api/moji-weather
QPS 限制：5 次/秒，超出后返回 429 状态码
缓存策略：
- 实况数据：缓存 5 分钟
- 当月历史：缓存 30 分钟
- 过去月份历史：缓存 24 小时
数据用途：由墨迹天气官方提供，不能用于农业、保险、航运、防灾等专业决策场景

所有返回数据均以 JSON 格式包裹在 code / msg / data 结构中。code: 0 表示成功，非零值表示错误。

参数与鉴权

请求支持两种鉴权方式（二选一无需同时使用）：

Header 方式：添加 Authorization: YOUR_API_KEY
Query 方式：添加 ?api_key=YOUR_API_KEY（建议使用 Header，更规范）

核心 Query 参数：

参数	类型	必填	说明
`city`	string	否	城市中文名，支持模糊匹配，与 `id` 二选一
`id`	number	否	城市 internal_id，优先精确匹配
`op`	string	否	取值 `search` / `history`，缺省为实况
`keyword`	string	配合 `op=search`	城市关键字，支持中文、拼音、首字母
`limit`	number	配合 `op=search`	返回条数，1~50，默认 20
`day`	string	配合 `op=history`	日期，格式 YYYY-MM-DD / MM-DD / DD，需额外提供 `month`
`month`	string	配合 `op=history`	月份 YYYYMM，可查整月数据

请求示例（curl）

获取实况天气：

curl -sS \
  -X GET \
  -H "Authorization: YOUR_API_KEY" \
  "https://v1.apizero.cn/api/moji-weather?city=北京"

按 internal_id 查询（更快）：

curl -sS \
  -X GET \
  -H "Authorization: YOUR_API_KEY" \
  "https://v1.apizero.cn/api/moji-weather?id=33"

搜索城市列表获取 id：

curl -sS \
  -X GET \
  -H "Authorization: YOUR_API_KEY" \
  "https://v1.apizero.cn/api/moji-weather?op=search&keyword=大化&limit=5"

查询历史天气：

curl -sS \
  -X GET \
  -H "Authorization: YOUR_API_KEY" \
  "https://v1.apizero.cn/api/moji-weather?op=history&city=北京&day=2026-05-12"

响应数据解读

成功时返回如下结构（已精简）：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "_cached": false,
    "city": {
      "id": 1205,
      "name": "大化瑶族自治县",
      "parent": "广西壮族自治区",
      "pinyin": "dahuayaozuzizhixian",
      "timezone": 8
    },
    "condition": {
      "temperature": 32,
      "condition": "多云",
      "humidity": 62,
      "wind_dir": "南风",
      "wind_level": 3
    },
    "aqi": {
      "value": 29,
      "level": 1,
      "description": "优"
    },
    "forecast_day": [ /* 7 天预报 */ ],
    "forecast_hour": [ /* 24 小时 */ ],
    "index": [ /* 生活指数 */ ],
    "summary": "大化瑶族自治县，多云，32℃，南风3级，空气优。"
  }
}

注意 _cached 字段标识本次是否命中缓存。condition 中的 lunar_date 为农历日期。

常见错误与排错

以下列出接入过程中的高频问题，按错误来源分类。

1. 城市参数错误：city 与 id 冲突或都缺失

现象：返回 code: 400，msg: "参数错误，city 与 id 必填其一"（示意）

原因：请求未提供 city 也未提供 id，或同时提供了两者但值不一致。

排查步骤：

检查请求 URL 中是否包含 ?city=xxx 或 ?id=xxx
确认城市名无编码问题（如空格被编码为 %20 仍可接受，但优先使用正确中文）
如果同时使用 city 和 id，API 会优先使用 id，但建议只传一个以避免混淆

2. 无效的 internal_id

现象：返回 code: 404，msg: "未找到该城市"，且 data 为空

原因：传入的 id 在数据库中不存在，可能从旧版本或第三方复制而来。

排查步骤：

先用 op=search&keyword=城市名 获取正确的 id
注意 id 是 number 类型，不要用字符串 "33" 导致类型不匹配（但 API 通常会自动转换，推荐仍传 number）
id 是内部整数，不同环境可能不同，请以当前接口搜索为准

3. 鉴权失败

现象：返回 HTTP 401 或 403，响应 JSON 中 code: 10001（示意），msg: "无效的 API Key"

原因：

未提供 Authorization Header 或 api_key Query 参数
API Key 过期、被禁用或密钥错误

排查步骤：

确认 Header 名称为 Authorization，而非 X-API-Key（部分早期文档可能不同，以最新文档为准）
检查 Key 是否包含多余空格或换行符
尝试在浏览器中直接访问 https://v1.apizero.cn/api/moji-weather?city=北京&api_key=YOUR_KEY 排查
如果使用环境变量注入，确保变量已正确导出

4. 查询模式错误：op 参数与必要参数不匹配

现象：

请求 ?op=search 但缺少 keyword，返回 code: 400，msg: "search 模式需要 keyword 参数"
请求 ?op=history 但缺少 day 或 month，返回类似错误

排查步骤：

确认 op 取值只能是 search 或 history，拼写错误（如 “seach”）会导致被当作实况查询，此时 keyword 或 day 参数会被忽略
若想只查实况，不要传 op 参数或传空
对于历史查询，若只传 day 而不传 month，API 会尝试从 day 中提取月份；建议明确传递 month 参数