地图发布指南

地图发布将可编辑地图转化为一种稳定体验，让其他人能够打开、嵌入或在产品中使用。主要选择包括独立分享链接、嵌入式 Viewer，以及更深入的应用集成。生产地图还需要访问规则、允许嵌入的域名、线上版本、移动端布局、发布与取消发布路径和衡量机制，而不只是一条 URL。

下文介绍发布模型、访问与域名控制、嵌入布局、消息通信、版本管理、分析，以及 Kaleidr Studio 和 Viewer 界面。产品信息请参阅 Kaleidr Studio。有关嵌入机制，请参阅如何在网站中嵌入交互式地图；有关构建器与 API 的责任归属，请参阅无代码地图构建器与地图 API；有关 SDK 挂载，请参阅什么是 AI 地图 SDK？。

发布要点

制作 ≠ 发布： 草稿可以变化；已发布地图需要稳定的使用界面。

选择耦合程度： 分享链接保持轻量，嵌入位于页面中，产品集成则共享应用状态。

限制宿主： 允许的域名和来源检查应纳入发布契约。

预留空间： 嵌入区域折叠是布局错误，不是地图错误。

在稳定 ID 后进行版本管理： 无需重写每个宿主页面即可衡量、审核、发布和回滚。

交互式地图从制作、审核和发布，进入独立分享、网站嵌入和产品集成，并配有生产控制。

地图发布是什么意思？

创建地图和发布地图是不同阶段。在制作期间，团队可能会更改地点、图层、标签、颜色、瓦片、镜头、筛选器、交互和数据源。发布会创建一个使用界面，例如独立页面、网站嵌入、SaaS 门店定位器、编辑地图，或内部只读视图。制作工具可以容纳草稿，而已发布地图需要可预测的访问、布局、性能、行为、版本、署名和监控。Kaleidr Studio 目前将制作流程描述为 Prompt → Process → Refine → Deploy，并表示完成的地图可以发布为独立页面或嵌入为小组件（Studio）。

团队应分享、嵌入还是集成已发布地图？

三种模型可以涵盖大多数发布场景。分享链接最适合快速审核、营销活动和指南，因为宿主网站几乎不需要实施工作。嵌入式 Viewer 适合网站、落地页、CMS 页面和客户门户，让地图与宿主文案及行动号召并列显示。产品集成则适用于 SaaS、市场平台和自定义工作流，其中筛选器、选中的记录和应用状态需要与地图保持同步。正确选择取决于地图主要是内容、嵌入体验，还是应用状态的一部分。地图可以先以分享链接上线，之后再变成嵌入或产品组件。

模型	最适合	宿主开发量	产品耦合度
分享链接	审核、营销活动、指南	最少	低
嵌入式 Viewer	网站、CMS、门户	低	中
产品集成	SaaS 和自定义工作流	较高	高

Kaleidr 当前的开发者文档称，已发布的 Viewer 地图由分享链接控制，并通过分享 ID 而非通用 API 密钥寻址（Viewer Embed）。分享 ID 用于标识已发布体验；它不是服务器机密，不应按机密处理。Studio 目前表示地图发布后可作为小组件嵌入。Chat 可以连接到现有宿主地图，而 Viewer 围绕已发布的地图体验设计（kaleidr.js）。

三种地图发布模型：独立分享链接、网站嵌入地图，以及与应用状态深度集成的地图。

生产嵌入应如何处理布局、访问和消息通信？

上线前先确定发布契约：公开还是受限访问、允许嵌入的域名、草稿/已发布/已归档状态，以及线上界面是否显示经过审核的数据快照。域名控制应使用 https://www.example.com 和 https://app.example.com 这类纯来源。Kaleidr 当前的 Viewer 文档说明，发布者可为嵌入的已发布地图设置允许域名。受登录保护的宿主页面并不会自动让可独立访问的地图 URL 变为私有；私有业务数据需要专为该场景设计的授权架构。

预留高度和宽度，避免嵌入区域折叠。HTML 规范建议 iframe 具有简洁的 title，以便辅助技术为嵌套浏览上下文命名（HTML Standard）；对框架提出可编程确定名称的硬性要求在 WCAG 4.1.2。对屏幕外的嵌入使用平台支持的 loading="lazy" 延迟加载；HTML 标准定义了延迟加载属性，web.dev 建议推迟屏幕外 iframe 的加载，以减少网络和启动工作。首屏主要地图则应作为关键体验的一部分加载。保留文本后备内容，如地点名称、地址或列表，以便 Viewer 失败时页面仍可使用。

跨来源通信应通过受控渠道进行。window.postMessage() 是窗口与 iframe 之间的标准机制（HTML Standard）。对传入消息验证 event.origin，对传出消息设置具体目标来源；不要默认使用 "*"。Kaleidr 的 Viewer 文档描述了用于受支持行为的 kaleidr-embed:* 消息接口。Viewer 状态和宿主状态应保持分离：已发布地图负责 Viewer 内的镜头和选择，宿主页面负责导航、表单和转化。

// Published Viewer mount: share ID, not a server key
Kaleidr.mount("#published-map", {
  product: "viewer",
  shareId: "YOUR_SHARE_ID"
});

生产地图嵌入架构，包含宿主页面、跨来源 Viewer、允许域名关卡、经过验证的消息通信、响应式尺寸、延迟加载和文本后备内容。

团队应如何管理已发布地图的版本、衡量和回滚？

保存草稿不等于发布线上版本。为地点和嵌入保留稳定标识符，避免内容变化时破坏宿主页面。在这个稳定 ID 后管理版本：编辑新草稿，审核数据质量和移动端布局，发布，验证生产环境，并在发布失败时回滚。不要只衡量地图加载。地图就绪、地点选择、CTA 和错误都是有用信号；除非产品将这些名称记录为自动事件，否则应将其视为编辑建议。将制作分析与 Viewer 分析分开，以免草稿实验污染生产漏斗。

测试故障状态：域名被阻止、分享 ID 未发布、网络缓慢，以及缺少文本后备内容。生产域名、Content Security Policy、署名和出站链接安全都属于同一发布流程。CMS 页面需要预留容器和经过审核的快照；SaaS 产品需要让地图与应用状态耦合；营销页面需要不完全依赖地图交互的转化路径。实时和 3D 地图对性能及后备方案要求更高；只有宿主页面能够承担这些成本时才应发布。

运营地图发布生命周期：Viewer 分析为新草稿、审核后的发布、验证和回滚提供信息，同时嵌入标识符保持稳定。

团队应避免哪些地图发布错误？

错误	风险	更好的方法
将草稿 URL 当作生产版本	内容不稳定、嵌入损坏	发布经过审核的快照
嵌入时不预留高度	布局偏移、地图折叠	设置宽高比或明确尺寸
延迟加载主要地图	首屏为空	立即加载首屏地图
使用 `postMessage("*")`	跨来源欺骗	验证并指定来源
将分享 ID 当作机密密钥	访问模型混乱	将服务器密钥保留在后端
跳过允许域名检查	被意外宿主复用	限制嵌入来源
通过公开分享发布私有数据行	数据泄露	发布前完成授权
每次编辑都更换嵌入 ID	宿主页面损坏	在稳定 ID 后进行版本管理
只衡量地图加载	无法了解产品质量	跟踪就绪、选择、CTA 和错误
不提供文本后备内容	Viewer 失败时页面空白	在 HTML 中重复关键事实

最终结论

当团队把线上地图视为产品界面而非导出文件时，地图发布才能成功。根据地图需要与宿主内容及应用状态耦合的程度，选择分享、嵌入或集成。随后添加生产契约：访问、允许域名、预留布局、经过来源验证的消息通信、版本管理、衡量和回滚。Kaleidr Studio 目前可发布独立页面和可嵌入小组件，Kaleidr Viewer 通过分享 ID 标识已发布地图。这种分工让制作保持高效，同时由宿主页面负责转化、无障碍和发布纪律。

使用 Kaleidr Studio 发布地图

将地图创建、审核并部署为独立页面或可嵌入小组件，然后在宿主网站需要的位置挂载已发布的 Viewer。打开 Kaleidr Studio 进行发布，并使用开发者文档了解 Viewer 分享 ID、允许域名和 SDK 挂载。

常见问题

什么是地图发布？

地图发布是将可编辑地图转化为一种稳定体验，使其他人可以打开、嵌入或在产品中使用，并提供访问、布局、版本和衡量控制。

分享链接和嵌入有何区别？

分享链接将已发布地图作为独立页面打开；嵌入则把该地图放入宿主网站或产品布局中。

什么时候应使用产品集成而非嵌入？

当筛选器、选中记录或工作流状态必须与地图保持同步，而不是只围绕独立 Viewer 显示时。

Kaleidr Viewer 需要 API 密钥吗？

当前 Viewer 文档称已发布地图由分享链接而非 API 密钥控制。访问模型可能发展变化，因此部署前请查看最新开发者文档。

分享 ID 与 API 密钥相同吗？

不同。分享 ID 标识已发布地图体验。服务器 API 密钥授权特权 API 操作，必须保密。

应该延迟加载地图嵌入吗？

如果地图位于首屏以下或是次要内容，通常应该。如果地图是主要交互，则应作为关键体验加载，并优化其启动过程。

如何让 iframe 地图具有无障碍性？

为原始 iframe 提供简洁的 title，提供有用的周边 HTML，支持键盘可访问任务，并提供无需拖动地图即可读取的文本信息。

两个跨来源页面能否与嵌入地图通信？

如果集成支持，则可以。window.postMessage() 提供受控的跨来源消息通信。使用具体目标来源，并验证传入消息的来源。

能否通过地图嵌入发布私有业务数据？

只有在发布和授权架构专为该用例设计时才可以。受登录保护的宿主页面不会自动让可独立访问的地图 URL 变为私有。

已发布地图应该有版本管理吗？

如果变更可能影响客户、嵌入、报告或业务工作流，则应该。版本管理可以让回滚和调试安全得多。

Kaleidr Studio 可以无代码发布地图吗？

可以。Kaleidr 当前的 Studio 页面表示，作者可以直观地创建和完善地图，然后将其发布为独立页面或可嵌入小组件。

参考资料

Kaleidr. Design Custom Maps, Powered by Spatial AI. Kaleidr Studio. 访问日期：2026年8月19日。 https://kaleidr.com/studio
Kaleidr. kaleidr.js Loader. Kaleidr Developer Documentation. 访问日期：2026年8月19日。 https://docs.kaleidr.com/sdk/kaleidr-js
Kaleidr. Viewer Embed. Kaleidr Developer Documentation. 访问日期：2026年8月19日。 https://docs.kaleidr.com/sdk/viewer-embed
WHATWG. HTML Standard — Lazy loading attributes. 访问日期：2026年8月19日。 https://html.spec.whatwg.org/multipage/urls-and-fetching.html#lazy-loading-attributes
WHATWG. HTML Standard — The iframe element. 访问日期：2026年8月19日。 https://html.spec.whatwg.org/multipage/iframe-embed-object.html#the-iframe-element
W3C. Understanding Success Criterion 4.1.2: Name, Role, Value. WCAG 2.2. 访问日期：2026年8月19日。 https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html
WHATWG. HTML Standard — Posting messages. 访问日期：2026年8月19日。 https://html.spec.whatwg.org/multipage/web-messaging.html#posting-messages
web.dev. Lazy load images and iframe elements. 访问日期：2026年8月19日。 https://web.dev/learn/performance/lazy-load-images-and-iframe-elements

@misc{kaleidr_studio_publish_2026,
  title  = {Design Custom Maps, Powered by Spatial AI},
  author = {{Kaleidr}},
  note   = {Kaleidr Studio; accessed 19 August 2026},
  url    = {https://kaleidr.com/studio}
}

@misc{kaleidr_viewer_embed_2026,
  title  = {Viewer Embed},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Documentation; accessed 19 August 2026},
  url    = {https://docs.kaleidr.com/sdk/viewer-embed}
}

@misc{kaleidr_js_loader_2026,
  title  = {kaleidr.js Loader},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Documentation; accessed 19 August 2026},
  url    = {https://docs.kaleidr.com/sdk/kaleidr-js}
}

@misc{whatwg_iframe_2026,
  title  = {HTML Standard -- The iframe element},
  author = {{WHATWG}},
  note   = {Accessed 19 August 2026},
  url    = {https://html.spec.whatwg.org/multipage/iframe-embed-object.html#the-iframe-element}
}

@misc{wcag_412_2026,
  title  = {Understanding Success Criterion 4.1.2: Name, Role, Value},
  author = {{W3C}},
  note   = {WCAG 2.2; accessed 19 August 2026},
  url    = {https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html}
}

@misc{whatwg_lazy_loading_2026,
  title  = {HTML Standard -- Lazy loading attributes},
  author = {{WHATWG}},
  note   = {Accessed 19 August 2026},
  url    = {https://html.spec.whatwg.org/multipage/urls-and-fetching.html#lazy-loading-attributes}
}

@misc{whatwg_postmessage_2026,
  title  = {HTML Standard -- Posting messages},
  author = {{WHATWG}},
  note   = {Accessed 19 August 2026},
  url    = {https://html.spec.whatwg.org/multipage/web-messaging.html#posting-messages}
}

@misc{webdev_lazy_iframe_2026,
  title  = {Lazy load images and iframe elements},
  author = {{web.dev}},
  note   = {Accessed 19 August 2026},
  url    = {https://web.dev/learn/performance/lazy-load-images-and-iframe-elements}
}