Remotion 地图渲染稳定性：用"固定地图画板"消除 MapTiler / Mapbox 平移缩放闪烁

本文是 Remotion 地图类技能库（remotion-maps）中 MapTiler / Mapbox 2D 地图制作必须掌握的渲染稳定性参考。核心场景是：你在 Remotion 合成中让一张带卫星影像、矢量山体阴影或高保真底图的地图做平移与缩放，却发现渲染出的画面中底图细节逐帧"闪烁"或"抖动"。读完本文你将掌握：抖动根因的判别方法、"固定地图画板（Fixed Map Plate）"模式的完整实现与 CSS 变换数学、画板尺寸与清晰度的取舍规则，以及一套可复现的最终验证流程，从而产出真正稳定的移动地图动画。

症状与根因：逐帧 map.jumpTo() 是抖动来源

如果在平移动画（pan）或缩放动画（zoom）过程中，底图细节出现"微光闪烁（shimmer）"或"抖动（jitter）"，最可能的原因是每一帧都在调用 map.jumpTo()。

在无头（headless）渲染环境下，MapTiler 的捕获流程可能逐帧以不同方式对矢量山体阴影（vector hillshade）与卫星影像进行重采样——即使瓦片本身加载完全正常。这属于渲染器（renderer）自身的重采样效应，而不是数据、网络或图层标签的问题。因此在动手排查时应当明确：

• 调整瓦片重试（tile retries）不能解决；
• 修改缓动曲线（easing）不能解决；
• 更换标注（label）不能解决。

这一点在技能库的多份文档中被反复强调：MapTiler 技巧页的 "Motion stability" 一节明确要求"地图相机移动时不要在每一帧调用 map.jumpTo()"；Mapbox 技巧页的核心规则也要求在逐帧移动相机前先阅读移动地图稳定性参考，并默认保持相机静态。MapLibre 技巧同样共享该参考文件（maplibre 版本）。简言之，动态相机只适合静态镜头；只要镜头在动，就应该采用下面的固定画板模式。

核心模式：固定地图画板（Fixed Map Plate）

所谓固定地图画板，思路是：让地图渲染器（renderer）的相机永远保持冻结，把所有相机运动转化为对一整块预先渲染好的超大 HTML 画布的 CSS 变换。对任何 2D 平移 / 缩放镜头，遵循以下五步：

1. 一次性地在地图所需的最大 zoom 级别下，把 MapTiler 画布渲染进一个超大尺寸的容器中。画布尺寸要依据相机路径推算，且每个维度都要低于浏览器可靠的 WebGL 渲染缓冲上限（常见为 4096 px）。不要盲目使用 3× 系数：1920×1080 的合成乘 3 会变成 5760 px 宽，Chromium 可能静默降采样，导致 CSS 缩放时出现可见的像素化。
2. 保持地图相机（center / zoom）静态。
3. 在每一帧，根据已确认的插值目标（center / zoom）计算平移量，然后用 CSS translate + scale 移动画布。
4. 把完全相同的变换施加到每一个投影后的 HTML 覆盖层（标注、标签等）。
5. 继续用命令式方式（imperatively）驱动 GeoJSON 数据与 paint 属性的动画；只有渲染器相机是被冻结的。

注意 pitch 与 bearing 必须保持恒定。如果你需要真正的变 pitch / bearing 镜头或地形穿越（terrain flythrough），应改用 3D 引擎（技能库中的 Cesium 技巧 即为此设计），固定画板是纯 2D 方案。

画板变换的代码实现与数学原理

底层变换非常简单：经纬度坐标经过墨卡托投影后，zoom 每增加 1，屏幕距离翻一倍。于是给定基准 zoom（画板渲染时的 zoom）与当前帧的目标 zoom，CSS 缩放系数就是：

const scale = 2 ** (camera.zoom - baseZoom);

只要 camera.zoom <= baseZoom，scale <= 1，意味着画板只会被缩小而不会被放大，清晰度就有保证。参考文档给出的完整示例实现如下：

const baseZoom = Math.max(start.zoom, end.zoom);
const map = new maptilersdk.Map({
  container,
  style,
  center: end.center,
  zoom: baseZoom,
  pitch: end.pitch ?? 0,
  bearing: end.bearing ?? 0,
  interactive: false,
  fadeDuration: 0,
  canvasContextAttributes: {preserveDrawingBuffer: true},
});

// Per Remotion frame. `camera` is the approved centre/zoom interpolation.
const projected = map.project(camera.center);
const scale = 2 ** (camera.zoom - baseZoom);
const plate = {
  transform: `translate(${width / 2 - projected.x * scale}px, ${height / 2 - projected.y * scale}px) scale(${scale})`,
  transformOrigin: "0 0",
};

// Convert label projection with exactly the same plate transform.
const labelX = labelPoint.x * scale + width / 2 - projected.x * scale;
const labelY = labelPoint.y * scale + height / 2 - projected.y * scale;

代码中的关键点：

• baseZoom = Math.max(start.zoom, end.zoom)：把画板渲染在路径上最高的 zoom，保证缩放过程全部是缩小；
• interactive: false 与 fadeDuration: 0：禁用交互与非确定性行为（Mapbox 技巧页同样要求关闭这两项）；
• preserveDrawingBuffer: true：保证 Remotion 的截图能捕获到 WebGL 画布内容；
• map.project(camera.center) 返回当前冻结相机下该经纬度在画布内的像素坐标，projected.x * scale 是它在最终画面坐标系中的偏移；
• 变换的几何含义：先把画板平移，使目标中心点恰好落在画面中心 (width/2, height/2)，再以画板左上角（transformOrigin: "0 0"）为原点做缩放。

这套模式在技能库的示例组件 RiverReveal.tsx 中有可对照的真实实现：它用 lerp(START.zoom, END.zoom, tt) 得到当前帧相机，随后

const cameraPoint = map.project(camera.center);
const plateScale = 2 ** (camera.zoom - Math.max(START.zoom, END.zoom));
const plateX = width / 2 - cameraPoint.x * plateScale;
const plateY = height / 2 - cameraPoint.y * plateScale;

并把结果写入 React state，最终渲染在叠加层容器上：

<div
  ref={ref}
  style={{
    width: width * 2,
    height: height * 2,
    position: 'absolute',
    transform: `translate(${plate.x}px, ${plate.y}px) scale(${plate.scale})`,
    transformOrigin: '0 0',
  }}
/>

该容器按 width * 2、height * 2 初始化（对 1080p 即 3840×2160），与参考文档建议的安全默认值一致。整个渲染流程的时序在 map-explainer-architecture.md 中有完整描述：地图只初始化一次（ref guard），load 后添加数据源与图层并等待 once('idle') → continueRender；每一帧则走 delayRender → setData/setPaintProperty → map.once('idle', continueRender) → triggerRepaint，其中 triggerRepaint() 的作用是即使相机参数与上一帧完全相同，也强制触发一次 idle 事件，避免渲染被挂死。

HTML 覆盖层（标注 / 标签）如何与画板同步移动

地图上的标注如果做成 DOM/Marker，会脱离冻结的相机、导致"标注漂移"。技能库的推荐做法是：标注是 React HTML 覆盖层（而非地图 symbol），每一帧用 map.project(anchor) 把锚点经纬度投影成屏幕像素，再套用与画板完全相同的缩放和平移。

在 CountryLabel.tsx 配合的实现中（见 map-explainer-architecture.md），逐帧计算：

const p = map.project(META[c].anchor); // lngLat → screen px（在冻结相机下）
pos[c] = {x: p.x * plateScale + plateX, y: p.y * plateScale + plateY, reveal: lp};

p.x * plateScale + plateX 正是"用与画板完全相同的变换处理标注投影"的具体落地：先把投影像素乘以缩放系数，再加上画板平移量。标签容器整层设置 pointerEvents: none，避免干扰。此例还演示了上升 + 渐显的入场动画、CSS 自定义属性提供字重/字号/字距/字色的中性兜底值，生产项目应使用自己的字体与配色系统替换这些占位值。

画板尺寸与清晰度：在 4096 px 上限内做取舍

画板到底该多大？参考文档给出了明确规则与经验值：

• 按路径上任意相机路点（waypoint）会达到的最大 zoom 渲染，包括中间相机与停留（hold）相机。CSS scale 永远不应超过 1，否则就说明画板在被放大、清晰度会受损。
• 把冻结地图的中心放在相机路径地理范围的中点，而不是自动对准终点相机——这样所需的多余扫描区域（overscan）最小。
• 画板最大边保持在 4096 px 及以下，除非实际渲染环境已经用更大的 MAX_RENDERBUFFER_SIZE 验证过。
• 具体经验值：1920×1080 横屏，3840×2160 的画板是安全默认；1080×1920 竖屏、且路径需要额外横向平移空间时，约 2700×3840。
• 如果路径在所需 zoom 下无法塞进上述画板，就把镜头拆成两块固定画板，中间用一次有意的剪辑过渡（editorial transition）。不要为了少拆镜头而牺牲清晰度去渲染一张巨型画布。

文档还给出了一个非常有价值的排障判别方法：

• 反复出现的闪烁（repeating shimmer） ⇒ 说明实时渲染器（live renderer）的相机在动；
• CSS 推镜过程中瓦片持续偏软（steadily soft tiles） ⇒ 说明固定画板本身规格不足、被内部降采样，或缩放系数超过了 1。

两者成因不同、修法也不同，先判别再动手。

验证清单：如何确认渲染真的稳定

在 Studio 预览里"看起来没问题"远远不够。参考文档要求在交付前完成以下检查：

1. 渲染一段短视频 MP4，而不是只看 Studio 预览——无头渲染的重采样问题只在真实出片中复现；
2. 相机移动过程中检查静态地形纹理与卫星细节是否保持锐利稳定；
3. 只要任何底图细节出现波动，就切换为固定地图画板，不要当作轻微预览瑕疵放行；
4. 校验期间使用保守的渲染参数渲染 WebGL：--gl=angle、preserveDrawingBuffer: true，并将并发度限制为保守值（1）。

Mapbox 技巧页给出了对应的命令形式（Bun 项目用 bunx，npm 项目用 npx）：

bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1

同时要逐分辨率（aspect ratio）检查渲染出的像素而非仅依赖播放器表现。delayRender() / continueRender() 必须在加载地图与每帧地图更新周围正确配对，避免帧内容尚未就绪就被截图。

什么时候可以继续用动态相机

技能库的总体取舍是：

• 静态镜头（相机不动，只做数据动画）：可以用 map.jumpTo() 一次性就位后冻结，例如 Mapbox / MapTiler 基本示例中的做法；
• 2D 平移缩放镜头：一律先读本文，优先使用固定地图画板；
• 仅在渲染短视频 MP4 并确认无闪烁之后，才允许保留逐帧实时相机方案（Mapbox 技巧页的"Camera guidance"为此场景）；即便如此，该 2D 方案也不提供真正的 terrain、pitch、bearing 或 banking 变化。

需要说明的是：本参考文档属于 MapTiler 技巧目录，技能库在 Mapbox 与 MapLibre 目录下各维护了一份同源副本（mapbox 副本、maplibre 副本），三类底层都是 MapLibre 系 GL 引擎，症状、原理与修复模式完全一致，可交叉引用。若镜头需求超出 2D 平移缩放（如改变 pitch/bearing 的飞行镜头、地形穿越），请转向 Cesium 技巧目录。

仓库内的配套资料导航

• MapTiler 技巧主文档 — 相机稳定性规则、图层取舍与最小化清理指引；
• render-stability.md — 本文依据的源文档；
• map-explainer-architecture.md — 渲染时序模型与逐帧 label 投影机制；
• RiverReveal.tsx — 固定画板变换的可运行实现示例；
• CountryLabel.tsx — HTML 覆盖层标注示例；
• MapTilerVectorElement.ts — 供逐帧 paint 更新的 provider 图层配置；
• Mapbox 技巧主文档 — 含动态相机路线动画的完整 jumpTo() 示例与 WebGL 渲染命令；
• remotion-maps 技能总览 — Mapbox / MapLibre / MapTiler / Cesium / 静态图五类地图方案的选型入口。