Mapshaper 基础操作实战：从数据探查、过滤连接到简化、投影与导出的完整配方手册-平芜编程栈

GIS
CLI
数据可视化

【免费下载链接】mapshaper

Tools for editing Shapefile, GeoJSON, TopoJSON and CSV files

项目地址：https://gitcode.com/gh_mirrors/ma/mapshaper

本篇技术指南以 Mapshaper 官方 Basics 示例文档为骨架，汇总了 GIS 日常工作中最常用的一批"短配方"：格式转换、属性连接（join）、简化（simplify）、溶解（dissolve）、投影（projection）、分类着色与 Web 导出等。你读完本文将掌握：在 Mapshaper 命令行与 Web 控制台中快速探查数据集、按条件过滤与聚合、把 CSV 连接到 Shapefile、为 Web 地图生成精简且拓扑正确的 TopoJSON，以及用命令文件（command file）把整套处理流水线参数化、可复现地跑起来。每个配方都附带仓库源码与测试中的实现细节，方便你对照命令参考进一步深挖。

说明：本文示例主要面向 Web 应用的 Console ——先加载数据，再逐条运行下面的命令；文件名、图层名与字段名均为示意，请替换为你自己的数据。命令名统一保留前导-，这种写法在 Web 控制台与 CLI 中都适用，且命令序列在第一条命令之后也需要它。若要在命令行运行大多数示例，只需在命令序列前加上mapshaper input-file、在序列后加上-o output-file。命令与选项的完整语法见命令参考；-each、-filter、calc=等命令所用 JS 表达式的上下文见 JavaScript 表达式指南。

一、数据探查：动手处理前的第一步

打印数据集摘要

-info

-info会打印几何类型、要素数量、CRS（若已知）、包围盒，以及每个属性字段的名称与类型——这是快速回忆"这个文件里到底有什么"的最快方式。CLI 下还可以加save-to=info.json把结果以 JSON 形式落盘，便于脚本消费。从源码看，getLayerInfo()与getAttributeTableInfo()等函数（见 mapshaper-info.mjs）负责拼装这些信息；save-to=选项则会调用文件导出模块写盘。参考文档中-info还支持+（保存为图层，默认名为info）与name=选项（见命令参考）。

在指定图层上运行命令

-info target=counties

命令默认作用于当前选中的图层；用target=指名其他图层，或用target=*让命令作用于每一个图层。target=还接受图层编号（第一个图层为 1）以及逗号分隔的名称/编号列表，名称中可含*通配符（见命令参考的 Common options）。

按字段分组统计要素数

-drop geometry \ -dissolve STATE calc='N = count(), POP = sum(POP)'

"溶解 +calc=子句"是对数据进行聚合的惯用法：这里-drop geometry把结果变成一张纯属性表，可直接导出为 CSV。

二、过滤与选取：只留下你关心的要素

保留满足条件的要素

-filter 'CONTINENT == "Asia" && POP > 1e7'

-filter保留表达式返回true的要素。JS 表达式中this指向当前要素，字段可直接按名引用；this.id是要素的数字 id（从 0 开始）。

过滤时保留原始图层

-filter 'POP > 100000' + name=large_places

+标志把结果存为新图层而非替换当前图层；配合name=给新图层起个有意义的名字。这是 Mapshaper 派生图层的惯用方式（命令参考中+与name=被列为许多命令的通用选项）。

保留包围盒内的要素

-clip bbox=-10,35,30,60

四个 bbox 数值依次为xmin,ymin,xmax,ymax，使用图层自身的坐标系。-clip保留框内部分；想保留框外部分则用-erase bbox=...。

按某属性取前 N 条要素

-sort POP descending \ -filter 'this.id < 50'

-sort POP descending按人口从大到小排序；要素的数字 id 从0开始，因此this.id < 50恰好保留前 50 条。

丢弃空几何要素

-filter remove-empty

remove-empty标志删除几何缺失或为空的要素。类似的remove-empty标志同样出现在-filter-islands、-filter-slivers等命令中，并有对应测试覆盖（如 filter-slivers-test.mjs）。

三、编辑属性字段

添加派生字段

-each 'STATE_FIPS = COUNTY_FIPS.substr(0, 2), AREA_KM2 = round(this.area / 1e6, 1)'

-each对每个要素运行一条 JS 表达式；给裸字段名赋值即创建或更新该字段。round(x, 1)是 Mapshaper 的取整辅助函数（此处保留 1 位小数）。在未投影的经纬度数据上，this.area返回平方米，除以1e6即换算为平方公里。

重命名并筛选字段

-rename-fields POPULATION=POP,MEDIAN_INCOME=MEDIAN_INC \ -filter-fields STATE,COUNTY,POPULATION,MEDIAN_INCOME

-rename-fields接受新名=旧名的成对参数；-filter-fields只保留列出的字段，且按列出顺序排列——非常适合整理 CSV 导出结果。

保留 CSV 中的前导零

string-fields=FIPS,STATEFIPS

Mapshaper 默认会把任何看起来像数字的 CSV 列解析为数值，从而悄悄丢掉 FIPS、ZIP 等标识列的前导零。在 Web 应用中，导入 CSV 时在Advanced options字段里填入string-fields=FIPS,STATEFIPS；在 CLI 中则通过-i传入：mapshaper -i counties.csv string-fields=FIPS,STATEFIPS。string-fields=*可匹配全部字段；测试 delim-import-test.mjs 中专门覆盖了"保护字符串格式数字"与"string-fields=*匹配所有字段"两种场景。

四、数据连接（Join）

按键连接 CSV 与 Shapefile

-join demographics keys=STATE_FIPS,FIPS

运行连接前需同时加载目标图层与 CSV。keys=A,B表示"用目标的A字段匹配源表的B字段"。若源键是 FIPS、ZIP 这类带前导零的代码，请用string-fields=FIPS导入 CSV，让"06"匹配"06"而不是被解析成6。只想从源表取几列时，加fields=FIELD_A,FIELD_B；fields=*复制全部字段，fields=（空列表）则不复制任何字段（命令参考）。

空间连接：为点打上所在多边形的属性

-join precinct_polygons

省略keys=时，-join会根据涉及的几何类型退化为空间连接：上例中每个点继承包含它的多边形的属性。可用fields=PRECINCT_ID,DIVISION只保留指定列。-join的完整选项还包括where=（按条件过滤源记录）、prefix=（给连接字段加前缀）、largest-overlap、min-overlap-pct=、max-distance=（点对点）以及force（允许目标表字段被源表覆盖）等，详见命令参考。

多对一连接 + 聚合

-join crimes calc='N = count(), AVG_SEVERITY = mean(SEVERITY)'

多边形到多点（polygon-to-many-points）的连接可以用calc=把匹配到的多条源记录汇总成每个目标要素上的一个或多个新字段。calc=里可用的函数与-calc相同。

五、简化（Simplification）

为 Web 简化多边形图层

-simplify 5% keep-shapes \ -clean

-simplify 5%使用默认的加权 Visvalingam 算法保留 5% 的原始顶点；keep-shapes防止简化把小多边形整个抹掉；-clean则清理激进简化引入的拓扑错误。TopoJSON 输出通常比同等 GeoJSON 小 2–5 倍：在 Export 对话框选择 TopoJSON，或在 CLI 中用-o format=topojson provinces.topojson。简化算法的实现细节可在 simplify 目录下查看。

多文件共享拓扑简化

-simplify 10%

在 Web 应用导入多个文件时，在Advanced options里加combine-files，Mapshaper 会先把输入合并为一个数据集，再构建弧段拓扑——这样图层间共享的顶点在简化后依然共享，州/县边界不会出现缝隙或重叠。

修复拓扑错误

-clean

-clean会吸附近似重复的顶点、清除多边形之间微小的缝隙与重叠，并修复自相交的线，是任何空间操作前安全的"第一步"。必要时可用gap-width=或snap-interval=微调。

六、聚合（Aggregation）

溶解到父级地理单元

-dissolve STATE

-dissolve把命名字段取值相同的相邻多边形合并为一个。

溶解的同时计算分组统计量

-dissolve STATE calc='N = count(), POP = sum(POP), MEDIAN_INC = median(MEDIAN_INC)'

calc=同样适用于-dissolve。可用的命名函数包括count、sum、mean、median、mode、min、max、quartile1/2/3、iqr、quantile、collect、every、some、first、last，它们与-each共享同一个要素级上下文。

点数据溶解为人口加权质心

-dissolve STATE_FIPS weight=POPULATION

把共享STATE_FIPS值的点分组溶解为每组一个加权质心。weight=接受字段名或 JS 表达式；省略分组字段时，所有点会溶解为一个质心。

七、空间操作

从一个图层中擦除另一图层

-erase lakes

-erase删除目标图层中落在源图层多边形内部的部分，常用于遮掉水域、公园等"不计入"区域。反向操作是-clip（保留内部）。

提取内部边界

-innerlines

-innerlines把多边形之间的共享边界输出为一条线图层，通常用于在样式化地图上给内部边界加描边。想同时保留外边界与内边界，改用-lines。

生成覆盖图层的六边形网格

-grid type=hex interval=10km name=hex

-grid type=hex cols=40 name=hex

-grid生成覆盖目标包围盒的规则网格，支持square、square2、hex、hex2、rhombus、rhombus2、triangle、triangle2、cairo等类型。用interval=直接设定单元边长，或用cols=、rows=、cells=设定近似网格分辨率；cell-scale=可让单元相对中心缩放，rotate=可绕目标包围盒中心旋转。生成的网格可配合空间连接-join interpolate=POPULATION用插值后的计数数据来着色。

合并兼容图层

-merge-layers target=OR,WA,CA,AK name=pacific_states

-merge-layers把几何类型兼容的多个图层合并为一个；若各图层属性字段不一致，加force让 Mapshaper 用空值填充缺失字段。

八、重投影

投影到命名 CRS

-proj robinson

-proj接受 EPSG 编码（EPSG:3857）、PROJ 字符串（+proj=tmerc +lon_0=...）或短别名（wgs84、webmercator、robinson、albersusa）。细节见 Projections 指南。Mapshaper 内置了丰富的投影实现，包括蝴蝶投影、Dymaxion、Lee 四面体投影等自定义投影（见 crs 目录）。

匹配另一文件的投影

-proj match=basemap

match=读取另一图层或.prj文件的 CRS，并把目标投影到与之匹配的坐标系——在组装需要共享同一坐标系统的多个数据集时非常方便。

九、分类与样式

分位数分类到颜色渐变

-classify save-as=fill quantile classes=6 color-scheme=Oranges

-classify把类别索引或派生值（这里是用色值）写入命名字段。默认是顺序分位数分类，也可以切换为equal-interval、nice、categorical或non-adjacent。CLI 下运行mapshaper -colors可列出内置配色方案。

为导出添加 SVG 样式

-style stroke="#444" stroke-width=0.5 fill=none \ -style where='RANK == 0' stroke="#000" stroke-width=1.5

-style把 SVG 呈现属性写到每个要素上；where=形式允许按条件设置样式。准备就绪后导出为 SVG，即可用于印刷或 Web 布局。-style支持的样式值既可以是字面量也可以是 JS 表达式（命令参考）。

十、输出与格式转换

Shapefile 与 GeoJSON 互转

Web 应用点 Export 按钮选择 GeoJSON 或 Shapefile 即可。CLI 下输出格式由文件扩展名推断：

mapshaper input.shp -o input.geojson mapshaper input.geojson -o input.shp

也可用format=强制指定格式（如-o format=topojson out.json）。写出 Shapefile 时，Mapshaper 会同时生成.shp、.shx、.dbf与.prj；若未给出输出文件名，输出文件将沿用目标图层名。

量化 TopoJSON

Web 应用点 Export 按钮选择 TopoJSON。TopoJSON 输出默认启用量化——Mapshaper 会根据数据坐标范围自动选取量化级别。量化把坐标舍入到网格上，从而大幅缩小文件体积；默认级别可用quantization=覆盖（如quantization=1e5）。配合-simplify与 TopoJSON 的共享弧编码，量化输出通常比同等 GeoJSON 小 2–5 倍。

输出为 ndjson

mapshaper big.geojson -o ndjson big.ndjson

换行分隔的 JSON（Newline-delimited JSON）对 jq、BigQuery、DuckDB 这类面向行的工具更友好——每行一个 Feature，没有外层 FeatureCollection。这主要是 CLI 工作流。

按字段切分图层为多个文件

mapshaper counties.shp \ -split STATE \ -o out/ extension=geojson

-split FIELD按字段值把要素切分为独立图层；-o指向目录时每个图层写成一个文件，以字段值命名。这主要是 CLI 工作流。

十一、工作流模式：命令文件与参数化

从文件运行命令链

# build.txt mapshaper -i counties.shp -rename-fields POP=POPULATION -dissolve STATE calc='POP = sum(POP)' -simplify 5% -o out/states.topojson

mapshaper -run build.txt # or simply: mapshaper build.txt

长流水线可以放进命令文件中。命令文件是首行非空、非注释内容以mapshaper开头的.txt文件，支持#注释、无需转义 shell 元字符、接受尾部反斜杠续行（非强制）。这是 CLI 工作流；Web 应用运行命令文件的支持自 v0.7.46 起已加入（见 command-line.md）。

参数化命令文件

mapshaper -vars YEAR=2024 PCT=10 -run build.txt

# build.txt mapshaper -defaults YEAR=2020 PCT=5 -i sources/counties_{{YEAR}}.shp -simplify {{PCT}}% -o out/counties_{{YEAR}}.shp

{{VAR}}占位符在解析时替换。-defaults设置可被调用方用-vars覆盖的默认值（也支持用{{env.NAME}}引用环境变量）。-vars每次调用都会覆盖已有值，而-defaults只在键尚未定义时写入；两种命令还都接受指向含扁平 JSON 对象的文件路径作为变量来源（命令参考）。注意：-vars/-defaults写入模板作用域，{{X}}替换时优先查模板作用域、再回退到表达式作用域；而 JS 表达式（-each、-filter等）中的裸名只能看到表达式作用域，详见 JavaScript 表达式指南。

遇到坏输入时提前终止流水线

mapshaper input.csv \ -calc 'N = count()' \ -if 'global.N == 0' \ -print 'No records, exiting' \ -stop \ -endif \ -o out.csv

-calc表达式可通过简单赋值向global对象发布值；-if/-stop据此保护流水线后续步骤。这适合"上游数据出错时应当响亮失败，而不是静默产出空输出"的脚本场景。-if/-elif/-else/-endif/-stop属于控制流命令，见命令参考的 Control Flow 一节。

处理超大文件时增加堆内存

mapshaper-xl 16gb counties_5m.shp -simplify 10% -o counties_5m.topojson

mapshaper-xl是一个包装脚本，以更大的 Node 堆（默认 8 GB，可传参数覆盖）启动 mapshaper。查看 bin/mapshaper-xl 的源码可见：它会解析首个参数——形如16gb（也接受16g、16）的数字——并把它限制在 1–64 GB 范围内，随后以--max-old-space-size=<GB*1000>重新启动bin/mapshaper可执行文件。遇到 "JavaScript heap out of memory" 错误时就用它。

【免费下载链接】mapshaper

Tools for editing Shapefile, GeoJSON, TopoJSON and CSV files

项目地址：https://gitcode.com/gh_mirrors/ma/mapshaper

点击查看免费下载

【免费下载链接】mapshaper

一、数据探查：动手处理前的第一步

打印数据集摘要

在指定图层上运行命令

按字段分组统计要素数

二、过滤与选取：只留下你关心的要素

保留满足条件的要素

过滤时保留原始图层

保留包围盒内的要素

按某属性取前 N 条要素

丢弃空几何要素

三、编辑属性字段

添加派生字段

重命名并筛选字段

保留 CSV 中的前导零

四、数据连接（Join）

按键连接 CSV 与 Shapefile

空间连接：为点打上所在多边形的属性

多对一连接 + 聚合

五、简化（Simplification）

为 Web 简化多边形图层

多文件共享拓扑简化

修复拓扑错误

六、聚合（Aggregation）

溶解到父级地理单元

溶解的同时计算分组统计量

点数据溶解为人口加权质心

七、空间操作

从一个图层中擦除另一图层

提取内部边界

生成覆盖图层的六边形网格

合并兼容图层

八、重投影

投影到命名 CRS

匹配另一文件的投影

九、分类与样式

分位数分类到颜色渐变

为导出添加 SVG 样式

十、输出与格式转换

Shapefile 与 GeoJSON 互转

量化 TopoJSON

输出为 ndjson

按字段切分图层为多个文件

十一、工作流模式：命令文件与参数化

从文件运行命令链

参数化命令文件

遇到坏输入时提前终止流水线

处理超大文件时增加堆内存

延伸阅读

【免费下载链接】mapshaper

相关推荐

NocoDB数据导出终极指南：从新手到专家的完整操作手册

ToolJet 连接 MongoDB 数据源：从连接配置到 18 种查询操作的完整指南

QtScrcpy安卓投屏完全手册：从基础连接到高级群控的完整指南

本地虚拟机文件互传：VMware与VirtualBox共享文件夹配置避坑指南

Warp 代码评审并排 Diff 布局实现解析：DiffLayout 枚举、双编辑器桥接架构与特性开关设计

插件机制全面解析：从IAR到MusicFree，加载失败根源与避坑指南

openrig 统一编排 Claude Code 与 Codex：YAML 配置与 Node.js 实战

Claude Code 入门指南：TaoToken 统一 Key 接入 AI IDE 的 MCP 与 agentic 工作流

VueFlow 事件系统完全指南：组件事件监听与 useVueFlow Hooks 双模式实战