1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | remotion-maps-remotion-dev-skills |
| 作者/维护者 | Remotion（remotion-dev 官方团队，视频框架 Remotion 的所有者） |
| 来源链接 | https://github.com/remotion-dev/skills/tree/main/skills/remotion-maps |
| 许可证 | Remotion License（个人开发者、≤3 人营利组织、非营利组织、评估阶段可免费；超出范围需购买公司许可证），GitHub API 未能自动识别为标准 SPDX 许可证，已直接读取主仓库 remotion-dev/remotion 的 LICENSE.md 确认条款 |
| GitHub Stars | 4,206（合集仓库 remotion-dev/skills 整体数字，来自 GitHub API；该数字属整个技能合集，不代表本技能自身热度） |
| Forks | 484（同上，合集整体） |
| 最新版本 | 4.0.506（SKILL.md frontmatter 标注，随 Remotion 框架版本同步发布） |
| 安装方式 | 见第 10 章 |
2. 功能介绍与亮点
remotion-maps 是官方针对“如何在 Remotion 视频里做出可用的地图动画”整理的技法知识库，核心设计是一个技法选择器：先判断镜头需要的效果，从 5 套自包含技法中选 1 个，其余技法可整体忽略而不影响已选技法运行。
- 静态地图：把卫星图/地图截图当
<Img>素材，用 Remotion 自身插值函数叠加缩放平移动画，零第三方依赖。 - Mapbox：视觉效果最完整的技法，支持缩小时的球形地球与 3D 建筑实体（如埃菲尔铁塔），需自备 API token。
- MapLibre：Mapbox 的开源平替，近期更新后已完全不需要 API token，可零成本复现基础地图动画，但不支持 3D 建筑。
- MapTiler：擅长在国界、河流、地名等地理要素上叠加自定义标注。
- CesiumJS：面向真实地形的“飞行模拟器”式镜头，可做山脉/地形飞越。
每套技法都附有可直接复制的完整 React/TS 组件（例如一份约 180 行的路线动画组件，内含 Turf.js 地理计算、GeoJSON 数据源管理与逐帧相机控制），并记录了实测踩过的坑，例如“不要给地图实例加清理函数，会打断 Remotion 的渲染生命周期”、“跨越国际日期变更线的路线数据会变成 MultiLineString 需特殊处理”。仓库最近一次提交在 2026-08-04，与 Remotion 核心框架保持同步维护。
3. 适用场景
所属分类：内容创作与知识管理（产出物是嵌入视频作品的地图动画片段，服务于程序化视频内容创作这一实践，与同仓库其余专注字幕、动效标记、可视化编辑等环节的姊妹技能同属一类；经 --neighbors 检索，36 条功能相近的历史记录中 21 条落在本分类，含同仓库的 remotion-best-practices）。
程序化视频创作者需要在作品中插入地图动画镜头时可直接套用——例如旅游/航空品牌制作路线宣传片段、数据记者在新闻视频里可视化某事件的地理传播范围、本地生活账号展示门店分布的城市飞越镜头。受益人群主要是使用 Remotion 做视频的前端/内容团队与独立视频创作者。
4. 跨 Agent 兼容性
| Agent 生态 | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 仓库官方文档将 Claude Code 列为受支持 agent，技能以 /remotion-maps 斜杠命令触发，遵循标准 SKILL.md 格式 |
| Codex | 原生支持 | 官方文档同样列出 Codex，可通过同一套 npx skills add 安装 |
| OpenClaw | 未验证 | 已抓取材料（官方文档、README、SKILL.md）未提及 OpenClaw |
| Hermes Agent | 未验证 | 已抓取材料未提及 Hermes Agent |
5. 推荐理由
地图动画看似只是“加一张地图”，实际涉及地理坐标系、逐帧相机插值、第三方地图 SDK 生命周期等专业细节，新手容易在 Mapbox/CesiumJS 这类重量级库上反复踩坑。remotion-maps 由 Remotion 官方亲自维护，把 5 种可选技法的完整可运行代码与真实踩坑记录直接交给使用者，其中 MapLibre 技法已做到零 API token 即可用，免去了“先申请 key 再试错”的门槛。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | Remotion 官方出品；第三方平台 skills.sh 记录该子技能上线约 12 天内已获 1.41 万次独立安装，是具体到本技能自身的采用证据；所属仓库整体 4,206 星属整个合集，不代表本技能自身热度 |
| 可用性 | 9 | SKILL.md 结构完整，5 套技法各自独立成文并附可运行完整代码与实测踩坑记录；仓库近 1 天内（2026-08-04）有提交，维护频繁；至少一条技法路径（MapLibre）完全免费、无需任何 API key |
| 安全性 | 8 | 见下方检查清单，主要扣分点是第三方扫描工具在其中一套技法中标记的中等风险缺陷 |
安全检查清单：
① 是否执行 shell 命令：不涉及，技能本身是文档与可复制的组件代码，不引导执行 shell 命令
② 运行时是否联网外发数据：地图渲染需联网加载瓦片/脚本资源（Mapbox/MapLibre/MapTiler 瓦片服务、CesiumJS 官方 CDN），用途透明，均为地图内容本身
③ 是否要求 API key/凭据：Mapbox、MapTiler 技法需自备 API key 并通过环境变量存储（如 REMOTION_MAPBOX_TOKEN），文档说明清楚；MapLibre 技法完全无需任何凭据
④ 可疑指令：未发现提示注入或恶意指令；第三方安全扫描工具 Snyk 对该技能标记 2 项中等风险，均限于 CesiumJS 技法组件——一是相机路径坐标计算使用了未经校验的第三方输入，二是从 Cesium 官方 CDN 动态加载外部脚本、完整性无法验证；两者均属“输入未清洗/外部依赖未锁定”类安全缺陷而非恶意行为，且只影响 5 套技法中的 CesiumJS 一套，其余 4 套不受影响
⑤ 作者/组织信誉：Remotion 官方团队直接出品，无刷星或造假迹象
⑥ License：Remotion License，条款明确（个人与 ≤3 人营利组织/非营利组织/评估阶段免费，超出范围需购买商业授权）
⑦ 最近维护时间：仓库最近一次提交在近 1 天内，持续活跃维护
7. 跟同类 Skills 相比的优势
| 竞品 | 定位 | 与本技能的差异 |
|---|---|---|
同合集的 remotion-best-practices |
Remotion 项目的通用入门与整体规范，官方建议“不确定用哪个技能时先看这个” | 是覆盖全局的入口技能，未展开地图渲染这一细分场景的具体做法；remotion-maps 专注该单一需求，给出 5 套可直接套用的技法与代码 |
同合集的 remotion-markup |
覆盖动画驱动、媒体元素、字幕、3D、地图等几乎全部视频创作场景的综合写法指南 | 是广度优先的全场景参考手册，地图部分只是其中一节；remotion-maps 是该主题的深度展开版，每种地图技法独立成文并附完整组件与已知坑点 |
社区维护的 manalkaff/remotion-prompts 中的 maps-animation 提示词 |
面向 Remotion 的第三方提示词集合，只提供一段生成提示语，不含技法选择或坑点记录 | 由框架原厂维护、随版本同步更新，提供 5 种技法的对比选择与实测踩坑经验，而非单一提示词 |
8. 用户评价
该技能目前在 skills.sh 平台尚无具名用户评价或评分记录。
9. 其他补充
remotion-maps 与同仓库的 remotion-markup（动画与媒体写法）、remotion-best-practices（项目整体规范）等技能相互引用、职责分工明确，是一套架构统一、持续演进的官方技能矩阵的组成部分。
10. 安装使用方式
- 方式一（推荐）：手动复制 —— 从
remotion-dev/skills仓库下载/克隆skills/remotion-maps/整个目录（含 SKILL.md 与 5 个techniques/*/TECHNIQUE.md子目录），复制进 Claude Code / Codex 的技能目录（如.claude/skills/remotion-maps/） - 方式二：官方一键安装 —— 运行
npx skills add remotion-dev/skills安装整套 Remotion 技能合集（含本技能），或新建项目时运行bun create video按提示选择安装 - 安装后注意事项：安装后无需重启 agent；对话中提出地图动画需求时会自动匹配，也可用
/remotion-maps显式唤起；技能会先引导选择上述 5 种技法之一，再加载对应techniques/<name>/TECHNIQUE.md；使用前需已有可运行的 Remotion 项目环境（Node.js + Remotion 依赖）；选用 Mapbox 或 MapTiler 技法需自行申请 API key 并配置对应环境变量，选用 MapLibre 技法则无需任何凭据
11. 注意事项
- 第三方安全扫描工具 Snyk 标记 CesiumJS 技法组件存在 2 项中等风险（未校验的第三方路径输入影响相机坐标计算；从 CDN 动态加载外部脚本完整性未经验证），只影响选用该技法的用户，其余 4 套技法不受影响
- Remotion License 为个人/小型团体免费、达一定规模的商业机构需付费授权的双层许可，企业用户使用前应自行核实是否需要购买商业授权
- 官方一键安装命令
npx skills add所依赖的第三方安装器vercel-labs/skills存在两个尚未修复的公开 issue，分别指控其在未明确告知的情况下上传使用数据、以及审计上报机制不完全受禁用开关约束；选择该安装路径的用户可改用上文的手动复制方式规避此风险 - 合集仓库整体 4,206 星与 484 forks 属整个 remotion-dev/skills 技能矩阵，不代表本技能自身的独立采用热度
- Mapbox 与 MapTiler 技法涉及第三方商用 API，存在使用限额或付费门槛，预算有限的用户可优先尝试 MapLibre 技法