全新上线——最全面的 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 算法
| 操作 | 模块 | 算法 |
|---|---|---|
| Union | @turf/union | Greiner-Hormann 裁剪 |
| Intersect | @turf/intersect | Sutherland-Hodgman 裁剪 |
| Difference | @turf/difference | 布尔差集操作 |
等高线生成 - 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.无法计算则返回nullconsthull=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 commitCI/CD 三条流水线
| Workflow | 触发条件 | 用途 |
|---|---|---|
turf.yml | 推送/PR | Node.js 18/20/22 测试 |
prerelease.yml | 推送 master | Alpha 版本发布 |
release.yml | 推送 v*..标签 | 正式版本发布 |
🎯 为什么这份文档独一无二？
✅源码级解析
每篇文档都标注了 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 算法爱好者
👇 转发给身边的技术伙伴，一起探索地理空间算法的奥秘！