patch-package，让GIS前端开发告别依赖库 "卡脖子"

作为 GIS 前端开发，日常要跟各种庞大的图形学库打交道：OpenLayers, Leaflet, Mapbox GL JS, Cesium, Turf.js... 这些库动辄几万行代码。不知道大家开发的时候有没有遇到需要修改node_modules中的源码这种情况，比如小编之前的老项目中用到了 OpenLayers 6.x 版本，用到的第三方插件早就不更新了。这时候如果使用新版的插件就要升级 OpenLayers 版本，对于一个已经交付多年的项目来说，这基本是不可能的工作量。

传统的解决方案

如何解决这种问题呢？有很多刚开始接触GIS开发的新手会去直接改 node_modules 里的代码。但这种方法的弊端很明显：本地跑通了，别人一拉代码 npm install，Bug 又回来了；CI/CD 构建的时候直接报错。

另外一种方法，小编常用，就是把整个库下载下来，改完发布一个私有包。但这要求公司有自己的私有NPM仓库，根据小编所知不是所有的公司都有这种基础设施，比如小编所在的公司虽然有私有NPM仓库，但需要申请各种权限，所以小编一般将改动的代码放在一个git仓库，并使用npm + git方式引入到代码仓库。

npm i https://github.com/user_name/node_project_name

更优雅的patch-package

最近小编又遇到了问题，但总用NPM + Git方式引入的库，还是觉得有些麻烦，毕竟每次还是需要去新建仓库，还要配置拉取权限等等。这种问题不可能小编自己遇到，结果一找果然发现了更优雅的解决方案：patch-package

如何使用？

假设项目中使用 Mapbox GL JS 加载 UTM 投影（EPSG:32650）的矢量瓦片，发现缩放级别 10 以上时，POI 标签会偏离要素中心点。排查后定位到mapbox-gl.js中投影转换的坐标计算错误，我们使用 patch-package 应该怎么做？

第一步：安装 patch-package

npm install patch-package --save-dev
# 或者使用 yarn
yarn add patch-package postinstall-postinstall

注：使用 yarn 的同学最好加上 postinstall-postinstall，这是为了确保兼容性。

第二步：直接修改 node_modules

找到项目中node_modules/mapbox-gl/dist/mapbox-gl.js，定位到投影转换相关代码（比如搜索projectToScreen方法），修复坐标计算逻辑：

// 原错误代码（简化示例）
const projected = this.projection.project(coords);
const x = projected.x * this.scale;
const y = projected.y * this.scale;

// 修复后代码（添加UTM投影偏移补偿）
const projected = this.projection.project(coords);
const x = projected.x * this.scale - (this.projection.isUTM ? 10 : 0);
const y = projected.y * this.scale - (this.projection.isUTM ? 5 : 0);

第三步：生成补丁文件

npx patch-package mapbox-gl

执行后会在项目根目录生成patches/mapbox-gl+2.9.1.patch文件，这个文件记录了你的代码修改，一定要提交到 Git 仓库！

第四步：使用补丁

在package.json中添加postinstall脚本，确保每次npm install或yarn install时自动应用补丁：

{
  "scripts": {
    "postinstall": "patch-package" // 新增这行
  }
}

团队其他成员拉取代码后，只需执行npm install，补丁就会自动应用到node_modules中，无需额外操作～

总结

虽然 patch-package 可以解决这个问题，但小编建议不到迫不得已，还是不能滥用，否则会导致代码越来越难以维护。只有在原npm已经停止维护或者紧急上线的时候使用，另外使用的时候一定要注意锁版本，避免出现版本冲突。

你在 GIS 项目中遇到过哪些依赖库坑？欢迎在评论区分享你的解决方案！