全新上线——最全面的 Turf.js中英文学习文档

全面解析源码，深入架构设计

🎉 重磅发布

你是否想深入了解 Turf.js 的源码实现？

🤔 为什么它能实现缓冲区计算？
🤔 K-means 聚类在地理空间中的实现细节是什么？
🤔 100+ 模块是如何组织成清晰的架构的？

今天，我们正式发布史上最全面的 Turf.js Wiki 文档站！

不是简单的 API 翻译，而是从源码层面深度解析每一个算法、每一处架构设计。

📚 文档站包含什么？

🔹 六大系统模块

1️⃣架构深度解析

Monorepo + 四层依赖 + 100+ 模块

源码级揭示：

• Lerna + pnpm的 Monorepo 组织方式
• 四层依赖架构：外部依赖 → 基础工具 → 原始操作 → 复合操作
• 100+ 包的版本统一管理策略
• ESM/CJS/UMD三格式分发机制

// 根 package.json"private":true// 工作区根，不发布// lerna.json"version":"7.2.0",// 100+ 包统一版本"npmClient":"pnpm"// pnpm 作为包管理器

2️⃣三大基础模块

@turf/helpers - GeoJSON 工厂函数

// packages/turf-helpers/index.ts:254-277exportfunctionpoint(coordinates:Position,properties?:Properties,options?:Options):Feature<Point>{// 直接对象创建，无中间结构constfeat:any={type:"Feature"};if(options?.id!==undefined)feat.id=options.id;feat.properties=properties||{};feat.geometry={type:"Point",coordinates};returnfeat;}

设计亮点：

• 最小验证，追求极致性能
• 支持点、线、面、Feature、FeatureCollection 的工厂函数
• 地球半径常量：6,371,008.8 米，所有测地线计算的基础

@turf/meta - 迭代工具链

// packages/turf-meta/index.jscoordEach(geojson,(coord,index)=>{// 跳过空几何体if(coord===null)return;// 处理所有 GeoJSON 类型// 不创建临时数组，直接遍历});

性能优化：

• 避免临时数组分配
• 直接坐标访问，无需规范化
• 支持excludeWrapCoord跳过闭合坐标
• 递归处理 GeometryCollection

@turf/invariant - 验证与提取

// 使用模式：自动提取几何体constgeom1=getGeom(feature1);// Feature → Geometryconstgeom2=getGeom(feature2);

三个验证函数：

• geojsonType()- 验证 GeoJSON 类型
• featureOf()- 验证 Feature 几何类型
• collectionOf()- 验证集合中的所有特征

3️⃣几何操作算法

缓冲区实现 - 测地投影 + JSTS

// 核心流程1.defineProjection()// d3-geo 创建等距方位投影2.projectCoords()// 递归投影到平面坐标3.BufferOp.bufferOp()// JSTS 库执行缓冲4.unprojectCoords()// 逆投影回 WGS84

多边形裁剪 - Greiner-Hormann 算法

等高线生成 - Marching Squares

// 从网格数据生成等值线/等值带-@turf/isolines → LineString features（等值线）-@turf/isobands → Polygon features（等值带）

4️⃣测量与变换

测地线 vs 恒向线

// 测地线：最短路径（大圆）distance(point1,point2,{units:'kilometers'})bearing(point1,point2)// 初始方位角destination(point1,10,90,{units:'kilometers'})// 10公里90度方向// 恒向线：等角航线（恒定方位）rhumbDistance(point1,point2)rhumbBearing(point1,point2)rhumbDestination(point1,10,90)

180 度经线补偿

// rhumb-destination 实现destination[0]+=destination[0]-coords[0]>180?-360:coords[0]-destination[0]>180?360:0;

5️⃣空间分析

K-means 聚类 - 球面距离版

// packages/turf-clusters-kmeans-依赖：skmeans（统计库）+@turf/distance（球面距离）-优化：点克隆避免修改原始数据-输出：每个点的 cluster 分组属性

DBSCAN 聚类 - 密度聚类

// packages/turf-clusters-dbscan-依赖：rbush（R-tree 空间索引）-优势：无需预设聚类数量，自动发现任意形状簇-参数：maxDistance（邻域半径）、minPoints（最小点数）

凹包生成 - 基于 TIN

// packages/turf-concave1.生成不规则三角网（TIN）2.基于边长过滤三角形3.合并剩余三角形形成凹包4.无法计算则返回null

consthull=turf.concave(points,{maxEdge:2,// 最大边长units:'kilometers'});

6️⃣构建系统

tsup 编译流水线

// 每个 package.json"build":"tsup --config ../../tsup.config.ts"

TypeScript 源代码 ↓ tsup ┌──────────────────────────┐ │ ES2017 JavaScript │ ├──────────────────────────┤ │ esm/index.js + .d.ts │ ← ESM 输出 │ cjs/index.cjs + .d.cts │ ← CJS 输出 └──────────────────────────┘

Rollup 浏览器包生成

// packages/turf/rollup.config.jsexportdefault[{input:"index.ts",output:[{file:"turf.min.js",format:"umd",name:"turf"}],plugins:[commonjs(),nodeResolve(),nodePolyfills(),// Node.js polyfillsbabel({babelHelpers:"bundled"}),// ES5 转译terser(),// 压缩],}];

双格式导出配置

{"type":"module","main":"dist/cjs/index.cjs","module":"dist/esm/index.js","types":"dist/esm/index.d.ts","exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/cjs/index.d.cts","default":"./dist/cjs/index.cjs"}}}}

7️⃣开发工具链

质量保证流水线

代码修改 → git add ↓ lint-staged 检测 ↓ ├─ monorepolint: package.json 一致性 ├─ eslint: 代码规范修复 ├─ typescript: 类型检查 └─ generate-readmes: JSDoc → README ↓ prettier: 格式化 ↓ git commit

CI/CD 三条流水线

🎯 为什么这份文档独一无二？

✅源码级解析

每篇文档都标注了 GitHub 源码位置，算法实现细节清晰可查

✅架构深度剖析

不局限于 API 使用，更讲解设计理念和实现策略

✅30+ 图表可视化

架构图、流程图、算法示意图，让复杂概念一目了然

✅实战代码示例

从简单到复杂，覆盖真实业务场景

✅中英文对照

中文深入讲解 + 英文原文参考

🚀 文档特色

📦 六大模块 21 篇文档- 从入门到精通的完整路径
🏗️ 源码级架构解析- Monorepo、依赖层次、构建系统
🔬 算法实现细节- 测地投影、JSTS、Greiner-Hormann
📊 空间分析深度- K-means、DBSCAN、凹包生成
⚡ VitePress 驱动- 极速加载，毫秒级响应
🌙 深色/浅色主题- 日夜无障碍阅读
🔍 全文搜索- 毫秒级检索技术细节

💻 立即体验

# 快速上手npminstall@turf/distance @turf/bufferimportdistance from'@turf/distance';const d=distance(point1, point2,{units:'kilometers'});

🔗 文档站点：https://lzugis.cn/turfjs-wiki/
🔗 GitHub 仓库：github.com/Turfjs/turf

🎓 适合人群

• 🌐 前端地图开发者（MapboxGL、Leaflet、OpenLayers）
• 📊 地理数据可视化工程师
• 🚀 全栈开发者（Node.js 空间计算）
• 🎯 想深入理解 Turf.js 源码的开发者
• 📚 GIS 算法爱好者

👇 转发给身边的技术伙伴，一起探索地理空间算法的奥秘！