Turf.js 缓冲区分析(Buffer)实战：生成多边形缓冲区域

一、什么是缓冲区分析及其空间几何意义

空间缓冲区本质上是空间临近度度量的一种几何表达。无论是判断某一危险化学品泄露点的辐射隔离带、计算城市给排水主管道沿线受保护走廊，还是核算规划用地四周的建筑退让红线，核心问题都可以归纳为：以已知几何体为中心，寻找所有到该几何体边界的最短欧几里得距离或大圆测地线距离小于等于给定距离 \(r\) 的所有空间点的集合。

在 Turf.js 中，无论输入的原始要素是点（Point）、多线（MultiLineString）还是复杂多边形（Polygon），经过 turf.buffer 计算后，生成的输出始终是封闭的面要素——即 Feature<Polygon | MultiPolygon>。不同形态的几何体在外扩时遵循着严密的几何拓扑法则：

• 点要素缓冲：以点坐标为中心，以 \(r\) 为半径向四周各向同性扩展，生成一个逼近圆形的闭合多边形。
• 线要素缓冲：沿折线的每条线段左右两侧沿法线方向等距外平移，线段交接处生成平滑倒角，并在首尾两端生成半圆形的封闭弧形穹顶，最终组合为胶囊状的带状走廊面。
• 面要素缓冲：对于正向距离，面要素的所有外轮廓向外推移膨胀，凸角以圆弧过渡；对于负向距离，轮廓向内部侵蚀等距收敛，收窄原本的多边形面积。

二、Turf.js 缓冲区分析核心 API 与运行机制

Turf.js 的缓冲区功能封装于 @turf/buffer 模块中，如果引入的是包含完整工具集的全局命名空间包 @turf/turf，则直接通过 turf.buffer 调用。其函数签名如下：

turf.buffer(geojson, distance, [options])

该方法接收三个主要参数：

• geojson (GeoJSON | Feature | FeatureCollection): 输入的原始地理要素，支持 Point、LineString、Polygon 以及对应的 Multi 复合类型和要素集合。
• distance (number): 缓冲区的距离半径。允许传入正数（向外扩展）或负数（仅针对 Polygon 向内收缩）。传入 0 则返回原几何体近似轮廓。
• options (Object, 可选): 缓冲区控制参数对象，包含以下两个核心属性：
  • units (string): 距离单位，可选值为 'kilometers'（默认）、'meters'、'miles'、'degrees'、'radians'。
  • steps (number): 控制圆弧段插值折线的步数，默认值为 8。该数值越高，圆角过渡越平滑，生成的坐标顶点也越多。

三、实战演练：生成点、线、面的多边形缓冲区

下面给出在现代 JavaScript / Node.js 或浏览器环境中使用 Turf.js 生成三种典型几何形态缓冲区的完整可运行示例代码。

1. 引入 Turf.js 依赖

如果你在前端 HTML 项目中通过 CDN 加载：

<script src="https://cdn.jsdelivr.net/npm/@turf/turf@6/turf.min.js"></script>

如果在现代前端工程化项目（如 Vue、React、Vite）中使用 npm 安装：

npm install @turf/buffer @turf/helpers

2. 点要素生成圆形缓冲多边形

以某个商圈 POI 点（如经度 116.4074，纬度 39.9042）为例，生成其周围 500 米的服务范围多边形：

// 1. 定义点要素 (北京天安门附近)
const pointFeature = turf.point([116.4074, 39.9042], {
  name: "核心商圈POI",
  category: "零售中心"
});

// 2. 生成 500 米的缓冲区多边形
const pointBuffered = turf.buffer(pointFeature, 500, {
  units: 'meters',
  steps: 16 // 增加步数，使生成的圆轮廓更加平滑
});

console.log("缓冲后要素类型:", pointBuffered.geometry.type); // "Polygon"
console.log("坐标顶点数量:", pointBuffered.geometry.coordinates[0].length); // 65 (16 * 4 + 1个闭合点)
console.log("保留的原始属性:", pointBuffered.properties.name); // "核心商圈POI"

3. 线要素生成带状管廊缓冲多边形

以一段道路或输水管线（LineString）为基准，向两侧各延伸 50 米，形成施工控制带：

// 1. 定义输油管线折线要素
const pipelineFeature = turf.lineString([
  [116.38, 39.90],
  [116.40, 39.91],
  [116.42, 39.90]
], { pipelineId: "PL-2026-A" });

// 2. 生成双侧各 50 米的廊道多边形
const pipelineBuffered = turf.buffer(pipelineFeature, 50, {
  units: 'meters',
  steps: 8
});

// 结果将输出一个闭合的 Polygon，末端以半圆穹顶平滑封闭

4. 面要素向外扩展安全红线

对于已有的一处公园或保护区多边形，向外扩展 1.5 公里作为生态缓冲屏障：

// 1. 定义保护区多边形
const parkPolygon = turf.polygon([[
  [116.35, 39.92],
  [116.37, 39.92],
  [116.37, 39.95],
  [116.35, 39.95],
  [116.35, 39.92] // 首尾闭合
]], { parkName: "城市中央湿地公园" });

// 2. 向外扩展 1.5 千米
const parkBuffered = turf.buffer(parkPolygon, 1.5, {
  units: 'kilometers',
  steps: 12
});

四、核心参数与状态对比：正向缓冲 vs 负向缓冲与精度步数

在实际生产开发中，开发者经常需要根据不同的业务目标调优缓冲区的参数。其中最关键的两个控制变量，一是缓冲半径的正负方向，二是插值步数 steps 的取值。为了清晰理解其对几何拓扑与系统性能的影响，我们在相同输入条件下对比其关键差异。

1. 正向缓冲与负向缓冲的机制差异

缓冲距离的正负不仅决定了面积是膨胀还是收缩，更对要素的几何存续性有着本质区别：

2. steps 参数对性能与视觉精度的权衡

steps 参数决定了每一个 90 度圆弧象限内插入的折线段数量。在生成圆形或圆角时，一个完整 360 度的圆周包含的顶点数约为 \(4 imes ext{steps} + 1\)。

• 低步数（如 steps: 4 ~ 8）：在默认值 8 时，每个圆弧由 32 个线段组成。几何体轮廓在常规比例尺下足够平滑，且每个要素的坐标体积非常轻量。若将 steps 降为 4，生成的缓冲圆接近正十六边形，计算耗时仅需微秒级，特别适合移动端或成千上万个要素的批量即时运算。
• 高步数（如 steps: 24 ~ 64）：当 steps 设为 32 时，圆周顶点数骤增至 129 个；若设为 64，则达到 257 个。在高精度大比例尺地图显示或精确几何量算时，高步数能消除视觉上的棱角感；但多边形的数据体积与后续交并差拓扑运算耗时将呈几何级数增长。在生产环境中，无特殊测绘需求不建议盲目设置超过 16 的步数。

五、生产避坑指南：坐标系陷阱、塌陷防御与拓扑重叠合并

在实际项目落地时，若直接将 turf.buffer 放置在业务链路中，往往会遇到边界异常导致页面白屏或样式重叠混乱的问题。以下是三个必须处理的高频陷阱及对应的解决方案：

1. 负缓冲导致的几何完全塌陷防御

当对一个较小的地块应用过大的负向缓冲时（例如一个直径 20 米的地块进行了 -30 米的内缩），JSTS 底层几何计算引擎会发现多边形已无任何内部实体，此时 turf.buffer 将返回 undefined。如果代码中直接访问 buffered.geometry，就会抛出致命的 TypeError: Cannot read properties of undefined。

// 生产安全调用范式：必须增加判空兜底
function safeNegativeBuffer(polygonFeature, shrinkDistanceMeters) {
  const buffered = turf.buffer(polygonFeature, -Math.abs(shrinkDistanceMeters), {
    units: 'meters'
  });

  if (!buffered || !buffered.geometry) {
    console.warn("多边形面积过小，经负缓冲计算后已完全塌陷消失！");
    return null; // 安全兜底，避免后续渲染流程崩溃
  }

  return buffered;
}

2. 多要素批量缓冲的重叠合并（Dissolve）

当对密集的多个点（例如一串摄像头点位或公交站点）同时执行 turf.buffer 时，若直接渲染到地图上，半透明的缓冲圆在交叠区域会产生杂乱的颜色叠加和视觉黑斑，且图层元素数量过多。此时应结合 turf.combine 与 turf.dissolve 将重叠区域融合成单一连续的多边形：

// 1. 创建包含多个邻近点的 FeatureCollection
const points = turf.featureCollection([
  turf.point([116.40, 39.90]),
  turf.point([116.41, 39.90]),
  turf.point([116.42, 39.90])
]);

// 2. 批量生成 1.5 公里缓冲区
const bufferedCollection = turf.buffer(points, 1.5, { units: 'kilometers' });

// 3. 核心步骤：将有重叠的多个多边形融合成无缝单一多边形
const combined = turf.combine(bufferedCollection);
const dissolved = turf.dissolve(bufferedCollection);

// 此时 dissolved 内部重叠的轮廓线被全部消除，仅保留最外层连续轮廓

3. 单位（units）遗漏引发的尺度失真

turf.buffer 的默认单位是 'kilometers'。初学者常传入 turf.buffer(point, 100) 并意图获得 100 米的缓冲圈，但实际上生成了一个半径长达 100 公里、覆盖大半个省份的巨型多边形。无论在何种场景下，都应始终显式指定 units 参数。

六、全流程总结与工程实践清单

在 Web 前端执行缓冲区分析，不仅减轻了服务器端的计算与网络吞吐负担，而且能带来流畅的即时交互体验。在将缓冲区功能引入工程项目时，建议遵循以下清单进行自检：

• 数据输入前：严格核对坐标序为 [经度, 纬度]，确认输入源属于标准 WGS84 经纬度。
• 参数配置时：显式声明 units 参数（如 'meters'）；针对大量要素场景，将 steps 维持在 8。
• 逻辑分支中：凡是涉及负缓冲计算（distance < 0），强制加入 if (!result) 判空防御逻辑。
• 视觉呈现时：对于多要素连续缓冲区，优先调用 turf.dissolve 进行几何融接，消除内部重叠线与样式脏斑。
• 性能极限下：当要素顶点数超过万级时，可配合 turf.simplify 进行道格拉斯-普克（Douglas-Peucker）抽稀，或将计算逻辑放入 Web Worker 中执行以避免阻塞 UI 线程。