Turf.js 安装与引入：NPM 打包及 CDN 快速上手指南

一、引入模式选型与多维对比

在着手编写代码之前，明确不同引入方式的技术边界有助于避免后续的包体积膨胀或依赖冲突。Turf.js 的架构设计非常模块化，官方既维护了一个包含百余种常用空间分析函数的全集仓库（@turf/turf），也将每个计算函数独立发布为单独的 NPM 子包（如 @turf/distance、@turf/buffer 等）。

总体而言，接入 Turf.js 存在三种典型姿态：

• CDN 全量直链引入：适合快速构建原型、简单单页演示、教学代码或无前端编译链的遗留系统。浏览器直接请求已打包好的压缩脚本，全局挂载 window.turf。
• NPM 全量包引入（@turf/turf）：适合在本地开发阶段探索各种算法，或者项目本身是复杂 GIS 分析平台需要密集调用大量函数的场景。
• NPM 细粒度子包引入（推荐）：生产环境工程（基于 Vite、Webpack、Rollup）的推荐实践。只安装并打包用到的算法，可将最终产物体积压缩至原来的几十分之一。

二、方案一：CDN 快速上手（免构建方案）

如果你只需要在一个独立的 HTML 文件中验证某个空间算法（例如计算两个坐标点之间的球面距离），使用公共 CDN 服务是最快的方式。你不需要初始化 package.json，也不需要运行构建命令。

1. 常用 CDN 地址与版本控制

目前业界主流公共 CDN（如 unpkg 和 jsdelivr）均镜像了 Turf.js 发布的预编译产物。常用的 CDN 引用地址如下：

• unpkg 稳定版：https://unpkg.com/@turf/turf/turf.min.js
• unpkg 锁定具体版本（推荐）：https://unpkg.com/@turf/turf@7.2.0/turf.min.js
• cdnjs 源：https://cdnjs.cloudflare.com/ajax/libs/Turf.js/7.2.0/turf.min.js

2. 完整 HTML 演示示例

下面是一个完整的 HTML 文件示例。代码首先通过 <script> 标签拉取 Turf.js，随后在业务脚本中使用 turf.point() 构造北京与上海的经纬度要素，并计算两地的实际球面距离：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Turf.js CDN 快速测试</title>
  <!-- 1. 引入 CDN 托管的预打包脚本 -->
  <script src="https://unpkg.com/@turf/turf@7.2.0/turf.min.js"></script>
</head>
<body>
  <h1>Turf.js 空间距离计算测试</h1>
  <div id="output" style="padding: 12px; background: #f0fdf4; border-radius: 6px;">正在计算...</div>

  <script>
    // 2. 确认 window.turf 已经注入
    if (typeof turf === 'undefined') {
      console.error('Turf.js 加载失败，请检查网络连接或 CDN 地址！');
    } else {
      // 3. 定义两个地理点要素（注意经纬度顺序：[经度 lon, 纬度 lat]）
      const beijing = turf.point([116.4074, 39.9042]);
      const shanghai = turf.point([121.4737, 31.2304]);

      // 4. 计算大圆球面距离，指定单位为千米 (kilometers)
      const options = { units: 'kilometers' };
      const distance = turf.distance(beijing, shanghai, options);

      // 5. 渲染结果
      const resultText = `北京到上海的大圆球面距离约为: ${distance.toFixed(2)} 公里`;
      console.log(resultText);
      document.getElementById('output').innerText = resultText;
    }
  </script>
</body>
</html>

3. 运行验证方法

在本地使用现代浏览器双击打开上述 HTML 文件，或者通过 VS Code 的 Live Server 插件启动。在浏览器开发者工具的 Console 面板中，应该能够看到清晰的输出：

北京到上海的大圆球面距离约为: 1067.78 公里

若控制台报错 turf is not defined，通常是因为 CDN 资源被浏览器插件拦截，或者业务脚本在 CDN 脚本完成下载前就提前执行了。确保业务 <script> 标签位于 CDN 引入标签之后，即可解决加载时序问题。

三、方案二：NPM 工程化安装与现代打包配置

在基于 Vue、React、Svelte 或原生 TypeScript 的工程项目中，更普遍的做法是通过 NPM 安装依赖，由 Vite、Webpack 等构建工具进行模块分析与打包。

1. 方式 A：安装全量包（适合算法密集的探索阶段）

如果你的项目涉及大量的拓扑分析、曲面插值、缓冲区分析等，直接安装全量包最为省心：

npm install @turf/turf

在 ES Module 环境中的引入方式：

// 整体导入为 turf 命名空间
import * as turf from '@turf/turf';

const pt = turf.point([116.4, 39.9]);
const buffered = turf.buffer(pt, 5, { units: 'kilometers' });

优缺点剖析：这种方式的好处是 API 完备，与官方文档保持一致；但缺点在于，@turf/turf 的根入口打包了所有子模块，部分构建工具难以在全量包上做彻底的代码剪裁，可能导致构建出的 Vendor 文件体积超过 500KB。

2. 方式 B：细粒度子模块按需安装（生产推荐实践）

Turf.js 官方建议在生产项目中仅安装实际需要的功能子包。例如，你的地图组件只需要测量两点距离和生成点要素，只需运行：

npm install @turf/distance @turf/helpers

在业务代码中进行精准导入：

// 仅按需引入对应功能模块
import distance from '@turf/distance';
import { point } from '@turf/helpers';

const p1 = point([120.153576, 30.287459]); // 杭州
const p2 = point([121.473701, 31.230416]); // 上海

const dist = distance(p1, p2, { units: 'kilometers' });
console.log('杭州至上海两点间距:', dist.toFixed(2), 'km');

3. TypeScript 类型支持

从 Turf 6.x / 7.x 开始，官方库已经完全采用 TypeScript 重写。无论是全量包 @turf/turf 还是细分子包 @turf/distance，安装后均内置包含了类型声明文件（.d.ts），开发者无需额外安装 @types/turf。

在 TypeScript 文件中，输入要素和参数选项都能获得精确的智能代码补全：

import distance, { Units } from '@turf/distance';
import { point, Feature, Point } from '@turf/helpers';

const unit: Units = 'kilometers';
const startPoint: Feature<Point> = point([113.2644, 23.1291]); // 广州
const endPoint: Feature<Point> = point([114.0579, 22.5431]);   // 深圳

const result: number = distance(startPoint, endPoint, { units: unit });
console.log(`广深相距约: ${result.toFixed(2)} km`);

4. Node.js 服务端环境引入（CommonJS 兼容）

如果你在 Node.js 后端编写空间分析脚本，且项目仍采用 CommonJS 规范，可以通过 require 方式引入：

// CommonJS 环境引入
const distance = require('@turf/distance').default || require('@turf/distance');
const { point } = require('@turf/helpers');

const from = point([-75.343, 39.984]);
const to = point([-75.534, 39.123]);

console.log('距离:', distance(from, to));

四、常见问题与避坑提醒

1. 坐标顺序陷阱：经度在前、纬度在后

这是初学者最容易踩中的错误。日常口语中常说“经纬度”，但在某些非标准地图 SDK（如百度地图、高德地图个别类）中容易混淆。Turf.js 完全严格遵循 GeoJSON 国际规范（RFC 7946），坐标数组永远是 [经度 Longitude, 纬度 Latitude]。

// 正确做法：[经度, 纬度]
const correctPt = turf.point([116.4074, 39.9042]);

// 错误做法：颠倒成 [纬度, 经度]，会导致计算出错误的海域或两极坐标！
const wrongPt = turf.point([39.9042, 116.4074]);

2. 距离单位单位拼写错误

在调用 distance 或 buffer 等涉及空间单位的方法时，参数对象中的 units 字段必须严格使用小写且支持的值：

• 'kilometers' 或 'km'（推荐使用标准的复数名词形式 'kilometers'）
• 'meters' 或 'm'
• 'miles'
• 'degrees' / 'radians'

3. 异步组件或微前端环境下的全局污染排查

在微前端架构中，若子应用 A 使用 CDN 挂载了 window.turf，子应用 B 依赖 NPM 本地构建，可能会出现全局属性覆盖或版本混用的问题。在大型协作项目中，建议统一通过 NPM 显式安装依赖，隔离运行时作用域。

五、引入方案选型建议与总结

通过以上对 CDN 直链与 NPM 工程化打包的全面剖析，可以得出清晰的技术选型结论：

1. 概念验证与独立演示页：优先使用 <script src="https://unpkg.com/@turf/turf@7.2.0/turf.min.js"></script>，开发体验最轻快。
2. 常规中大型 Web 生产项目：坚决采用 npm i @turf/子包名 形式，借助构建工具的 Tree-Shaking 获得最佳的打包效率与更小的加载体积。
3. 全栈与 Node.js 空间批处理脚本：直接在服务端运行子模块，兼顾执行性能与模块隔离。