如何为你的应用添加地图：嵌入式地图、交互式地图与门店定位

要为应用添加地图，首先要决定你需要的是静态嵌入（一个位置加一个标记，例如“找到我们的店铺”），还是交互式地图（由你的数据生成多个标记、支持筛选、聚合，以及“附近”搜索）。对于单一位置，嵌入式地图是最快的方式，而且使用Google的Maps Embed API是免费的。对于交互式地图，请使用JavaScript地图库：Google Maps JavaScript API、Mapbox GL JS，或开源的Leaflet加瓦片服务商。把每个地点的纬度和经度存入数据库，并把API密钥限制为你自己的域名。下面的供应商信息均来自各供应商自己的文档，截至2026年9月。

你需要哪种地图？

大多数小型商家网站只需要第一行。目录、交易市场和列表类网站则需要第三和第四行。

你的选择

Google Maps Platform

Google的入门指南称，你必须创建启用了结算功能的Cloud项目，并启用你想使用的API。其按量付费定价为Essentials SKU（包括Dynamic Maps）提供每月10,000次免费事件的上限，并列出超出部分在首个价格档位下Dynamic Maps为每1,000次事件7.00美元。Maps Embed SKU列为不限量且免费。Google还销售按月订阅套餐。当前价格请查看Google Maps Platform定价。

Mapbox

Mapbox定价页面列出，Mapbox GL JS在网页端每月提供50,000次免费地图加载，之后每1,000次加载收费5.00美元。见Mapbox定价。

Leaflet与OpenStreetMap

Leaflet自我描述为一个开源的JavaScript库，用于移动端友好的交互式地图，约42 KB的JavaScript。它需要从某处获取地图瓦片（即地图的图像）。OpenStreetMap的公共瓦片服务器看似很有吸引力，但其瓦片使用政策要求显示署名，禁止批量下载，不提供服务保证，并警告商业服务其访问权限可能会被撤销。对于正式产品，请使用可与Leaflet配合的商业瓦片源或自行托管的瓦片源。

API密钥：公开，但需限制

浏览器中使用的地图密钥对任何打开你页面的人都是可见的。这是预期之中的，但也意味着有人可能复制你的密钥并消耗你的用量，让你付费。Google的安全指南建议添加网站（HTTP引荐来源）限制，列出你的域名；并添加API限制，使该密钥只能用于你所使用的API。

用于服务器端服务的密钥（例如为成千上万个地址进行地址编码）应当与之分开，保存在服务器端密钥中，而不是放在页面里。同时，请在服务商的控制台中设置预算提醒或配额，防止一个失误变成一笔巨额账单。

地址编码：把地址转换为坐标一次即可

地图标绘的是纬度和经度，而不是地址。把地址转换为坐标称为地址编码（geocoding），大多数服务商对每次请求都收费。高效的做法是：

1. 保存列表时，在服务器上对其地址进行地址编码。
2. 把纬度和经度存入数据库。
3. 地图读取已存储的坐标；它绝不在页面每次打开时进行地址编码。

请检查各服务商的条款，了解你可以保存地址编码结果多长时间，因为各家的规定不同。

示例提示词

单一嵌入式地图：

在联系页面上，使用Maps Embed API嵌入一张Google地图，显示我们的地址（12 High Street, Leeds），密钥保存在 GOOGLE_MAPS_EMBED_KEY 中。在地图下方添加一个“获取路线”链接。在手机上使其全宽显示，并启用懒加载。

列表的交互式地图：

在 listings 表中添加纬度和经度。创建列表或其地址变更时，使用 GEOCODING_API_KEY 中的密钥在服务器上进行地址编码，并保存坐标。在浏览页面上，使用Leaflet显示地图，每个列表一个标记；标记重叠时使用聚合。点击标记显示标题、价格和链接。地图和列表应使用相同的筛选条件。

“附近”功能：

添加一个“附近”按钮，请求访问者的位置，并显示10公里内的列表，按距离排序。如果对方拒绝位置访问，则让他们输入城市名称。

分步操作

1. 选择地图类型，参考开头的表格。
2. 创建服务商账户和项目，并只启用你需要的API。
3. 创建密钥：一个限制为你的域名（包括构建期间使用的预览域名）的浏览器密钥，以及在需要时用于地址编码的服务器密钥。
4. 把密钥保存为机密，并让构建器使用它们；即使浏览器密钥最终出现在页面中，也要保持其限制。
5. 为每个地点存储坐标到数据库中。
6. 构建地图：标记、弹出窗口、聚合，以及合理的默认缩放级别。
7. 与列表搭配使用。 只有地图很难在手机上使用，屏幕阅读器也无法读取。请以列表形式显示相同的结果。
8. 在服务商控制台中设置预算提醒。
9. 在正式域名上发布并测试，因为引荐来源限制通常会在添加正式域名之前阻止地图显示。

常见错误

• 未加限制的密钥。 任何人都可以在他们自己的网站上复用它们。
• 每次打开页面都进行地址编码。 既慢又贵；应在保存时编码一次。
• 在密钥限制中忘记正式域名。 在预览中可以正常显示，到了正式环境却是一个空白的灰色方框。
• 只有地图、没有列表的布局。 只有标记而没有列表，在小屏幕上很难使用，也无法被辅助技术访问。
• 数百个标记却没有聚合。 既难以辨认又会变慢。
• 缺少署名。 大多数地图和瓦片服务商都要求署名，隐藏署名违反其条款。
• 在页面加载时就请求位置。 只在用户点击“附近”时才应请求。

检查清单

• 已为工作选择正确的地图类型
• 浏览器密钥已限制为你的域名和所需API
• 服务器端密钥保存在机密中
• 坐标已存入数据库，且只进行一次地址编码
• 结果同时以列表形式显示
• 大量标记时使用了聚合
• 署名清晰可见
• 已在服务商控制台中设置预算提醒
• 已在正式域名和手机上测试

在Mythex中添加地图

Mythex没有内置的地图集成；你需要自带服务商密钥，把它添加为项目机密（或在代理显示机密卡片时粘贴进去），然后在聊天中要求添加地图，具体方法见集成任意API。坐标存放在项目的数据库中。别忘了把预览域名和正式域名都添加到密钥的网站限制中，并在修改机密后重新发布。

地图通常与搜索和列表配合使用：参见如何为应用添加搜索、如何构建目录网站和如何构建小型商家网站。

常见问题