简介：pex-exp-topo-world 是一套基于 JavaScript + WebGL 与 TopoJSON 的世界地图渲染示例，面向前端开发、数据可视化学习者及需要构建地理信息展示的工程师。项目演示了从 TopoJSON 数据加载、地理坐标投影、顶点缓冲与着色器编写，到最终 canvas 绘制的完整链路，并包含多个层级地图数据，如 world-110m、world-50m、国家名称表等，便于对照理解 D3 与 WebGL 的协作方式。压缩包共 12 个文件，以 json 地图数据、js 脚本和 html 页面为主，辅以 tsv 对照表、预览图及说明文档，整体仅 1.18MB，结构紧凑、易于阅读。资源已有 209 人学习，适合希望快速体验拓扑地图渲染或将其嵌入自身可视化项目的开发者。 搞前端可视化的朋友，早晚都会碰到“把世界地图画在页面上”这种需求。之前我折腾过一个叫pex-exp-topo-world的实验项目，核心就一句话：用 Playwright 驱动浏览器，把topo-json格式的世界地图数据渲染成一张好看的图片。整个过程踩了不少坑，从数据格式的选择、topo-json 结构解读，到 D3 投影参数调优，再到最终截图输出，每一步都值得拿出来聊聊。
这个项目适合谁参考？如果你正准备做数据大屏、全球业务分布图、或者任何需要世界地图底图的可视化任务，这篇文章能给到你一套可以直接上手的方案。我会把关键原理、完整实操、以及我实际遇到的坑位都交代清楚，照着做基本能复现。
1. 为什么用 topo-json 渲染世界地图
1.1 topo-json 和 geojson 的本质区别
很多人第一次接触地图数据，拿到的都是 GeoJSON。它直观，每个国家都是一个独立的 Polygon 或 MultiPolygon，边界坐标直接写在 coordinates 数组里。但问题出在文件体积上。世界地图级别的 GeoJSON，动辄几十 MB，因为相邻国家的公共边界被重复存储了两遍。
TopoJSON 的设计思路是：把边界存成“弧段”。整个世界的所有国界，拆成一段段不重复的弧，然后每个国家用弧的编号组合出自己的形状。公共边界只保存一次，数据量能压缩掉 80% 左右。我项目里用的世界数据，GeoJSON 版本大约是 25MB，转成 TopoJSON 之后只剩 4MB 左右。加载和解析的速度差别，在低配机器上感知非常明显。
这也就是为什么 pex-exp-topo-world 选择 topo-json 作为数据格式的核心原因：更小的体积、更快的加载、更顺畅的渲染体验。尤其当你需要把地图数据打包进离线环境时，这 20MB 的差距就是能不能部署的红线。
1.2 数据从哪来：下载与转换
数据源方面，我推荐从公开的 GIS 数据仓库获取。常用的有两个路子：
直接下载现成的 .topo.json 文件。GitHub 上有不少维护良好的世界 TopoJSON 数据集，比如 world-atlas 这个仓库，提供了不同精度的版本，110m、50m、10m 分别对应低、中、高精度。做世界地图底图，110m 精度足够，文件只有几百 KB。
先拿 GeoJSON，再用工具转换。如果你手头只有 GeoJSON 数据，可以用 npm 上的
topojson-server工具包转换。命令也很简单：
npx geo2topo countries.geo.json > countries.topo.json这里有个关键参数--quantization值得注意，它决定坐标粒度的简化程度。默认值 1e4（即一万个量化区间），文件会小很多，但边界会略微失真。我习惯设成1e5，在文件体积和边界平滑度之间取一个平衡点。
注意：如果是从公开仓库下载现成文件，务必搞清楚数据精度和坐标系。大部分 world-atlas 数据用的都是 WGS84（EPSG:4326），也就是经纬度坐标系，D3 可以直接消费。
2. 核心细节：读懂 topo-json 的 arcs 与 transform
2.1 拓扑编码原理
TopoJSON 文件的核心结构比 GeoJSON 多了一层抽象。顶层是一个topology对象，里面有一个objects字段，存放了你关心的地理实体集合；还有一个arcs数组，存放所有的弧段定义；以及一个transform对象，用来做坐标解码。
这里要理解一个关键机制：arcs 里存的不是真实的经纬度坐标，而是“增量坐标”。为了压缩体积，TopoJSON 把所有坐标统一减去最小经纬度后，再除以一个量化步长，转成整数。真正的经纬度要经过 transform 里的scale和translate还原回来。解码公式是：
lon = (delta_x * scale[0] + translate[0]) lat = (delta_y * scale[1] + translate[1])也就是说，arcs 数组里第一个点是绝对坐标（经过量化），后面的点都是相对上一点的坐标差值。
2.2 关键字段解读
看一个简化后的 TopoJSON 结构：
{ "type": "Topology", "transform": { "scale": [0.036, 0.018], "translate": [-180, -90] }, "objects": { "countries": { "type": "GeometryCollection", "geometries": [ { "type": "Polygon", "arcs": [[0, 1, 2, -3]], "id": "CHN" } ] } }, "arcs": [ [[...]], // arc 0 [[...]], // arc 1 [[...]], // arc 2 [[...]] // arc 3 ] }注意arcs数组里的负数索引，比如-3，表示“反向遍历第 3 号弧”。这是拓扑结构的精髓：一条弧可以被多个面共享，方向相反表示对面的边界走向相反。D3 的topojson-client库会自动处理这些索引逻辑，你不需要手动解码，但理解它有助于排查数据问题。
我遇到过一种诡异的情况：地图上某个国家死活显示不出来，打开原始 JSON 一看，它的 arcs 索引超出数组长度。原因是最初的数据转换工具版本太老，生成的索引有 bug。如果你也遇到部分区域渲染缺失，第一步就该检查arcs索引合法性。
3. 实操：Playwright + D3 渲染世界地图完整流程
3.1 环境准备与工程初始化
项目目录结构很简单，前后端不需要分离，纯静态页面加一个 Playwright 截图脚本就行。
pex-exp-topo-world/ ├── index.html ├── map.js ├── package.json └── data/ └── countries-110m.jsonpackage.json 里的依赖：
{ "dependencies": { "d3": "^7.8.2", "topojson-client": "^3.1.0" }, "devDependencies": { "playwright": "^1.40.0" } }安装完依赖后，记得跑一次npx playwright install chromium，把 Chromium 内核下载下来，否则后续截图脚本会报浏览器找不到的错误。
3.2 加载数据和绘制地图
核心渲染逻辑写在 map.js 里。先加载 topo-json，再用topojson.feature()方法把拓扑数据转换成 GeoJSON Feature 集合，最后交给 D3 去绘制路径。
// map.js const width = 1280; const height = 720; // 1. 创建 SVG 容器 const svg = d3.select("#map") .append("svg") .attr("width", width) .attr("height", height); // 2. 加载 TopoJSON 数据 const response = await fetch("./data/countries-110m.json"); const worldTopology = await response.json(); // 3. 转换成 GeoJSON 要素集合 const countries = topojson.feature(worldTopology, worldTopology.objects.countries);这里有个容易踩坑的点：topojson.feature()的第二个参数必须是objects字段里的具体属性名，不是整个 topology 对象。我见过有人直接传worldTopology，结果返回的是空数组，地图一片空白。
接下来是投影和路径生成。D3 的geoNaturalEarth1投影是做世界地图的经典选择，视觉效果比较均衡，既不像墨卡托那样极地变形严重，也不像等距方位投影那样边缘拉伸。
// 4. 定义地图投影 const projection = d3.geoNaturalEarth1() .fitSize([width, height], countries); // 5. 生成路径生成器 const path = d3.geoPath(projection); // 6. 绘制每个国家 svg.append("g") .selectAll("path") .data(countries.features) .join("path") .attr("d", path) .attr("fill", "#e8e8e8") .attr("stroke", "#fff") .attr("stroke-width", 0.5);fitSize是 d3-geo 提供的好用方法，它会自动计算合适的缩放比例和平移偏移，让整个地图恰好铺满指定宽高的容器，省去手动试参的麻烦。对于 1280x720 的画布，自然地球投影默认经过 fitSize 调整后，视觉效果完全不输在线地图工具截图。
3.3 投影参数怎么调
fitSize虽好，但如果你想微调地图位置、缩放级别，就得手动控制投影参数了。核心是三个参数：
scale：缩放比例，数值越大地图越大。translate：地图中心在画布上的像素坐标。center：投影中心的地理坐标（经纬度）。
以自然地球投影为例，默认中心是 [0, 0]，也就是本初子午线和赤道的交点，正好是几内亚湾附近。如果想以亚洲为中心，比如把中国放在画布中央，可以这样做：
const projection = d3.geoNaturalEarth1() .center([105, 10]) // 亚洲中心大致经纬度 .scale(280) // 手动调缩放 .translate([width / 2, height / 2]);手动调参的方法：先固定 center，再调 scale，每次加 20 看效果，最后微调 translate 让整体居中。这个过程比较费眼力，建议在浏览器里开 DevTools 实时改参数，而不是反复刷新页面。
关于抗锯齿和边界清晰度，还有一个视觉小技巧：给每个国家路径加一道白色描边，宽度 0.5px。这样国与国之间的边界会非常清晰，大范围同色块填充时尤其重要。
#map path { stroke: #ffffff; stroke-width: 0.5px; vector-effect: non-scaling-stroke; }vector-effect: non-scaling-stroke这个属性容易被忽略，它保证描边宽度不随缩放而变粗变细，在地图缩放时保持边界线条的一致性。
4. 常见问题与排查技巧实录
4.1 数据加载失败或渲染空白
现象：页面打开，SVG 存在，但没有任何 path 元素，控制台报 fetch 404。
排查思路：先看网络请求，确认 countries-110m.json 是否真的被服务到了。如果你是直接双击打开 index.html，文件协议下 fetch 会被浏览器拦截，报 CORS 错误。解决办法：起一个本地静态服务。
npx serve .如果确认文件能访问，但地图还是空白，接下来在控制台打印countries.features.length。看到长度为 0，说明topojson.feature()的参数传错了。看到长度正常但页面无渲染，检查一下投影和路径生成代码，尤其是projection是否定义成功。
4.2 投影偏移导致地图跑到画布外
现象：地图渲染了，但只显示了一部分，另一半跑出画布。
这几乎都是 scale 和 translate 不匹配导致的。fitSize不会出这种问题，手动调参时才会。我的经验是：先不用 translate，默认 [0, 0]，把 scale 调到地图尺寸比画布略大，再用 translate 把地图中心点移回画布中心。这个顺序不能反，否则每次改 scale 都要重新算 translate。
另外，当你切换不同投影类型时，scale 的“手感”完全不同。geoNaturalEarth1的 280 和geoMercator的 280 对应不同视觉效果。别指望同一套参数在不同投影间复用。
4.3 Playwright 截图不全或字体异常
我在项目里用 Playwright 做无头浏览器截图，把渲染出来的 SVG 地图转成 PNG。有个细节要注意：等地图渲染完成再截图。D3 的 join 操作是同步的，数据加载之后的绘制过程不需要额外等待，因此脚本在page.goto()之后直接截图通常没问题。但如果你在地图之上叠加了动画过渡（transition()），就必须等动画结束，否则截到的画面只画了一半。
字体异常是另一个坑。无头浏览器默认没有系统字体渲染中文，如果页面上有中文标签，截图里就是方块字。解决办法是在截图脚本里指定等字体加载完成：
await page.evaluate(async () => { await document.fonts.ready; });顺带提一个视觉效果优化：SVG 地图默认是矢量渲染，缩放不糊，但导出 PNG 时会按设备像素比采样。我通常把deviceScaleFactor设为 2，这样导出的图片清晰度能适配高 DPI 显示屏。
const browser = await chromium.launch(); const page = await browser.newPage({ viewport: { width: 1280, height: 720 }, deviceScaleFactor: 2 });4.4 性能优化：大数据量下的卡顿与内存
虽然 110m 精度的世界地图数据不大，但如果你换成 10m 高精度版本，或者给每个国家加了复杂的点击交互，性能问题就会冒出来。我实际测量过：10m 精度数据渲染出的 path 节点超过 3 万个，首次渲染耗时比 110m 版本高出近一个数量级。
优化手段按优先级排列：
- 降低数据精度。世界地图底图，110m 足够，别追求高精度。
- 合并小区域。面积特别小的岛屿、飞地，可以直接从数据里剔除，肉眼根本看不出来。
- Canvas 渲染替代 SVG。D3 支持通过
canvas.getContext("2d")和path(context)绘制到 Canvas，几千个 path 的绘制性能提升明显，代价是失去 DOM 节点的点击能力。如果不需要交互，优先用 Canvas。
5. 从底图到数据大屏：效果增强经验
底图渲染出来只是第一步。pex-exp-topo-world 项目到了后期，我在底图上叠加了数据气泡、区域着色等效果，有几个经验值得分享。
给区域着色：topojson.feature()返回的 features 数组，每一项都有一个id属性，对应 ISO 3166-1 三位国家代码。我准备了以国家代码为 key 的统计对象，然后在创建 path 时指定fill颜色：
svg.append("g") .selectAll("path") .data(countries.features) .join("path") .attr("d", path) .attr("fill", (d) => { const value = dataMap[d.id]; if (value === undefined) return "#f0f0f0"; return colorScale(value); });标注城市坐标：d3-geo 投影函数反着用，可以把经纬度转成屏幕像素坐标：
const [x, y] = projection([116.4, 39.9]); // x, y 就是北京在 SVG 上的像素位置这个用法让点位标注、飞线动画都变得很简单。项目里我标了几个主要城市点位，再配合text元素显示城市名，一张业务大屏的地图部分就成型了。
发光效果：如果地图用于深色主题大屏，可以给高亮区域加filter发光。D3 里用 SVG filter 实现比较容易，但要注意 filter 在截图时可能渲染不完全，尤其是 Playwright 无头模式。我踩过一次这个坑，最后的解决办法是在 CSS 里用drop-shadow替代 SVG filter，截图表现稳得多。
6. 写在最后的实操心得
整个 pex-exp-topo-world 折腾下来，我最大的感受是：地图渲染上层的“画图”动作很简单，真正花时间的地方全在数据格式理解和参数调试上。TopoJSON 的弧段索引机制初看不直观，但一旦理解了transform的编解码逻辑，后面排查任何数据异常都非常顺手。
如果你照着这条路做，建议先跑通 110m 精度、自然地球投影、SVG 渲染的最小闭环，再一步步加交互、加数据、换 Canvas。别一上来就上高精度多效果，那样出了问题很难定位。
前阵子我规划了一个扩展方向：把地图数据从静态文件换成后端动态下发，前端只负责渲染，这样业务数据更新时不用重新构建静态资源。技术上没有新难点，核心就是接口返回 GeoJSON 格式，前端topojson.feature()这步改成直接使用d3.geoPath渲染后端返回的 GeoJSON。整体思路和这套静态方案是一脉相承的，你也可以试试看。
本文还有配套的精品资源，点击获取
