| name | minemap-global-configuration |
| description | MineMap 全局配置、key/solution、域名地址、sprite/fonts、minemapCDN 与启动前配置顺序。用于指导用户正确完成地图初始化前的配置，不再把 accessToken 作为主推荐路径。 |
MineMap Global Configuration
Quick Start
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.keyminemap.solutionminemap.domainUrlminemap.dataDomainUrlminemap.serverDomainUrlminemap.serviceUrlminemap.spriteUrlminemap.fontsUrlminemap.dataVersion
兼容入口仍然存在，但不再作为主推荐：
minemap.appKeyminemap.accessToken
另外，很多 3D / worker 相关 demo 还会显式设置：
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 不只是简单赋值，还会联动重算：
而且它会把传入地址拆成“域名 + 资源前缀”两部分，所以它既可以接纯域名，也能接带资源路径的地址。
minemap.dataDomainUrl
数据域配置。setter 会联动更新：
API_URLDYN_URLMERGE_URLOTHER_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: []
};
那通常还是建议把下面几项先配好：
keysolutiondomainUrldataDomainUrlserverDomainUrlspriteUrl
因为后面你很可能还是会加 source、layer、image、scene component。
3D / 模型 / 3D Tiles 场景
只要页面里有：
3d-model3d-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.htmldemo/html/3DTilesLoaded.htmldemo/html/3DModelViewer.htmldemo/html/ExtrusionLightStripScanning.htmldemo/html/VectorMap2.1.htmldemo/html/3DTilesOpacity.html
观察重点不是抄整页代码，而是看这几个字段：
domainUrldataDomainUrlserverDomainUrlspriteUrlserviceUrlkeysolutionwindow.minemapCDN
关于 demo 里的 key
仓库里有两种情况：
- 有些 demo 带了可运行示例 key
- 有些 demo 明确写成
<您的 key> / <your key> 占位
正确理解是：
- demo 顶部那段配置可以当“字段模板”
- 占位 key 必须自己替换
- 带示例 key 的页面可用于本地理解配置结构，但正式项目不要依赖仓库示例值
Failure Cases
1) 先 new Map()，后补全局配置
这是最常见错误。
MineMap 的资源 URL 和样式资源解析很多都是启动早期就发生的。后补配置，通常来不及。
2) 还在把 accessToken 当主推荐方案
源码虽然还保留 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.htmldemo/html/3DTilesLoaded.htmldemo/html/3DTilesOpacity.htmldemo/html/3DModelViewer.htmldemo/html/ExtrusionLightStripScanning.htmldemo/html/VectorGeojsonOverlap.htmldemo/html/VectorMap2.1.html
See Also
minemap-fundamentalsminemap-style-systemminemap-style-and-dataminemap-scene-componentsminemap-performance-and-backend
