name	minemap-global-configuration
description	MineMap 全局配置、key/solution、域名地址、sprite/fonts、minemapCDN 与启动前配置顺序。用于指导用户正确完成地图初始化前的配置，不再把 accessToken 作为主推荐路径。

MineMap Global Configuration

Quick Start

// 先配全局，再创建第一个 Map
minemap.domainUrl = "https://minedata.cn";
minemap.dataDomainUrl = "https://minedata.cn";
minemap.serverDomainUrl = "https://minedata.cn";
minemap.spriteUrl = "https://minedata.cn/minemapapi/sprite/latest/sprite";
minemap.serviceUrl = "https://minedata.cn/service/";

minemap.key = "<替换成你的 key>";
minemap.solution = 11001;
window.minemapCDN = "https://minedata.cn/minemapapi/minemap-CDN";

const style = {
	version: 8,
	glyphs: "minemap://fonts/{fontstack}/{range}",
	sprite: "minemap://sprite/sprite",
	sources: {},
	layers: []
};

const map = new minemap.Map({
	container: "map",
	style,
	center: [116.46, 39.92],
	zoom: 12
});

Architecture Positioning

1) 这些不是普通变量，而是 `source/index.js` 暴露的全局配置入口

MineMap 把一批启动配置直接挂在 minemap 顶层对象上。

当前源码能确认的主要入口有：

minemap.key
minemap.solution
minemap.domainUrl
minemap.dataDomainUrl
minemap.serverDomainUrl
minemap.serviceUrl
minemap.spriteUrl
minemap.fontsUrl
minemap.dataVersion

兼容入口仍然存在，但不再作为主推荐：

minemap.appKey
minemap.accessToken

另外，很多 3D / worker 相关 demo 还会显式设置：

window.minemapCDN

2) 推荐顺序：`key` + `solution`，不要再把 `accessToken` 当主方案

source/util/urlTransformUtil.js 的真实优先级是：

先用 key
没有 key 再用 appKey
再没有才退到 accessToken

也就是：key > appKey > accessToken

而仓库里的 demo，绝大多数也都在顶部配置：

minemap.key = ...
minemap.solution = ...

因此这套 skill 的推荐是：

新代码优先配置 key
有底图样式、平台方案时同时配置 solution
appKey 只作为兼容或某些旧服务/显式 URL 场景的补充
不再把 accessToken 作为默认推荐写法

3) 为什么一定要在创建 `Map` 之前配置

这些全局值会参与 MineMap 内部的 URL 组装、样式资源解析和服务请求拼接。

如果先 new minemap.Map(...)，再去补这些配置，常见后果是：

首批样式或数据请求已经发出
sprite / glyphs 已按旧配置解析
worker / 3D 资源已经按默认地址去拉取

所以正确顺序是：

先配全局
再创建 Map
再进入 load / style.load 后续逻辑

4) 各配置项的真实作用边界

`minemap.key`

主推荐鉴权参数。MineMap 在内部拼装 URL 时，会优先把它写成 key=...。

`minemap.solution`

方案 ID。内部会按 solu=... 拼进请求参数。只要你的底图、样式、服务能力和某个方案绑定，就应该一起配。

`minemap.domainUrl`

静态资源根域配置。source/index.js 的 setter 不只是简单赋值，还会联动重算：

SRC_URL
SERVICE_URL

而且它会把传入地址拆成“域名 + 资源前缀”两部分，所以它既可以接纯域名，也能接带资源路径的地址。

`minemap.dataDomainUrl`

数据域配置。setter 会联动更新：

API_URL
DYN_URL
MERGE_URL
OTHER_URL

源码支持字符串，也支持数组。

适合：

切到私有化数据域
多数据域分流

`minemap.serverDomainUrl`

分析/服务域配置。setter 会联动更新 SERVER_URL，同样支持字符串或数组。

`minemap.serviceUrl`

直接覆盖服务根地址。很多 demo 都显式设置它，用来明确 style / service 请求走哪个服务域。

`minemap.spriteUrl`

雪碧图覆盖地址。source/style/loadSprite.js 表明，它会和 style 里的 sprite 一起参与解析，而且配置项优先级很高。

源码还支持：

字符串
数组

数组模式可用于多 sprite 源。

`minemap.fontsUrl`

字形资源覆盖地址。不是每个 demo 都配，但源码和 VectorMap2.1.html 表明这是合法入口，适合旧字体服务或私有字体服务迁移。

`minemap.dataVersion`

内部会转成请求参数 version=...。适合和数据发布版本联动。

`window.minemapCDN`

这不是 minemap 顶层 getter/setter，但对 3D / worker 资源非常关键。

源码里 loaders.gl worker 和 CDN 选项都会读取它。没配时，很多 3D demo 的 worker 资源路径就不稳定。

Common Patterns

最常见的 demo 启动模板

仓库里大量 demo 都是这一段结构：

minemap.domainUrl = "https://minedata.cn";
minemap.dataDomainUrl = "https://minedata.cn";
minemap.serverDomainUrl = "https://minedata.cn";
minemap.spriteUrl = "https://minedata.cn/minemapapi/sprite/latest/sprite";
minemap.serviceUrl = "https://minedata.cn/service/";
minemap.key = "...";
minemap.solution = 11001;
window.minemapCDN = "https://minedata.cn/minemapapi/minemap-CDN";

如果你是不知道“到底要配哪些字段”，先按这个最小模板起步，通常最稳。

纯 2D / 空底图场景

如果你自己传的是空 style：

const style = {
	version: 8,
	glyphs: "minemap://fonts/{fontstack}/{range}",
	sprite: "minemap://sprite/sprite",
	sources: {},
	layers: []
};

那通常还是建议把下面几项先配好：

key
solution
domainUrl
dataDomainUrl
serverDomainUrl
spriteUrl

因为后面你很可能还是会加 source、layer、image、scene component。

3D / 模型 / 3D Tiles 场景

只要页面里有：

3d-model
3d-tiles
loaders.gl worker
部分高阶 3D 资源解析

就建议把 window.minemapCDN 一起配上。

这是 3D demo 中最常见的补充项之一。

多 sprite 源

VectorGeojsonOverlap.html 证明 minemap.spriteUrl 可以直接给数组：

minemap.spriteUrl = ["https://host-a/sprite/sprite", "https://host-b/sprite/sprite"];

适合：

多风格 icon 合并
迁移阶段同时挂旧 sprite 和新 sprite

字体服务覆盖

VectorMap2.1.html 证明可以单独配置：

minemap.fontsUrl = "https://your-host/fonts";

适合：

历史项目字体兼容
私有化字体服务
版本迁移时的 glyphs 定位修正

从 demo 里找配置的正确姿势

用户最容易卡住的，其实不是 Map 参数，而是“前面那段全局配置到底怎么写”。

建议直接看 demo 页面最上方的初始化段，通常就在创建 Map 之前。

优先参考这些页面：

demo/html/3DTiles.html
demo/html/3DTilesLoaded.html
demo/html/3DModelViewer.html
demo/html/ExtrusionLightStripScanning.html
demo/html/VectorMap2.1.html
demo/html/3DTilesOpacity.html

观察重点不是抄整页代码，而是看这几个字段：

domainUrl
dataDomainUrl
serverDomainUrl
spriteUrl
serviceUrl
key
solution
window.minemapCDN

关于 demo 里的 key

仓库里有两种情况：

有些 demo 带了可运行示例 key
有些 demo 明确写成 <您的 key> / <your key> 占位

正确理解是：

demo 顶部那段配置可以当“字段模板”
占位 key 必须自己替换
带示例 key 的页面可用于本地理解配置结构，但正式项目不要依赖仓库示例值

Failure Cases

1) 先 `new Map()`，后补全局配置

这是最常见错误。

MineMap 的资源 URL 和样式资源解析很多都是启动早期就发生的。后补配置，通常来不及。

2) 还在把 `accessToken` 当主推荐方案

源码虽然还保留 accessToken，但当前真实优先级已经是：

key
appKey
accessToken

而且当前 demo 主流也不是这么写。

所以不要再把它当主教程入口。

3) 只配 `domainUrl`，不配 `dataDomainUrl` / `serverDomainUrl`

在私有化、分域部署、服务域拆分场景里，这会导致：

样式资源和数据资源不在同一套地址
某些请求走对了，某些请求还在走默认域

4) 3D 场景忘了 `window.minemapCDN`

很多 2D 页面不一定会立刻暴露这个问题，但 3D / worker 相关场景非常容易踩坑。

5) `spriteUrl` 和 style 内 `sprite` 配置混着改，却不知道谁生效

loadSprite.js 的逻辑说明：全局 minemap.spriteUrl 会介入 sprite 解析。

如果你全局已覆盖，就不要一边指望 style 里的 sprite 生效，一边再全局强覆盖，最后自己也分不清实际请求地址。

6) 在顶层全局配置里优先用 `appKey`

appKey 不是不能用，但它更适合：

历史项目兼容
某些手工拼接服务 URL 的场景
demo 中少数旧页面

主配置入口还是优先 key。

Recommended Startup Recipe

如果你要给别人一段“先跑起来”的 MineMap 配置模板，优先给这套：

minemap.domainUrl = "https://minedata.cn";
minemap.dataDomainUrl = "https://minedata.cn";
minemap.serverDomainUrl = "https://minedata.cn";
minemap.spriteUrl = "https://minedata.cn/minemapapi/sprite/latest/sprite";
minemap.serviceUrl = "https://minedata.cn/service/";
minemap.key = "<你的 key>";
minemap.solution = 11001;
window.minemapCDN = "https://minedata.cn/minemapapi/minemap-CDN";

然后再根据项目情况增量调整：

私有字体服务 → fontsUrl
多数据域 → dataDomainUrl 数组
多 sprite → spriteUrl 数组
数据版本控制 → dataVersion

Demo References

demo/html/3DTiles.html
demo/html/3DTilesLoaded.html
demo/html/3DTilesOpacity.html
demo/html/3DModelViewer.html
demo/html/ExtrusionLightStripScanning.html
demo/html/VectorGeojsonOverlap.html
demo/html/VectorMap2.1.html

minemap-global-configuration

このリポジトリの他の Skills

このリポジトリの他の Skills