Immich 自定义地图样式完全指南:MapLibre 风格文档与 MapTiler 实操
Immich 自定义地图样式完全指南:MapLibre 风格文档与 MapTiler 实操
Immich 内置的地图视图使用 MapLibre 渲染,而决定地图长相的正是那份 style.json 样式文档。本文基于 Immich 官方指南 Custom Map Styles 展开,讲清楚如何通过管理后台替换明/暗两套地图样式 URL、如何理解服务端默认值与暴露链路,以及如何借助 MapTiler 在线编辑器零手写 JSON 地发布一套属于自己的地图样式,读完后你可以为自己的 Immich 实例换上符合主题审美的瓦片源与图层。
为什么可以自定义地图样式
Immich 的地图渲染遵循 MapLibre 生态的通用约定:地图外观不写死在客户端代码里,而是由一份可远程加载的 style.json(MapLibre 样式文档)驱动。这带来两个直接收益:
- 视觉定制:颜色、字体、可见图层、标注风格都可以按个人偏好调整;
- 瓦片源切换:样式文档中的
sources字段指向瓦片提供方,因此换样式等价于可以更换底图瓦片供应商,而不必使用 Immich 默认的瓦片源。
从源码看,Web 端的地图组件 Map.svelte 基于 maplibre-gl 实现,并额外注册了 pmtiles 协议的瓦片源(Protocol + addProtocol('pmtiles', protocol.tile)),也就是说除了标准 XYZ/Vector 瓦片 URL 外,MapLibre 样式中声明的 PMTiles 源同样可用。
默认样式有两个官方地址,分别对应亮色与暗色主题:
亮色主题: https://tiles.immich.cloud/v1/style/light.json
暗色主题: https://tiles.immich.cloud/v1/style/dark.json
它们就是服务端配置中的出厂默认值(见下文源码佐证),可以作为创建自定义样式的起点:下载后修改 layers、colors、sources 再托管到任意可公网访问的静态地址即可。
服务端配置项:map.enabled / lightStyle / darkStyle
自定义样式最终落在服务端系统配置(System Config)的 map 分组下。其 Zod 校验定义位于 config.dto.ts:
map: z
.object({
enabled: configBool.describe('Enabled').meta({ visibility: User }),
lightStyle: z.url().describe('Light map style URL').meta({ visibility: User }),
darkStyle: z.url().describe('Dark map style URL').meta({ visibility: User }),
})
.meta({ id: 'AdminConfigMapDto' }),
三个字段的作用:
| 字段 | 类型 | 说明 |
|---|---|---|
map.enabled |
布尔 | 是否启用地图功能 |
map.lightStyle |
URL | 亮色主题使用的 style.json 地址 |
map.darkStyle |
URL | 暗色主题使用的 style.json 地址 |
注意两点实现细节:
- 两个样式字段都要求合法的 URL(
z.url()),粘贴非法链接会在保存时被校验拒绝; - 它们对普通用户可见(
visibility: User),而管理端修改入口在系统设置中。出厂默认值在 config.dto.ts 中定义为tiles.immich.cloud的 light/dark 两个地址,与上面列出的官方默认样式一致。
服务端再把这两项透传给客户端:server.service.ts 中可以看到 mapDarkStyleUrl: config.map.darkStyle 与 mapLightStyleUrl: config.map.lightStyle 被注入到 serverInfo,于是移动端(server_config.model.dart)与 Web 端读到的就是管理员当前配置的样式地址。
管理后台操作步骤
在 Immich Web 界面中完成替换,官方指南给出的三步流程如下:
- 进入 Administration(管理)→ Settings(设置)→ Map & GPS Settings(地图与 GPS 设置),展开 Map Settings 子区块;
- 将你的
style.json链接分别粘贴到 Light Style 或 Dark Style 输入框。可以只填一个,也可以为亮色/暗色模式各配一套不同风格,让地图随主题切换时视觉更协调; - 保存选择,刷新地图页面即可生效。
对应的管理界面组件是 MapSettings.svelte,其中两个输入框分别双向绑定 configToEdit.map.lightStyle 与 configToEdit.map.darkStyle,并以「当前编辑值 ≠ 已保存值」来判断输入框是否处于已修改状态——这与上面 DTO 定义的两个字段一一对应。
保存后无需重启服务,客户端下次拉取 serverInfo / 刷新地图时会使用新的样式 URL。
用 MapTiler 在线构建自定义样式
如果不想手写整份 JSON,可以用 MapTiler 的可视化编辑器(MapTiler 云平台,注册免费账号)完成定制。官方指南给出的完整流程:
- 在 MapTiler 创建免费账号;
- 登录后有两种方式起步:点击 New Map 选择一个 starter map 再点 Customize,或者直接选一张 Standard Map 进入定制;
- 编辑器(composer)操作直观:可以改颜色、移除可见图层、添加可选图层(如行政区划 administrative、地形 topo、水系 hydro 等);
- 编辑完成后点击右上角 Save,起一个唯一的名称保存到你的账号;
- 点击 Publish 发布到生产环境——发布后样式即可通过 Internet 暴露访问。发布前 MapTiler 会展示一个「原版 vs 你的修改」的并排对比地图供确认:
- MapTiler 会提示:修改地图会影响所有正在使用该地图的应用。由于此前还没有任何应用引用它,此时发布没有副作用;
- 点击左上角新地图的名称进入详情(details)页,在 Use vector style 下方复制 JSON 样式的链接——该链接会自动携带你的个人 API Key,可直接粘贴进 Immich 的 Light Style / Dark Style。
拿到链接后,按上一节的三步粘贴到管理后台并保存即可。
选型与注意事项
- 样式 URL 必须公网可达:
lightStyle/darkStyle走z.url()校验并由浏览器直接加载,若你自托管样式文件,需要保证客户端能访问该地址; - 明暗各配一套更合理:Immich 主题切换时地图会跟随切换样式源,两套风格统一(例如都基于同一 starter map 调整配色)体验最好;
- API Key 会随链接分发:使用 MapTiler 这类「链接自带密钥」的方案时,请注意该链接会出现在客户端获取的 serverInfo 中,仅建议在内网或可信客户端范围内使用;
- 可换任意瓦片源:原理上任何符合 MapLibre 样式规范的
style.json都可用,包括其他开源瓦片服务商发布的样式,替换sources即可换底图。
小结
Immich 的地图样式定制是「配置驱动」而非「代码驱动」的:管理员只需在系统设置的 Map Settings 中替换 map.lightStyle / map.darkStyle 两个 URL(定义见 config.dto.ts,透传见 server.service.ts),客户端的 MapLibre 渲染器(Map.svelte)会自动加载新样式;而 MapTiler 的 New Map → Customize → Save → Publish → 复制 Use vector style 链接流程,提供了不写一行 JSON 即可产出可用样式文档的完整路径。
