最近在维护博客侧边栏时，遇到了一次非常典型、也非常“真实”的问题：
最近刚换上的 Hexo 时钟插件，突然因为第三方 API 挂了，直接失效。
这篇文章记录了我从问题出现到完整解决的全过程，包括插件改造与 npm 发布。
这篇文章会讲什么
排查
hexo-butterfly-clock-remake失效原因自行修改并重写 IP 定位逻辑
接入高德地图 Web 服务 API
打包并发布自己的 npm 插件
完成Hexo 插件的安装与更新
一、问题背景：IP 定位接口失效
我上一篇 Blog 使用的是下面这个插件：
hexo-butterfly-clock-remake
用于 Butterfly 主题侧边栏显示：时间 + 天气 + 城市
原插件依赖的 IP 定位接口为：
https://api.vore.top/api/IPdata
某天开始出现异常，表现为：
插件完全不渲染
浏览器控制台请求失败
结论非常明确：
第三方 IP 定位 API 已不可用（接口直接炸了）
而插件本身已经多年未维护，也没有任何备用定位方案。
二、解决思路：用高德地图 Web 服务接管 IP 定位
问题集中在IP → 城市这一步，因此整体思路非常清晰：
保留原有插件结构与注入方式
只替换 IP 定位来源
不影响原有和风天气（QWeather）逻辑
为什么选择高德地图？
高德地图 Web 服务提供了稳定可靠的 IP 定位接口：
https://restapi.amap.com/v3/ip?key={你的Key}
优点非常明显：
接口稳定
国内访问速度快
返回城市 / 省份信息已足够使用
免费额度对博客场景完全充足
三、我具体做了哪些改动
1. 新增配置项
在站点配置或主题配置中新增一项：
gaud_map_key: xxxxxxxxxxxxxxxxxxxxx
说明：
这是高德地图 Web 服务 Key
与 JS SDK Key 不同
专用于 IP 定位接口
2. 修改 IP 获取逻辑
原逻辑（简化）：
IP API → city → QWeather
新逻辑：
高德 IP API → city / province → QWeather
当 IP 接口返回的city为空时，自动 fallback 到province，最大限度避免出现「未知城市」。
四、为什么我选择单独发布一个新插件
我没有直接向原仓库提 PR，而是选择：
独立维护
保持向下兼容
重新发布 npm 包
不影响原插件用户
最终插件命名为：
hexo-butterfly-clock-veeink
📦 GitHub 仓库地址：
👉 https://github.com/kitia01/hexo-butterfly-clock-veeink
这是一个只增强、不破坏的改进版本。
五、发布 npm 包的全过程
1. 登录 npm
npm login
按提示输入：
npm 用户名
密码
邮箱
OTP（如开启 2FA）
2. 配置package.json
确保关键信息正确：
{ "name": "hexo-butterfly-clock-veeink", "version": "1.0.0", "main": "index.js", "keywords": ["hexo", "butterfly", "clock"], "license": "MIT" }
3. 发布到 npm（重点）
npm publish
⚠️ 注意：npm不允许覆盖已发布版本号，每次发布必须升级版本。
六、Hexo 中如何安装 / 更新插件
1️⃣ 安装
（1）卸载旧时钟插件（如存在）
npm uninstall hexo-butterfly-clock npm uninstall hexo-butterfly-clock-anzhiyu npm uninstall hexo-butterfly-clock-anzhiyu-yang npm uninstall hexo-butterfly-clock-remake（2）安装本插件
npm install hexo-butterfly-clock-veeink
2️⃣ 使用方式
（1）添加配置
在站点配置_config.yml或主题配置_config.butterfly.yml中加入：
使用前需注册和风天气开发者账号
👉 https://dev.qweather.com
# electric_clock # see：https://github.com/kitia01/hexo-butterfly-clock-veeink electric_clock: enable: true # 插件开关 priority: 5 # 过滤器优先级 enable_page: all # 应用页面，可写特定路径或 "all" exclude: # 排除页面，可留空或写具体路径 # - /posts/ # - /about/ layout: type: class # 容器类型，class 或 id name: aside-content # 目标容器的 class 或 id # insert_before: user-countdown # 插入到该元素前面 insert_after: card-announcement # 插入到该元素后面（二选一） loading: https://cdn.cbd.int/hexo-butterfly-clock-veeink@1.0.0/lib/loading.gif clock_css: https://cdn.cbd.int/hexo-butterfly-clock-veeink@1.0.0/lib/clock-min.css clock_js: https://cdn.cbd.int/hexo-butterfly-clock-veeink@1.0.0/lib/clock-min.js qweather_api_host: {YOUR API HOST} qweather_key: {YOUR KEY} # 新增：高德地图 Web 服务 Key gaud_map_key: {YOUR KEY} # 高得地图web服务key default_city: "资兴"（2）参数说明
| 参数 | 类型 | 释义 |
|---|---|---|
| priority | number | 【可选】过滤器优先级，数值越小，执行越早，默认为10，选填 |
| enable | true/false | 【必选】控制开关 |
| enable_page | path | 【可选】填写想要应用的页面,如根目录就填’/‘,分类页面就填’/categories/'。若要应用于所有页面，就填all，默认为all |
| exclude | path | 【可选】填写想要屏蔽的页面，可以多个。写法见示例。原理是将屏蔽项的内容逐个放到当前路径去匹配，若当前路径包含任一屏蔽项，则不会挂载。 |
| layout.type | id/class | 【可选】挂载容器类型，填写id或class，不填则默认为id |
| layout.name | id/class | 【必选】挂载容器名称 |
| layout.insert_before | id/class | 【可选】 插入到该元素前面（二选一） |
| layout.insert_after | id/class | 【可选】插入到该元素后面（二选一） |
| loading | URL | 【可选】电子钟加载动画的图片 |
| clock_css | URL | 【可选】电子钟样式CDN资源 |
| clock_js | URL | 【可选】电子钟执行脚本CDN资源 |
| qweather_key | key | 【必选】和风天气 key |
| qweather_api_host | URL | 【必选】和风天气 api_host |
| gaud_map_key | string | 【可选】高得地图web服务key，如果没有填写则根据默认城市优先选择 |
| default_city | string | 【可选】当默认城市为空，优先根据IP定位，填写了默认城市将优先使用默认城市的定位和天气 |
3️⃣ 重新生成博客
hexo cl hexo g hexo s
确认侧边栏：
时间
天气
城市定位
均正常显示。
七、踩坑记录（真实）
❌ JS 压缩（minify）时错误混淆作用域，运行时报
ReferenceError❌ 过度依赖第三方 API 的稳定性
✅ Key 通过配置传入，而非写死
✅ IP 定位失败时增加 fallback，避免 UI 直接炸掉
八、总结
这次经历让我非常清楚地意识到：
博客长期稳定 ≠ 第三方 API 永久可靠
同时也完整走了一遍 npm 插件发布流程
整体并不复杂，但每一步都有坑。
如果你也在使用hexo-butterfly-clock-remake，并遇到城市定位失效的问题，希望这个插件和这篇记录能帮到你。
)
)
