在网页中嵌入在线地图：避开那些“坑”

想在网页里放个地图，看似简单，但新手开发者常常卡在几个意想不到的地方。无论是百度地图还是谷歌地图，从密钥申请到容器渲染，每一步都有需要注意的细节。下面就来梳理一下核心流程和那些容易踩的“坑”。

百度地图 JS API：加载并显示一个基础地图

第一步，也是必不可少的一步，是去百度地图开放平台申请密钥（AK）。没有这个“通行证”，初始化时就会遇到恼人的 Invalid key 错误。

拿到密钥后，事情就简单多了。关键是把引入SDK和初始化容器的顺序搞对：

• 引入SDK的脚本标签 ，必须放在地图容器DOM元素创建之后，或者使用 defer 属性来延迟执行。
• 地图容器，比如一个
  ，必须设置明确的宽度和高度。用百分比当然可以，但要确保它的父级容器不是 height: auto 这种不确定的状态。
• 初始化时，使用 BMapGL.Map（新版GL版）或 BMap.Map（旧版）构造函数，第一个参数传入容器元素或其ID字符串即可。

一个最简示例就能说明一切：

谷歌地图嵌入：为什么经常白屏或报错？

谷歌地图的集成在国内环境稍显复杂，除了众所周知的网络访问问题，密钥配置更是“重灾区”。很多开发者代码写得没错，但地图就是一片空白，或者控制台抛出 Google Maps Ja vaScript API error: InvalidKeyMapError。问题通常出在环境或配置上：

• 本地开发协议不符：直接用浏览器打开本地HTML文件（file://协议）是不行的。必须通过本地服务器（如 https://localhost）访问，或者部署到线上域名。
• 服务未启用：在Google Cloud控制台创建API密钥后，必须手动启用 Maps Ja vaScript API 这项服务，否则密钥无效。
• 域名限制过严：如果为密钥设置了HTTP referrer限制，请务必检查当前页面的域名是否在允许列表内。例如，白名单填了 example.com/*，但用 www.example.com 访问，就会被拦截。
• 加载方式有误：引入API的脚本标签，async 和 defer 属性建议都加上，以确保不阻塞页面渲染且执行顺序正确。

加载完成后，别急着初始化地图，最好等API完全就绪。使用回调函数是最稳妥的方式：

不用API密钥？试试静态图或iframe嵌入

如果你的需求只是展示一个固定位置，不需要用户交互（如缩放、拖拽、添加标记），那么完全不必动用复杂的JS API。静态图片或iframe嵌入是更轻量、几乎零配置的选择。

• 百度静态图：直接通过一个图片URL就能获取地图截图，非常适合嵌入邮件、PDF报告或简单的展示页面。URL格式类似：https://api.map.baidu.com/staticimage/v2?ak=YOUR_AK¢er=116.404,39.915&width=600&height=400&zoom=15。
• 谷歌静态图：原理类似，但同样需要API密钥。URL形如：https://maps.googleapis.com/maps/api/staticmap?center=39.915,116.404&zoom=15&size=600x400&key=YOUR_KEY。
• iframe嵌入（对非技术用户最友好）：直接在百度或谷歌地图的网页版上找到你要的位置，点击“分享”->“嵌入地图”，复制生成的