简介：geotools相关jar包集合是一份面向Java GIS开发者的离线依赖资源，围绕geotools 18.4版本整合核心库及常用配套组件，用于解决在Maven或非Maven工程中接入地理空间数据读写、OGC服务调用、坐标系统转换等能力时的依赖配置问题。压缩包内共247个文件，包含229个jar库、9个md说明文档、5个txt配置与使用指南、3个html页面和1个png图示，整体约87.28MB，既便于本地离线部署，也适合按文档快速查阅。借助这套jar包，开发者可读写Shapefile、GeoJSON、GPKG、PostGIS等矢量数据与TIFF、JPEG等栅格影像，调用WMS、WFS等标准服务，执行空间分析、缓冲区构建、地图渲染及坐标系转换，同时可对接ArcGIS Server发布的服务并处理Esri Shapefile格式，覆盖Web、桌面、移动端多种GIS应用开发场景。资源附带示例数据与官方说明页面，便于对照练习。目前已有1097人学习下载，适合有Java基础、希望快速在项目中集成GIS功能的中高级开发者。
1. geotools相关jar包集合：一次把版本、模块和兼容性讲透
如果你做过Java方向的GIS开发，一定经历过这种场景：按官方文档引一个依赖，Maven却报错找不到包；换个版本号，又和Spring的guava冲突；好不容易跑起来，部署到内网新机器上又缺了一个transitive依赖直接NoClassDefFoundError。geotools相关jar包集合就是这么个绕不开的坎——它是开源的Java GIS工具库，功能从shapefile读写、坐标参考系处理，到空间关系计算、栅格解析都有对应模块，但正因为模块拆得细、版本迭代频繁、依赖链又长，它从来不是一个jar能解决的问题，而是一套jar包集合。这篇就围绕这套jar包集合讲清楚三件事：模块怎么选、版本怎么锁、出了问题怎么定位。
2. 概念先立住：geotools为什么是一堆jar而不是一个jar
2.1 模块化架构：从gt-main到gt-referencing的分层职责
geotools相关jar包集合的底层逻辑是「按功能边界切分」。核心模块是 gt-main，它定义了Feature、FeatureType、DataStore这些最基础的数据模型；你要读shapefile，得有 gt-shapefile；要读GeoJSON，得加 gt-geojson；要做坐标转换，需要 gt-referencing 和 gt-epsg-hsql；要做空间计算，会用到 gt-ows、gt-epsg-extension 这类扩展模块。每个模块被设计成可以独立存在、按需引用，而不是一股脑塞给你一个大而全的包。
理解这个分层对排错至关重要。常见的问题是A同学只引入了gt-shapefile，代码里用到CRS时直接报NoClassDefFoundError: Lorg/geotools/referencing/CRS;——这不是代码错误，而是模块边界没踩准。CRS工具类在 gt-referencing 里，DefaultGeographicCRS等具体定义分散在 gt-epsg-hsql 或 gt-epsg-extension。所以引入jar包集合时，脑子里要先有一张模块地图：读数据、写数据、坐标系、渲染、栅格，各自对应哪几个模块。
2.2 版本线怎么选：稳定版与Java环境的硬约束
geotools的版本号和Java环境强绑定，选错版本等于给自己挖坑。比如某个旧的稳定版默认要求Java 8，到Java 11勉强能跑，但其中某些依赖在Java 16以上的模块化环境下会因javax.measure不在模块路径上报LinkageError。我一般会先确认项目基础环境的JDK主版本，再去选择匹配的geotools版本线。怎么确认？看发布说明里写的「Requires Java XX」，别靠猜。
另一个容易踩的坑是版本号和Maven仓库的对应关系。geotools的release版本在OSGeo的公开仓库能直接拉到，但带-SNAPSHOT的包只发布在快照仓库。很多项目图“新功能”直接写30-SNAPSHOT，结果在公司的私服上只配置了release代理，一构建就404。此外，jar包里还包含依赖的第三方库，比如旧版依赖的commons-lang3、guava，这些和Spring Boot等框架带的版本经常打架，这也是后面要专门排查的重点。所以选版本线时优先选release版本，并且尽量选社区用得最多的那个稳定分支，不要追新。
再说一个实践上的细节：同一套geotools相关jar包集合内部，版本必须完全一致。要么全是31.0，要么全是30.2，绝对不能gt-main用30.x、gt-referencing用29.x这种混搭。因为geotools的release包里各部分是一起编译发布的，跨版本混用会出现方法签名不匹配的NoSuchMethodError，而且这种错误在编译期不报，只要跑到对应方法才会暴露。如果你在工作区里看到一个生效的依赖版本是旧版、另一个模块被传递依赖成新版，那基本就是中了这个问题。
3. 用Maven把geotools相关jar包集合装到本地：最小配置与离线方案
3.1 最小pom配置：osgeo仓库、属性与核心依赖
在日常开发里，最稳妥的引入方式是在pom.xml里集中用一个properties统一管理版本号，并把OSGeo的release仓库显式加上。下面是常见的最小配置骨架，注意仓库地址和依赖版本都要按自己实际环境核对。代码里的${geotools.version}就是那个要锁死的版本号。
<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <geotools.version>替换成你要用的release版本</geotools.version> </properties> <dependencies> <dependency> <groupId>org.geotools</groupId> <artifactId>gt-main</artifactId> <version>${geotools.version}</version> </dependency> <dependency> <groupId>org.geotools</groupId> <artifactId>gt-shapefile</artifactId> <version>${geotools.version}</version> </dependency> <dependency> <groupId>org.geotools</groupId> <artifactId>gt-referencing</artifactId> <version>${geotools.version}</version> </dependency> </dependencies> <repositories> <repository> <id>osgeo-release</id> <name>OSGeo Release Repository</name> <url>https://repo.osgeo.org/repository/release/</url> </repository> </repositories>这段配置的逻辑很简单但有三点值得说明。第一，仓库必须加release仓库，-SNAPSHOT版本走了另一个快照仓库，不加就会遭遇404。第二，核心依赖加三个就够起步：gt-main提供Feature和DataStore模型，gt-shapefile负责shp读写，gt-referencing给坐标系操作兜底。第三，版本用properties统一定义，是为了后面升级时只改一行，避免散落多处导致版本不一致。如果你的业务涉及GeoJSON，就再补一个gt-geojson，涉及栅格就补gt-coverage和gt-geotiff，按需扩张。
3.2 离线环境下导出jar包集合的两个命令
很多时候代码开发完要部署到内网，机器上不能访问外网Maven仓库。这时候需要先在开发机上把整套jar包导出，连同应用一起带过去。“导出”不是把jar从本地仓库复制出来那么简单——需要考虑transitive依赖是否被一起带上，以及最终需要用到的模块有没有在编译后被裁剪。我常用的做法是用Maven内置插件生成一个lib目录。
# 方式一：在项目根目录执行，把运行期所有依赖复制到 ./lib mvn dependency:copy-dependencies -DincludeScope=runtime -DoutputDirectory=./lib # 方式二：深度导出，包含编译期依赖，适合排查缺失 mvn dependency:copy-dependencies -DincludeScope=compile -DoutputDirectory=./lib-all-DincludeScope=runtime是常用参数，它会把运行期要用的jar全部落盘，生成的是包含geotools模块和第三方传递依赖的完整集合。lib-all那个适合在解依赖冲突时用，把编译期scope也拉下来，配合mvn dependency:tree逐一比对。注意：导出之后别直接拿整个lib扔到服务器，一个常见错误是把本地仓库里其他项目引入的不相干jar也混了进去，导致冲突。最稳的做法是先mvn dependency:tree输出依赖清单，按清单比对lib目录。
3.3 完全不用Maven时的手工整理思路
有的老项目是纯Eclipse工程或直接用安装版Tomcat部署，pom.xml也不存在，这时就要手工整理jar包集合。我一般会先把官方发布的zip包（里面是全部jar和依赖说明）解压，再看我们只用哪些模块，手工把对应jar挑出去。这里有一个特别烦人的地方：jar包之间的传递依赖在无Maven环境下不会自动带上，比如gt-shapefile会依赖gt-main，gt-main又依赖gt-metadata、gt-api等。
手工整理的核心是先列功能清单再找jar。比如只需要“读shp并按EPSG:4326做坐标转换”，那么最小集合是gt-shapefile、gt-main、gt-api、gt-metadata、gt-referencing、gt-epsg-hsql再加第三方依赖，比如jts、commons-lang3等。缺少任何一个，启动时都不报错，跑到具体操作才会炸。所以这一步我特别不建议凭猜，而是先在Maven项目里用dependency:tree把真实依赖树跑出来，照着树手工复制jar，复制完再用一个可执行的测试入口做冒烟验证。
4. 避坑：geotools相关jar包集合的5个经典翻车现场
4.1 现象1：NoClassDefFoundError，从接口类到具体实现类
现象：代码在开发机上一个测试用例跑通了，部署到内网机器后一启动就报NoClassDefFoundError: org/geotools/referencing/crs/DefaultGeographicCRS。原因排查下来是内网部署时只拷贝了核心的几个gt jar，没把gt-referencing和gt-epsg-hsql带过去，而接口在gt-api里、具体实现在另一个模块里，两者缺一个都会这样。解决：用mvn dependency:copy-dependencies重新导出完整lib集合，并且核对geotools各模块版本号一致后再部署。
4.2 现象2：坐标系工厂报错，“EPSG:3857 unsupported”
现象：调用CRS.decode("EPSG:3857")时抛出异常，提示找不到对应的坐标系定义。原因：EPSG定义的数据库是由gt-epsg-hsql这个模块提供的，只引了gt-referencing没引gt-epsg-hsql，坐标系列表就是空的，默认只保留几个内置坐标系。解决：在依赖里补gt-epsg-hsql，同时在初始化时用Hints指定强制使用HSQL数据库：
Hints hints = new Hints(Hints.FORCE_LONGITUDE_FIRST_AXIS_ORDER, Boolean.TRUE); ReferencingFactoryFinder.setHints(hints);这段代码里的FORCE_LONGITUDE_FIRST_AXIS_ORDER也是新手高发坑点：默认坐标轴顺序是纬经度，不设置成经度优先，decode("EPSG:4326")出来的坐标是纬度在前，对Google地图这种习惯经度在前的场景直接翻车。这个参数也是我每次初始化必写的。
4.3 现象3：guava和commons-lang3的版本冲突
现象：Spring Boot项目跑起来后，某个geotools功能在调用时抛NoSuchMethodError: com.google.common.collect.ImmutableList.toImmutableList()。原因：Spring Boot的guava版本比geotools期望的版本新，guava内部方法变了，老方法不存在。解决：先mvn dependency:tree定位geotools引用的guava版本，然后在pom里排除geotools的guava依赖或者统一设置guava.version属性，确保全项目只有一个版本。说句公道话，这类冲突不算bug而是自己没lock版本，geotools官方适配的主要是自身jar包集合的内部一致性，外部第三方版本要靠项目层控制。
4.4 现象4：JDK 16以上跑老版本，LinkageError找上javax.measure
现象：升级JDK后，原本正常的坐标转换代码启动就报java.lang.LinkageError: loader constraint violation或NoClassDefFoundError: javax/measure/quantity/Length。原因：geotools旧版依赖的javax.measure库在JDK模块化之后不自动加载了。解决：优先把geotools相关jar包集合整体升级到官方声明支持当前JDK的版本线；如果项目暂时升不了，就手动引入新版javax.measure依赖并排除geotools里旧的那个。这类问题最忌“只加一个jar试试”，错上加错。
4.5 现象5：-SNAPSHOT包在私服上根本拉不到
现象：构建服务器报Could not find artifact org.geotools:gt-main:jar:31-SNAPSHOT。原因：公司私服只代理了release仓库，而SNAPSHOT版本在OSGeo的快照仓库才可下载。解决：如果只是为了功能演示或者连锁依赖，直接用release版本替换；如果确实需要快照的新特性，就得在私服配置里加上快照仓库的代理，并且在pom里单独指定<snapshots><enabled>true</enabled></snapshots>。更稳妥的方案还是那句话：生产项目用release版本。
5. 按业务挑模块：数据读写、坐标转换与空间分析的参数调整
5.1 最小模块清单：按业务在jar包里挑，不一把梭
现在假设你要做的是“读取shapefile，数据里有经纬度和面要素，需要转成EPSG:4326的WGS84坐标，再做简单的相交判断”。这套需求我通常只引四个geotools模块加一个第三方库。geotools这边是gt-shapefile负责shp读写、gt-referencing提供坐标系抽象、gt-epsg-hsql加载EPSG定义、gt-main提供Feature模型。第三方那边是jts-core，空间关系运算的核心库。这么搭出来的jar包集合体积不大，依赖冲突面积也小。
反过来，如果你的业务还要输出GeoJSON给前端，那得加gt-geojson，这个模块会把Feature序列化成GeoJSON结构，省掉手写转换。如果要处理栅格影像，geotools相关jar包集合要扩展出gt-coverage和gt-geotiff，同时对Java的imageio依赖也要注意带上。逐一按业务加模块，比一次性把官方所有jar都塞进lib要靠谱十倍。
5.2 三个必调参数：坐标系工厂、精度与Feature缓存
第一个参数是坐标系轴顺序。就是前文那个FORCE_LONGITUDE_FIRST_AXIS_ORDER，它影响所有坐标系的解码顺序，默认是false，也就是遵循EPSG原始定义（纬度优先）。做互联网地图服务的几乎都要把它设成true。我一般是把它放在静态初始化块里执行一次，全项目生效。下面这个写法在社区里比较常见：
static { Hints hints = new Hints(Hints.FORCE_LONGITUDE_FIRST_AXIS_ORDER, Boolean.TRUE); ReferencingFactoryFinder.setHints(hints); }第二个参数是几何操作的精度模型。它由GeometryFactory在创建几何对象时指定，默认Fixed精度会严格按照坐标数值参与计算，适合测绘数据；但有些业务数据本身带容差，比如做地块合并时几条边有0.001米级别的缝隙，用默认精度模型相交判断永远返回false。这种场景我一般用GeometryFactory携带的PrecisionModel调整为FLOATING，或者干脆在数据预处理阶段做一次buffer(0)容差处理：
Geometry geom = reader.readFeature(feature).getDefaultGeometry(); Geometry bufferedGeom = geom.buffer(0.000001);第三是Feature遍历的性能参数。geotools读取shp时默认用懒加载，一次性读入所有Feature到一个集合再遍历，内存占用会很失控。处理大文件时要在ShapefileDataStore设置System.setProperty("org.geotools.shapefile.files", "true")以及必要时开启内存映射模式。我处理几千万级的点要素时，会直接用FeatureIterator流式访问并手动关闭，避免FeatureCollection被全部落到内存里。这不算“调参”，但确实是最容易让大文件操作内存爆炸的血泪点。
6. 快速验证jar包集合可用的办法与一个值得养成的习惯
验证这套jar包集合是否完整，最快的方法是写一个几十行的小入口去实际读一个shapefile再转坐标，比任何启动时检查都直观。下面这个冒烟测试方法也是我每次做完lib整理后必然跑一遍的最小验证，避免到了项目现场再翻车：
File shpFile = new File("C:/temp/test.shp"); ShapefileDataStore store = new ShapefileDataStore(shpFile.toURI().toURL()); store.setCharset(StandardCharsets.UTF_8); FeatureSource<SimpleFeatureType, SimpleFeature> source = store.getFeatureSource(); Filter filter = CQL.toFilter("BBOX(the_geom, 110, 30, 120, 40)"); FeatureCollection<SimpleFeatureType, SimpleFeature> features = source.getFeatures(filter); try (FeatureIterator<SimpleFeature> iter = features.features()) { int count = 0; while (iter.hasNext()) { SimpleFeature feature = iter.next(); Geometry geom = (Geometry) feature.getDefaultGeometry(); if (geom != null && count == 0) { System.out.println(geom.toText().substring(0, 80)); } count++; } System.out.println("total features: " + count); } store.dispose();代码里CQL.toFilter这句是核心验证点：它同时依赖gt-main里的Filter解析和gt-referencing里的坐标系解析，如果之前那些模块缺失或版本不一致，这里大概率直接抛异常，比单纯启动Spring容器更快暴露问题。store.dispose()释放DataStore是杀招，Windows下文件被占用、后续重写shp失败的场景大多是因为没做这一步。跑完这段，再对照mvn dependency:tree导出的依赖清单抽查几个关键jar，就能确定这套geotools相关jar包集合是否可交付。
我自己的习惯是把这个冒烟类留在项目src/test里，每次切换版本线、调整模块、或者准备发版之前都跑一遍。做GIS开发，空间数据出了问题不像普通表单报错一样直观，很多错误要等数据落到某个具体处理环节才地冒出来，所以必须有一个能在十分钟内确认“基础环境没问题”的底。希望帮到你——下次再整理geotools相关jar包集合，至少不再靠玄学补依赖了。
本文还有配套的精品资源，点击获取
