【天地图】告别白屏！轻松替换 HomeAssistant 地图服务商

nxy

零、前言

由于 HomeAssistant 默认使用境外 Carto 地图，常常加载缓慢甚至超时。

而百度地图、高德地图等地图服务由于坐标系和API差异，通常需要使用第三方卡片或者APP。如果相关组件停止更新，可能需要花费大量时间进行迁移。

本教程选择“天地图”作为地图服务提供商，可以免费使用地图瓦片 API（1万次/天）。

该方案不会导致坐标偏移，也无需修改任何现有的地图卡片；如果方案失效，仅需移除脚本，即可快速还原。

完成设置后，将在网页、APP端中的所有原生地图组件中生效。

tips：我可能使用了较新的 JS 语法，使用低版本 Webview 的旧机器可能无法正常替换。

一、步骤

1. 前往天地图官网，注册并获取服务许可（Key）。

   • 注册为个人开发者即可。

   • 谨慎填写应用名称，如果乱填可能会被删除应用（被删可重新创建）。

2. 打开 HomeAssistant 配置文件夹，在 /config/configuration.yaml 文件中添加以下代码。

   # Load frontend themes from the themes folder
   frontend:
    themes: !include_dir_merge_named themes
    extra_module_url:
      - /local/hass_tianditu.js

   • 如果frontend.extra_module_url已存在，则仅需添加一项 /local/hass_tianditu.js 。

3. 从 Github Gist 中下载 hass_tianditu.js 。

4. 在脚本首行填写申请的“天地图Key”，然后将其上传至 /config/www 。

5. 重启 HomeAssistant 即可生效。

二、原理

通过监听 DOM 树的变化，自动将 Carto 地图的瓦片链接替换为天地图的底图和标注图层链接。

当遇到请求的地图级别（Z）超过天地图最大支持级别时，使用算法将瓦片贴图降级并放大。

lovelyelfpop

你贴的js文件代码有问题，大于号 小于号 都变成了 > 和 <

lovelyelfpop

还有，天地图的url报错 https证书错误 NET::ERR_CERT_AUTHORITY_INVALID
需要把  http://t4.tianditu.com  改为  http://t4.tianditu.gov.cn

nxy

lovelyelfpop 发表于 2025-6-18 15:59
你贴的js文件代码有问题，大于号 小于号 都变成了 > 和 <

这个似乎是论坛bug，带有标题的markdown里面代码的部分字符会被转义，目前我没有找到解决方法。

nxy

lovelyelfpop 发表于 2025-6-18 16:03
还有，天地图的url报错 https证书错误 NET::ERR_CERT_AUTHORITY_INVALID
需要把  http://t4.tianditu.com   ...

噢，我的HA是http的，所以可以直接用http://t4.tianditu.com。

如果HA是https可能就要用https://t4.tianditu.gov.cn。

yurunze

能不能把Js代码文件放出来

xiongmx

眼拙，替换后没看出任何区别

nxy

xiongmx 发表于 2025-8-8 19:32
眼拙，替换后没看出任何区别

论坛有bug，大于号和小于号会变成 > 和 < ，需要替换回来

hz153jht

nxy 发表于 2025-8-12 08:50
论坛有bug，大于号和小于号会变成 > 和 < ，需要替换回来

替换了大于小于号，前端里的地图依然还是OpenstreetMap

nxy

hz153jht 发表于 2025-8-13 18:48
替换了大于小于号，前端里的地图依然还是OpenstreetMap

你可以看看控制台有没有报错什么的。