最稳妥快速的方式是iframe嵌入：复制谷歌地图“嵌入地图”生成的完整/embed?链接，用div包裹并设CSS高度，禁用file://协议，添加loading="lazy"等属性确保兼容性。
直接在 index.html 里嵌入谷歌地图，最稳妥、最快能出效果的方式是用 iframe —— 不需要密钥、不写 JS、不配环境，复制粘贴就能跑。
用 iframe 嵌入地图时 src 属性必须是完整 embed 链接
很多人复制了谷歌地图地址栏里的 URL（比如 https://www.google.com/maps/place/...），直接塞进 iframe src，结果白屏或报错 Refused to display。这是因为谷歌只允许其官方生成的 /embed? 路径被 iframe 加载。
- 正确做法：在谷歌地图页面点右下角「⋮」→「共享或嵌入地图」→ 切到「嵌入地图」标签页 → 复制整段
<iframe src="https://www.google.com/maps/embed?pb=..."> - 别手动拼接
src，pb=后面那串参数含坐标、缩放、样式等，改错一个字符就失效 - 如果地图显示为空白但控制台无报错，大概率是用了非
/embed?的链接
iframe 宽高设为 100% 时必须包裹在有尺寸的父容器里
iframe width="100%" height="100%" 看起来响应式，但浏览器无法解析“100% of what？”——若父元素没显式宽高，它会坍缩成 0×0。
- 推荐结构：
<div class="map-wrapper"><iframe ...></div>，然后用 CSS 给.map-wrapper设固定高度（如height: 450px）或响应式高度（如padding-top: 56.25%配合绝对定位） - 别只靠
width: 100%，移动端上没设max-width容易撑破布局 - 加
loading="lazy"和referrerpolicy="no-referrer-when-downgrade"可减少隐私警告和加载阻塞
用 JavaScript API 初始化地图前必须确认三件事
如果你需要标记、点击事件、动态居中等交互能力，就得走 google.maps.Map 这条路，但失败率远高于 iframe——绝大多数问题卡在这三步：
立即学习“前端免费学习笔记（深入）”；
-
script标签必须带async defer，且放在<head>或<body>底部；只放<body>顶部会因 DOM 未就绪而报Cannot read property 'Map' of undefined - API 密钥必须在 Google Cloud Console 开启
Maps JavaScript API服务，仅开启Geocoding API或Places API不行 - 本地开发不能用
file://协议打开 HTML；必须通过http://localhost:xxxx或部署后访问，否则密钥校验直接失败，报InvalidKeyMapError
真正容易被忽略的是 referrer 限制：即使你填了 example.com/*，用 https://www.example.com 访问仍可能被拒——因为 www 是子域名，要单独加白名单或用通配符 *.example.com/*。
