Mapshaper 文档体系全览与快速上手：CLI、Web 应用与全部支持格式的实战指南-平芜编程栈

GIS
CLI
数据可视化

【免费下载链接】mapshaper

Tools for editing Shapefile, GeoJSON, TopoJSON and CSV files

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

Mapshaper 是一款面向地理数据编辑的 JavaScript 工具，支持 Shapefile、GeoJSON、TopoJSON、GeoPackage、FlatGeobuf、GeoParquet、GeoTIFF、KML、CSV 等多种格式的读取与写入，同时提供命令行工具（CLI）和浏览器内运行的 Web 应用两种形态。本文以 docs/index.md 的文档体系为骨架，完整梳理其文档导航结构，并深度展开 CLI 安装与命令语法、Web 应用交互、文件格式对比、近期新增特性等核心内容，帮助读者快速定位所需文档并掌握最常用的实战操作。

Mapshaper 是什么

根据 docs/index.md 与 README.md 的定义，Mapshaper 是一个用于编辑地理矢量与栅格数据的工具，覆盖 Shapefile、GeoJSON、TopoJSON、GeoPackage、FlatGeobuf、GeoParquet、GeoTIFF、KML 和 CSV 等数据格式。它支持制图工作中最常见的基础任务：简化形状（simplify）、编辑属性数据、裁剪（clip）、擦除（erase）、溶解（dissolve）、过滤（filter）等，并且既可作为命令行程序使用，也可作为浏览器 Web 应用使用。

两个入口共享同一套命令语言：在浏览器控制台中交互书写的命令，可以直接原样运行在脚本或命令行中。所有 Web 端处理都在浏览器本地完成，数据不会离开使用者的机器。

当前仓库版本为0.7.73（见 package.json），采用 MPL-2.0 开源协议，要求 Node.js>=20.11.0运行环境。

文档体系导航：六个核心板块

docs/index.md本身是一个文档门户页，它将全部文档组织为六个板块，是读者进入 Mapshaper 技术世界的入口地图：

板块	文档位置	内容定位
Command reference（命令参考）	docs/reference.md	所有命令与选项的完整说明，附示例
What's new（新特性）	docs/whats-new.md	近期新增用户可见特性的精选日志
Getting started（快速入门）	docs/essentials/command-line.md、docs/essentials/web-app.md	CLI 与 Web 应用的介绍性教程
Guides（指南）	docs/guides/	关键主题的深度讲解，如 simplification.md、projections.md、expressions.md、styles-and-symbols.md
File formats（文件格式）	docs/formats/overview.md	所有支持数据格式的读写细节
Examples（示例）	docs/examples/basics.md、docs/examples/	常见编辑任务配方与完整地图制作实例

此外还有精选示例画廊 docs/gallery/、格式专项文档（如 shapefile.md、topojson.md、geojson.md）、以及面向开发者的内部设计文档 docs/development/（如 undo/redo 实现、栅格实现、标签工具设计等）。

面向 LLM 与 Agent 的机器可读索引

值得一提的还有 docs/_llms.md 这个特殊的入口：整个文档体系同时以 Markdown 镜像形式存在，每个页面的 Markdown 版本与 HTML 版本保持同路径，便于语言模型和其他工具直接抓取阅读。README 也明确建议：使用 AI 助手或可读文档的工具时，可以直接指向机器可读的文档索引，每个页面均可通过追加.md后缀获得纯 Markdown 版本。这意味着本文介绍的所有文档页面，都可以被搜索引擎、Agent 和 LLM 直接解析与引用。

快速上手：安装 CLI

Mapshaper 的 CLI 依赖 Node.js（版本要求见 package.json 的engines字段，当前为>=20.11.0）。全局安装后即可获得三个可执行程序：

npm install -g mapshaper

安装后获得三个命令（bin定义见 package.json）：

mapshaper—— 主 CLI；
mapshaper-xl—— 与mapshaper用法相同，但以更大的 Node 堆内存启动（默认 8GB），用于处理超大文件，可用mapshaper-xl 16gb [commands]覆盖内存上限；
mapshaper-gui—— 在本地运行 Web 界面，默认地址http://localhost:5555。

也可以不安装直接用npx mapshaper [commands]，或通过 Bun 运行时执行bunx mapshaper [commands]。安装完成后可用mapshaper -v验证版本。

大文件处理的额外选项：README 指出单文件输出上限为 2GB；GeoJSON、CSV、.shp、.dbf等格式支持增量读取，可导入更大的输入文件。若遇到 "JavaScript heap out of memory" 崩溃，可用mapshaper-xl或直接以 Node 参数加大堆内存，例如：

node --max-old-space-size=16000 `which mapshaper` <mapshaper commands>

命令语法解剖：一条命令的三种选项形式

Mapshaper 的调用方式是一串从左到右顺序执行的命令序列（见 docs/essentials/command-line.md 与 docs/reference.md）。每条命令以连字符前缀的命令名开头，后跟零个或多个选项。若第一个参数不是命令名，Mapshaper 会自动推断：大多数文件路径被当作-i（输入），.txt命令文件被当作-run。

选项有三种形式：

值（Values）：如provinces.shp、output.geojson；
标志（Flags）：如dp；
名/值对（Name/value pairs）：如precision=0.00001。

经典示例——读取 Shapefile、用 Douglas-Peucker 算法简化至 20% 顶点、写出坐标四舍五入的 GeoJSON：

mapshaper provinces.shp -simplify dp 20% -o precision=0.00001 output.geojson

常用通用选项

多个命令共用的选项在 docs/reference.md 中统一说明：

name=—— 重命名被命令修改的图层；
target=—— 指定命令作用的图层，接受图层名、图层序号（第一个图层为 1）或逗号分隔的名称/序号列表，名称可含*通配符；
+—— 用命令输出创建新图层而非替换目标图层，常与name=配合派生新图层。

# 从 states 派生只含阿拉斯加的子集图层，同时保留原图层 mapshaper states.geojson \ -filter 'ST == "AK"' + name=alaska \ -o output/ target=*

帮助信息

mapshaper -h # 列出所有命令 mapshaper -h simplify # 查看单个命令的详细选项

图层模型与链式处理

Mapshaper 的大多数命令作用于图层（layer）：图层是具有相同几何类型和一致属性模式的要素集合，支持 polygon（多边形）、polyline（折线）、point（点）三类图层；单个要素可包含一个形状、多个形状或不含形状（见 docs/essentials/command-line.md）。

处理多图层数据集时，命令作用于target图层。多数命令接受target=选项，-target命令可为其后的所有命令设定目标。导入 TopoJSON 时，每个命名对象会自动成为一个图层，例如：

mapshaper usa.topojson \ -filter 'STATE == "HI"' target=states \ -o out/hawaii.geojson

链式命令的典型场景——从普查区块溶解出到街区级、再从县级 Shapefile 生成州界与全国边界：

# 从人口普查区块溶解到街区级 mapshaper tabblock2010_36_pophu.shp \ -filter 'POP10 > 0' \ -each 'TRACT=BLOCKID10.substr(0,11)' \ -dissolve TRACT sum-fields=POP10 \ -o tracts.shp # 从县级 Shapefile 一次生成州界与全国边界 mapshaper counties.shp \ -dissolve STATE_FIPS name=states \ -dissolve + name=usa \ -o target='*'

命令文件：把工作流写成可复用脚本

除在命令行逐条输入外，命令序列可以写入纯文本命令文件（见 docs/essentials/command-line.md 的 Command files 一节），相对 shell 脚本有以下便利：

支持#注释（独占一行或行尾均可）；
无需转义*等 shell 元字符，命令不经过 shell 解析；
尾部反斜杠续行可用但不强制——不以-开头的行会被拼接到前一条命令；
支持{{VAR}}占位符变量插值。

命令文件是.txt文件，其首个非空、非注释行以mapshaper开头：

mapshaper -i provinces.shp # 使用 Douglas Peucker 简化 -simplify dp 20% -o precision=0.00001 output.geojson

若按 shell 兼容语法书写（尾部\续行、不使用#注释），该文件还能直接粘贴到 bash 命令行执行。运行命令文件使用-run：

mapshaper -run build.txt

mapshaper commands.txt是mapshaper -run commands.txt的简写。（命令文件在 Web UI 中导入运行的支持自 v0.7.46 加入。）

变量插值：让命令文件参数化

命令文件与命令行可包含{{VAR}}占位符，在每条命令运行前被替换（见 docs/essentials/command-line.md 的 Variable interpolation 一节）。两种形式：

{{VAR}}—— 替换为VAR的值；
{{env.NAME}}—— 替换为NAME环境变量的值。

变量可通过四种途径设置：-vars命令（总是覆盖旧值）、-defaults命令（仅设置尚不存在的值）、-calc与-define表达式中的赋值、-each表达式中给global对象赋属性。{{X}}替换先查模板作用域再回退到表达式作用域；而 JS 表达式中的裸变量名只能看到表达式作用域（-vars设置的名字在-each、-filter中不能按裸名读取）。

# build.txt 内容 mapshaper -defaults YEAR=2024 PCT=10 # 可覆盖的默认值 -i sources/counties_{{YEAR}}.shp -simplify {{PCT}}% -o out/counties_{{YEAR}}_simplified.shp # 使用文件默认值运行 mapshaper build.txt # 从命令行覆盖默认值 mapshaper -vars YEAR=2030 PCT=5 -run build.txt

Web 应用：浏览器内交互编辑

Web 应用（详见 docs/essentials/web-app.md）面向交互式编辑与可视化探索，内置控制台支持与 CLI 相同的编辑语法，绝大多数工作流在数据加载后可直接在浏览器中完成。所有处理均在浏览器本地进行。

加载数据

支持拖拽、粘贴、或使用Add files按钮导入。若干不太显眼的技巧：

拖入包含 Shapefile 文件组的.zip，Mapshaper 会即时解压并识别附属文件（.gz用于单文件格式、.kmz用于 KML 同理）；
在页面任意位置粘贴 URL 即可导入该地址的文件；
查询串预加载：https://mapshaper.org/?files=URL1,URL2可导入逗号分隔的 URL 列表（需目标服务器允许跨域），追加&q可跳过导入对话框直接打开；
with advanced options是一个自由文本输入框，凡在 CLI 中-i后可写的选项均可使用，如encoding=、string-fields=、csv-fields=、csv-filter=、combine-files、name=等；
多文件不会自动合并：同时选择多个文件会作为独立图层导入；需要共享拓扑（公共边界被一致地简化）时，勾选with advanced options并添加combine-files。

导入 Shapefile 的技巧：可把.shp、.dbf、.prj一起拖入（其他附属文件通常可省略）；若出现未知文本编码警告，可重新导入并在高级选项里设置encoding=（例如中文环境常用encoding=big5）。

控制台（Console）

按空格键开关的控制台是 Web UI 中最强大的部分。大部分 CLI 命令在此可用，但-i、-include、-require等文件加载命令在浏览器控制台中被禁用。

快捷键：空格开关控制台；上/下方向键循环历史命令（跨页面刷新保留）；行尾输入反斜杠\可续行，回车换行、再按回车执行整条命令；
语法：单条命令开头的-可省略（clip places等价于-clip places）；连续命令序列中，除第一条外的每条命令前需带-；命令默认作用于当前选中图层，可在图层面板切换或在命令中显式传target=（target=*对所有图层执行）；
控制台专属的 "magic words"（CLI 不认识）：history将当前会话打印为一条命令行字符串，便于把交互工作流复现为脚本；clear清空控制台缓冲区；
命令发现：help列出所有可用命令，help <command>查看单命令完整选项。

地图交互与显示选项

右键菜单会根据光标下的内容自适应，点击值即可复制到剪贴板：包括经纬度（WGS84 坐标）、X, y（投影图层的自身坐标）、栅格图层的波段采样值（标记为red, green, blue及alpha，无数据像素会特别标注）、颜色图像的color条目（色块旁附十六进制值，可复制进样式命令）、Copy as GeoJSON（把选中要素复制为 GeoJSON 用于剪出单个多边形）、以及编辑模式下的删除顶点/点/要素项。未输入文字时，左/右方向键可在已加载图层间循环切换。

Display 按钮打开显示选项面板，两个复选框会在会话间被记住：

Detect line intersections—— 简化或编辑时用红色高亮自相交，并在地图顶部显示实时计数，可揭示源数据的拓扑问题与简化引起的相交；Simplify 模式下计数旁会出现repair链接，尝试修复简化引起的相交；
Compare with original—— 用洋红色描边在现有形状之上绘制上次编辑前的形状，适用于-buffer、-smooth、-simplify命令和 Simplify 滑块，可精确观察编辑改了什么；进行无关编辑或关闭复选框后叠加清除。

底图（Basemaps）

开启底图会在数据下方绘制地图瓦片，点击Reference map或Satellite image旁的眼镜图标启用，地图右上角也有同款缩略按钮。底图采用墨卡托投影，开启后数据也以墨卡托显示；若数据没有地理坐标或投影未知，面板会提示而非列出底图。Add可添加自定义底图：Mapbox 样式 URL（mapbox://...，可带访问密钥）或栅格瓦片 URL 模板（含 TMS 瓦片复选框，TMS 的 y 索引从底部计数）。自定义底图保存在浏览器中并可移除。注意：底图瓦片需要联网获取，其余处理全部在本地。

历史、撤销与快照

History 按钮涵盖撤销、命令历史与快照三件事：

撤销/重做默认开启。处理数据大到存储反向数据成为负担时，可清除enable undo关闭；该设置跨会话记忆，且只影响此后操作。快捷键为Ctrl+Z（Mac 为⌘Z）撤销、Shift+Ctrl+Z（⇧⌘Z）重做，地图底部也会出现小工具条按钮；在文本输入框中打字时快捷键无效。会话的首次导入不可撤销，恢复快照也不可撤销——两者被视为起点而非编辑。Mapshaper 保留最近十步，旧的被顶掉；但在编辑模式内，进入模式以来的每次修改都可撤销（无论多少）。编辑超大数据集可能让旧步骤更快被顶出，而大得存不下的步骤根本无法撤销：命令照常执行，但消息面板会出现警告。撤销数据存储在浏览器中，Restore data stored on-disk显示当前占用空间，clear undo history丢弃之；
命令历史：View command history打开控制台并打印产生当前状态的命令序列（与输入history相同），可直接粘贴到终端或保存为命令文件；撤销某步会将其从列表移除，因此历史始终描述屏幕当前状态；
快照：保存会话状态以便返回，同时记录背后的命令历史，重新打开快照也会带回历史。Create snapshot保存到浏览器存储，每个快照带 restore（回到该状态，替换已加载图层并清空撤销历史）、export（下载为.msx文件）、remove（删除）三个链接。浏览器内快照是临时性的，标签页关闭或刷新时会被清理；需要长期保留请用export，或在导出面板选择Snapshot file格式。.msx快照文件的内容与 CLI 用法见 docs/formats/snapshot.md。

本地运行 Web UI

mapshaper-gui（随npm install -g mapshaper一起安装）会启动本地 Node Web 服务器并打开http://localhost:5555，可用--port指定其他端口；命令行列出文件可跳过导入对话框直接预加载：

mapshaper-gui states.shp rivers.shp

浏览器支持与隐私：导入数百 MB 的超大文件时 Web 应用可能内存不足崩溃（Firefox 处理大文件能力历史上优于 Chrome，Chrome 近期有所改善）；崩溃时可改用mapshaper-xl命令行工具分配大内存。隐私方面，Web 应用完全在浏览器中运行，文件内容不上传任何服务器；唯一的网络流量是静态资源（应用本身）、开启底图后的瓦片、以及（若安装方启用）可选的 AI 助手请求和 mapshaper.org 页面的分析统计。

文件格式全景：读写能力对比

docs/formats/overview.md 给出了全部支持格式的对比表，以下是完整继承：

格式	扩展名	读	写	几何	属性	拓扑	多图层
Shapefile	`.shp.shx.dbf.prj.cpg`	✓	✓	矢量	DBF（10 字符字段名）	—	—
GeoJSON	`.json.geojson`	✓	✓	矢量	是	—	—
TopoJSON	`.json.topojson`	✓	✓	矢量	是	✓	✓
GeoPackage	`.gpkg`	✓	✓	矢量	是	—	✓
FlatGeobuf	`.fgb`	✓	✓	矢量	是	—	—
GeoParquet	`.parquet.geoparquet`	✓	✓	矢量	是	—	—
KML / KMZ	`.kml.kmz`	✓	✓	矢量	有限	—	✓
CSV / TSV	`.csv.tsv`	✓	✓	点（X/Y）	是	—	—
DBF	`.dbf`	✓	✓	无	是	—	—
JSON records	`.json`	✓	✓	无	是	—	—
GeoTIFF	`.tif.tiff`	✓	✓	栅格	—	—	—
PNG / JPEG 栅格	`.png.jpg.jpeg`	✓	—	栅格（带世界文件）	—	—	—
SVG	`.svg`	✓	✓	矢量	作为`data-*`	—	✓
Mapshaper 快照	`.msx`	✓	✓	矢量	是	✓	✓

跨格式的通用要点（原文完整继承）：

按扩展名自动识别：通常无需告知 Mapshaper 文件格式，输入输出格式均由扩展名推断；可用-i/-o的format=覆盖；
TopoJSON 是唯一在文件本身中保留拓扑的交换格式：-dissolve、-clean、-simplify等拓扑感知操作无论输入格式如何都能正确工作，但只有 TopoJSON 能在磁盘上避免相邻多边形共享边界被重复存储（Mapshaper 自己的.msx快照也保留拓扑，但其他工具无法读取）；
编码：-i与-o的encoding=选项适用于 Shapefile、DBF 与 CSV/TSV 读写（默认 UTF-8），其他格式仅支持 UTF-8；
栅格与矢量图层分开导出：GeoTIFF 是唯一接收栅格图层像素的输出格式，且只接收像素，因此会话中同时存在两类图层时-o需要target=；SVG 与.msx快照是仅有的两种可接受混合输出的格式。

格式专项细节示例

输入侧（-i，见 docs/reference.md 的 -i 一节）：多个输入文件可combine-files合并为共享拓扑的多个图层，或batch-mode作为多次独立运行分别处理（当前默认批处理模式，未来版本将变更默认值，隐式触发时会打印弃用提示；依赖批处理的脚本应显式加batch-mode）。其他重要选项包括：snap（吸附微小坐标错位）、precision=（已弃用，推荐在导出时用-o precision=）、no-topology（跳过拓扑识别以加速大文件）、encoding=（读 DBF 与分隔文本，缺失时尝试自动检测，也可用.cpg文件指定）、string-fields=/field-types=（CSV 字段类型控制，避免邮政编码等被转成数字）、csv-filter=/csv-fields=（边读边过滤/选字段，降低超大 CSV 的内存占用）、json-path=（JSON 深层路径）、layers=（GeoPackage 按名选层）、以及栅格相关的scaling=、scale-range=、percentile-range=、raster-type=image|categorical|continuous、rendition=（GeoTIFF 概览选择）。

输出侧（-o）：format=可指定shapefile|geojson|topojson|flatgeobuf|geopackage|geoparquet|geotiff|json|dbf|csv|tsv|svg|html；precision=用于四舍五入坐标以缩小 GeoJSON 体积；force允许覆盖输入文件；gzip/zip压缩输出；GeoJSON 相关的combine-layers、geojson-type=、hoist=、reverse-winding、ndjson、gj2008；TopoJSON 相关的quantization=、presimplify、singles；SVG/HTML 相关的width=、height=、svg-bbox=、raster-res=、jpeg-quality=、responsiveness=、image-format=、pixel-ratio=；GeoParquet 相关的compression=snappy|zstd|none（默认 snappy）、level=（ZSTD 1–22 级）、rowgroup=。html格式按 ai2html 思路输出 HTML 片段加图片：多边形、线、栅格、地图框与比例尺画入 PNG/JPEG 图像，点图层（标签、图标、圆）作为内联 SVG 叠在图像之上，各点符号以地图宽高的百分比锚定，地图缩放时符号保持位置与尺寸。

近期新增特性速览

docs/whats-new.md 记录了一系列近期加入的用户可见特性，其中较有代表性的包括：

预览模式：Web UI 新增预览开关，可查看导出后的地图效果（目前 SVG 是带样式的导出格式）；
标签编辑增强：标签文本在地图上就地编辑；曲线标签沿路径排布；区域文本按设定宽度换行；标注线（callout）支持直线、折线与曲线并可选箭头；文本光晕（halo）增强可读性；
饼图与甜甜圈符号：-symbols命令新增pie类型，values=设定各扇区大小、fills=设定颜色，加hole=即成为甜甜圈；
Repel 命令：-repel消除或减少圆形符号间的重叠，max-shift=限制符号偏离真实位置的距离，polygons=将符号约束在多边形边界内；
栅格能力：GeoTIFF 栅格导入、PNG/JPEG 世界文件栅格、-blur模糊、-contours等高线/等值带（含closed等值面）、GeoTIFF 导出；-proj支持 Interrupted Goode Homolosine、Interrupted Mollweide、Dymaxion、Butterfly、Cahill-Keyes、Narukawa 2022 等中断/多面体世界投影，-graticule可为这些投影生成经纬网、多边形足迹与边框；
Smooth 命令：-smooth按给定分辨率平滑多边形与折线，默认保留尖角并应用预过滤去除亚尺度细节，gain控制输出曲线振幅，max-bend-angle权衡输出顶点数与连接平滑度；
Buffer 命令：点/线/面缓冲，lat-long 数据集默认使用测地线距离，topological防止缓冲与邻近多边形重叠，fill-gaps填充封闭孔洞与窄口海湾而不扩大外边界；
撤销/重做：Web UI 支持控制台命令与数据编辑的撤销重做（默认开启，可从 History 菜单关闭）；
FlatGeobuf / GeoPackage / GeoParquet 读写、SVG 导入（导出后的 SVG 可重新导入做样式微调）、命令文件与变量插值（v0.7.46 起）、-dissolve 采用最稳健的溶解算法（-dissolve2降级为别名）、Snip 工具（Web UI 中切断折线要素）、Ruler 工具（测量距离）。

完整变更列表（含 bug 修复与内部工作）见仓库根目录的 CHANGELOG.md。

从源码与测试加深理解

Mapshaper 的命令实现集中在 src/commands/ 目录，每个命令一个模块，例如 mapshaper-simplify.mjs、mapshaper-dissolve.mjs、mapshaper-buffer.mjs、mapshaper-clip-erase.mjs。CLI 的解析与执行逻辑在 src/cli/（如 mapshaper-run-command.mjs、mapshaper-parse-commands.mjs），命令文件运行在 mapshaper-run-command-file.mjs。各类格式的读写分别位于 src/shapefile/、src/geojson/、src/topojson/、src/geopackage/、src/geoparquet/、src/geotiff/ 等目录。

测试方面，仓库在 test/ 下提供了与命令一一对应的测试文件，例如 simplify-test.mjs、dissolve-test.mjs、buffer-test.mjs、geoparquet-import-test.mjs，浏览器端行为则有 browser-tests/ 下的 Playwright 测试（如 label-editing.spec.mjs、snip-tool.spec.mjs）。开发者可从项目目录运行npm run build构建 CLI 与 Web UI 模块、npm test运行测试套件、npm run test:browser运行浏览器测试（见 package.json 的 scripts 字段）。

寻求帮助与反馈

若发现 bug 或希望请求新特性，可在项目仓库的 issues 页面提交；Mapshaper 是自由软件，官方同时提供赞助渠道支持其持续开发。对于需要引用权威说明的读者，当对某个命令的行为拿不准时，docs/reference.md 是"唯一事实来源"（source of truth），其中每个命令都附有完整选项与示例；本文所引的所有文档均可在仓库 docs/ 目录下直接查阅对应的 Markdown 原文。