Immich 自定义地图样式完全指南:MapLibre 风格文档与 MapTiler 实操

原创2026-09-04 16:50:342,543 阅读
文章标签:后端前端移动开发计算机视觉机器学习图像处理音视频Web

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 地址

注意两点实现细节:

  1. 两个样式字段都要求合法的 URL(z.url()),粘贴非法链接会在保存时被校验拒绝;
  2. 它们对普通用户可见(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 界面中完成替换,官方指南给出的三步流程如下:

  1. 进入 Administration(管理)→ Settings(设置)→ Map & GPS Settings(地图与 GPS 设置),展开 Map Settings 子区块;
  2. 将你的 style.json 链接分别粘贴到 Light Style 或 Dark Style 输入框。可以只填一个,也可以为亮色/暗色模式各配一套不同风格,让地图随主题切换时视觉更协调;
  3. 保存选择,刷新地图页面即可生效。

对应的管理界面组件是 MapSettings.svelte,其中两个输入框分别双向绑定 configToEdit.map.lightStyle 与 configToEdit.map.darkStyle,并以「当前编辑值 ≠ 已保存值」来判断输入框是否处于已修改状态——这与上面 DTO 定义的两个字段一一对应。

保存后无需重启服务,客户端下次拉取 serverInfo / 刷新地图时会使用新的样式 URL。

用 MapTiler 在线构建自定义样式

如果不想手写整份 JSON,可以用 MapTiler 的可视化编辑器(MapTiler 云平台,注册免费账号)完成定制。官方指南给出的完整流程:

  1. 在 MapTiler 创建免费账号;
  2. 登录后有两种方式起步:点击 New Map 选择一个 starter map 再点 Customize,或者直接选一张 Standard Map 进入定制;
  3. 编辑器(composer)操作直观:可以改颜色、移除可见图层、添加可选图层(如行政区划 administrative、地形 topo、水系 hydro 等);
  4. 编辑完成后点击右上角 Save,起一个唯一的名称保存到你的账号;
  5. 点击 Publish 发布到生产环境——发布后样式即可通过 Internet 暴露访问。发布前 MapTiler 会展示一个「原版 vs 你的修改」的并排对比地图供确认:

MapTiler 样式发布设置界面

  1. MapTiler 会提示:修改地图会影响所有正在使用该地图的应用。由于此前还没有任何应用引用它,此时发布没有副作用;
  2. 点击左上角新地图的名称进入详情(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 即可产出可用样式文档的完整路径。

登录后查看全文
immich