Mapshaper Web App 使用指南：浏览器内的交互式地图编辑与数据处理工作台

• GIS
• CLI
• 数据可视化

Mapshaper Web App（位于 mapshaper.org 的公共站点，或由mapshaper-gui在本地启动）是 Mapshaper 的图形化界面，面向交互式编辑与可视化探索。它内置了一个与 CLI 共享同一套命令语法的控制台，数据加载完成后，绝大多数工作流都能在浏览器里完成。本文以 docs/essentials/web-app.md 为主线，结合 src/gui 下的源码实现与 bin/mapshaper-gui 启动脚本，系统讲解数据导入、控制台、显示选项、撤销与快照、本地部署等完整用法。

读完本文，你将掌握：如何在 Web App 中高效导入 Shapefile/GeoJSON/TopoJSON/CSV 及压缩包；如何用控制台以 CLI 语法驱动编辑；如何借助底图、交点检测、对比叠层进行可视化诊断；如何用好撤销、命令历史与.msx快照；以及如何本地起服、如何应对超大文件。

浏览器内处理：数据始终留在本机

Mapshaper Web App 的全部处理都在浏览器内完成，这是它最根本的架构前提。即使使用公共网站，你的数据也不会被上传到任何服务器；唯一会产生的网络流量是加载应用本身的静态资源、启用底图后拉取的瓦片，以及在开启相应选项时可能发生的 AI 助手请求和mapshaper.org的页面访问统计（详见 www/privacy.html）。这意味着你可以放心地拖入本地敏感数据做快速清洗、简化与投影转换。

加载数据

进入 Web App 后，可以通过三种方式把数据放进工作区：拖拽文件、粘贴内容、或点击Add files按钮选择文件。除了最直观的拖拽导入外，还有几个不那么显眼但很实用的行为。

压缩包自动解包

• 拖入一个包含 Shapefile 文件束的.zip，Mapshaper 会在浏览器端即时解压，并自动识别.shp、.dbf、.prj等伴生文件（sidecar）。
• 单文件格式（如 GeoJSON、TopoJSON、CSV）的.gz压缩包同样直接支持。
• KML 的.kmz压缩包也可以直接拖入。

粘贴 URL 与查询字符串预加载

• 在页面任意位置粘贴一个 URL，即可导入该地址指向的文件。
• 使用查询字符串批量预加载：https://mapshaper.org/?files=URL1,URL2会导入逗号分隔的 URL 列表。所有文件必须由允许跨域请求（CORS）的主机提供，否则会因跨域限制加载失败——导入逻辑在 src/gui/gui-import-control.mjs 中会给出包含 CORS 提示的错误说明。
• 在上述 URL 后追加&q可以跳过导入确认对话框，直接打开文件。www/index.html中的初始化逻辑会识别files=查询参数并据此触发预加载。

With advanced options：透传-i参数

导入对话框中的with advanced options是一个自由文本输入框，凡是 CLI 中-i（input）命令之后能写的参数，在这里都能用，包括：

• encoding=：指定文本编码（如encoding=big5用于 Big-5 编码的 DBF 属性表）；
• string-fields=：强制某些字段按字符串读取；
• csv-fields=：限定 CSV 导入的字段；
• csv-filter=：导入 CSV 时按表达式过滤行；
• combine-files：把多个文件合并成共享拓扑的数据集；
• name=：给导入的图层命名。

多文件不会自动合并

一次选中多个文件导入时，它们会被作为相互独立的图层载入，各自拥有独立的拓扑。如果你希望它们共享拓扑——这样公共边界在简化时会保持一致——需要勾选with advanced options并加上combine-files。这是做出"无缝简化"效果的关键开关：未合并时各图层的相邻边界各自简化，合并后则作为同一条弧统一处理。

导入 Shapefile 的小技巧

• 把 Shapefile 的组件文件一起拖入或选中：.shp、.dbf、.prj是最核心的三个，其余扩展名文件（如.shx、.cpg、.sbn）一般可以省略。
• 如果出现"未知文本编码"的警告，说明 DBF 属性表的编码无法自动识别。此时重新导入，勾选with advanced options并设置encoding=，例如繁体中文数据用encoding=big5，日文数据按实际来源选择对应编码。

控制台：交互式命令工作台

控制台（Console）是整个 UI 中能力最强的部分，按空格键即可开关。CLI 的绝大多数命令都能在控制台里执行，唯一例外是文件加载类命令-i、-include、-require——它们在浏览器控制台中被禁用，因为浏览器沙箱不允许任意读盘。从源码看，src/gui/gui-console.mjs 中validateBrowserRunCommands()也明确禁止了include、require、external从命令文件在控制台运行。

键盘操作

行尾反斜杠的续行逻辑在 src/gui/gui-console.mjs 的onEnter()中实现：检测到行尾\后，先把输入整理为多行形式，等用户再次回车才提交整条命令。

语法规则

• 单条命令前导的-可以省略：clip places与-clip places效果相同。
• 输入多条命令序列时，从第二条起每条都要带前导-。本文档示例统一带前导-，因为这种写法在 Web 控制台和 CLI 中都能直接使用。
• 命令默认作用于当前选中图层。执行前先在图层面板切换目标图层，或者显式传入target=指定；target=*表示对所有图层生效。对于顶层命令（如-dissolve）产生的新图层，控制台会自动把选中状态迁移过去（见 src/gui/gui-console.mjs 中applyParsedCommands()对flags.select的处理）。

控制台魔法词

以下命令由控制台直接识别，mapshaperCLI 程序并不认识它们：

• history：把当前会话打印成一条完整的命令行字符串。可以用它把交互操作复现成脚本，或保存为命令文件。
• clear：清空控制台缓冲。

此外，src/gui/gui-console.mjs 的submit()还内置了其他几个实用的魔法词，可作为补充：

• tips：打印控制台常用命令示例；
• context：以 JSON 形式输出当前运行时状态上下文；context download可将其保存为mapshaper-runtime-context.json；
• layers：列出当前已加载的图层；
• close/exit/quit：关闭控制台。

发现命令

• 输入help列出全部可用命令。
• 输入help <command>查看单个命令的完整选项，例如help dissolve。
• docs/reference.md 中的命令参考与help输出内容一致，且带搜索框，适合查阅。

值得一提的细节：控制台还支持Tab 键补全——输入单词前缀后按 Tab，会基于当前活动图层的字段名、其他图层名以及命令文件名自动补全（见 src/gui/gui-console.mjs 的tabComplete()与getCompletionWords()）。另外，info类命令不会写入命令历史，避免干扰target重置逻辑。

地图画布

右键菜单

右键菜单会根据光标下方的内容自适应：点击菜单中的值即可复制到剪贴板；点击菜单外任意位置即可关闭。可用的条目包括：

• Longitude, latitude：点击点的 WGS84 经纬度坐标。
• X, y：当数据已投影时，同一位置在图层自身坐标系下的坐标。
• Band values：在栅格图层上，光标所在像素的采样值——彩色影像会标注为red, green, blue（以及alpha）；无数据像素会明确标注"no data"。彩色影像还会额外给出color条目，以一个小色块加十六进制色值的形式展示像素颜色，方便直接复制进样式命令。
• Copy as GeoJSON：把当前选中的要素以 GeoJSON 复制出来，适合"抠出"单个多边形用于其他地方。
• Delete vertex / delete point / delete feature：在对应编辑模式下可用，用于删除顶点、点或整个要素。

图层导航

未在输入框打字时，按← / →方向键即可在已加载图层间循环切换（见 src/gui/gui-console.mjs 的onKeyDown()：左右方向键映射到selectPrevLayer()/selectNextLayer()）。

显示选项

点击页头的Display按钮打开显示选项面板。面板中的两个复选框都会跨会话记住（保存在浏览器本地存储中）。

• Detect line intersections（检测线交点）：在简化或编辑过程中，将自相交线段以红色高亮显示，并在地图顶部显示一个实时计数。它可以暴露源数据自身的拓扑问题，以及简化过程产生的线交点。在 Simplify 模式下，计数旁会出现repair链接，用于尝试修复由简化引起的交点。对应实现可见 src/gui/gui-intersection-control.mjs，其中维护着intersection-count读数与交点计数渲染。
• Compare with original（与原始数据对比）：以洋红色轮廓把"上一次编辑之前"的形状叠加到当前图形上，适用于-buffer、-smooth、-simplify命令以及 Simplify 滑杆操作。这样无需反复开关图层，就能直观看出一次编辑到底改了什么。当你做了无关的编辑或取消勾选时，叠层会清除。

底图（Basemaps）

打开底图会在数据下方绘制地图瓦片。点击Reference map（参考地图）或Satellite image（卫星影像）旁的眼睛图标即可开启；同样的两个选项也以缩略图按钮形式出现在地图右上角。

底图使用Mercator 投影，因此开启底图后你的数据也会切换为 Mercator 显示。如果数据无法以这种方式展示——比如没有地理坐标，或投影未知——面板会直接给出提示，而不是列出底图选项。

Add按钮可以添加你自己的底图，两种来源：

• Mapbox style URL：形如mapbox://...，可选填 access key；
• 栅格瓦片 URL 模板：并提供一个TMS复选框——TMS 瓦片的 y 索引从底部计数（区别于常见 Web Mercator 从顶部计数的惯例）。

自定义添加的底图会保存在浏览器中（src/gui/gui-basemap-control.mjs 中以custom_basemaps键存储），之后可从列表移除。注意底图瓦片是通过网络获取的，这是 Web App 中少数会产生网络流量的功能之一；其余一切数据操作仍在本机完成。

历史、撤销与快照

页头的History按钮统管三件事：撤销（Undo）、命令历史（Command history）与快照（Snapshots）。

撤销与重做

撤销默认开启。取消勾选enable undo可关闭它——当数据量大到"为每一步反向操作保存数据"成为负担时，关闭是值得的。该设置跨会话记住，并且改变只对之后的操作生效，不会追溯影响已有的撤销历史。从源码看，默认值与持久化逻辑位于 src/gui/gui-app-undo.mjs：APP_UNDO_DEFAULT = true决定默认开启，localStorage中mapshaper.undo为'off'时才关闭；URL 查询参数undo=on/off/commands还可以强制覆盖 UI 设置。

几个关键行为：

• Ctrl+Z（Mac 上是⌘Z）撤销，Shift+Ctrl+Z（⇧⌘Z）重做。只要有可撤销内容，地图底部的小工具栏也会出现同样的按钮。在文本输入框中打字时，快捷键会被忽略。
• 会话的第一次导入不可撤销，恢复快照也不可撤销——两者都被视为工作起点而非编辑操作。
• Mapshaper 默认保留最近十步，更早的会被丢弃；但当你处于某个编辑模式内部时，进入该模式以来的所有更改都可以逐步撤销，无论有多少步。编辑非常大的数据集会让较早的步骤更快被挤出；而一步大到存不下时，该步骤将不可撤销——命令本身仍会照常执行，但消息面板会出现警告。撤销所需的恢复数据存放在浏览器存储中：Restore data stored on-disk显示当前占用空间，clear undo history则立即丢弃。
• 需要说明的是：未记录的命令（例如在撤销关闭时执行的命令）会清空既有撤销历史，因为此时的历史已无法安全回溯（src/gui/gui-console.mjs 的discardHistoryAfterUnrecordedCommand()注释解释了这一安全策略）。

命令历史

View command history会打开控制台，并打印出产生当前状态的那串命令——作为一行命令文本，可以直接粘贴到终端，或保存为命令文件后用mapshaper -run执行。它与在控制台输入history的效果一致。当你撤销某一步时，该步会从命令历史中移除，因此这份历史始终精确描述"当前屏幕上是什么状态"。实现上，控制台每次成功执行命令都会把标准化后的命令追加进会话记录（src/gui/gui-console.mjs 的gui.session.consoleCommands(...)），而撤销/重做会同步激活或停用对应的历史条目。

快照

快照保存一个会话的完整状态，让你可以随时返回。它同时记录了背后的命令历史，因此重新打开快照时，命令历史也会一并恢复。

• Create snapshot：保存到浏览器内存储。每个快照会出现在按钮下方的列表中，附带三个操作链接：
  • restore：回到该状态。这会替换当前加载的图层并清空撤销历史。
  • export：把快照下载为.msx文件。
  • remove：从浏览器中删除。
• 浏览器内快照定位是临时的：Mapshaper 会在标签页关闭或页面重载时尝试清理它们。需要长期保留的内容，请使用export导出，或在 Export 面板中选择Snapshot file格式。

.msx快照格式

.msx是 Mapshaper 专有的二进制快照格式，包含弧段、图层、属性、CRS 元数据、拓扑，以及（从 Web App 导出时）产生它的命令历史，全部封装进单个文件（详见 docs/formats/snapshot.md）。它的二进制序列化基于 msgpack 协议（通过 msgpackr 库实现）。.msx并非用于与其他 GIS 工具交换数据——那是 Shapefile、GeoPackage、FlatGeobuf、GeoJSON 等格式的职责；它更适合保存工作进度、打包多数据集、以及在浏览器里做"实验前的存档点"。

在 CLI 端，-o foo.msx会捕获整个会话——所有数据集和所有图层，而不只是-target当前选中的部分；-target控制的是重开快照时的可见性与堆叠顺序（先匹配的在下层）。Web App 导出.msx时会把会话命令历史嵌入文件（见 src/gui/gui-export-control.mjs 中相关注释与实现），保证重新导入后工作流可复现。

本地运行 Web UI

mapshaper-gui在npm install -g mapshaper时会随mapshaper一起安装（package.json 中将其映射到bin/mapshaper-gui）。启动后它会：

1. 启动一个本地 Node Web 服务器；
2. 默认在http://localhost:5555打开 Web UI。

使用--port参数可以更换端口（对应 bin/mapshaper-gui 中的-p, --port <port>选项，默认端口常量即 5555）。

还可以在命令行直接列出文件进行预加载，从而跳过导入对话框：

mapshaper-gui states.shp rivers.shp

这样启动即进入带数据的编辑界面，适合把 Web App 作为日常查看/微调 Shapefile 的轻量工具。

浏览器支持与大数据量处理

Web App 的所有处理都在浏览器内存中完成，因此在导入数百 MB 级别的超大文件时可能耗尽内存导致崩溃。历史上 Firefox 处理大文件的能力优于 Chrome，但 Chrome 近期已有改善。如果 Web App 崩溃，可以改用mapshaper-xl命令行工具——它以更大的 Node 堆内存启动（默认 8 GB），并可用mapshaper-xl 16gb [commands]进一步调高上限，适合承接浏览器扛不住的大数据处理。

隐私小结

• Mapshaper Web App完全运行在浏览器内，没有任何文件内容被上传到服务器。
• 仅有的网络流量来源：应用静态资源本身、开启底图后的瓦片请求、安装方启用后的可选 AI 助手请求，以及mapshaper.org的页面加载统计。
• 完整的隐私说明见 www/privacy.html。

综合来看，Web App 与 CLI 共享同一套命令模型与文件格式（.msx、命令历史、-i参数体系），区别只在交互载体：前者提供画布、图层面板、右键菜单与即时可视化反馈，后者提供脚本化与超大内存处理能力。把交互式探索放在 Web App，把批处理与重型计算交给 CLI，是 Mapshaper 最实用的工作方式。

• GIS
• CLI
• 数据可视化