如果你正在做前端地图可视化、数据治理或者给业务部门维护底图数据应该能体会 GeoJSON 文件里那些“看起来没毛病、一上线就出问题”的坑坐标数组少了一对括号、Feature 里漏掉 geometry、properties 字段名不统一、投影坐标没有声明。这类错误在浏览器里往往不会直接抛异常而是变成地图白屏、图层偏移或者样式错乱最后查半天才发现是数据源的问题。GeoLint 就是你在这个场景下的一个辅助工具一个面向 GeoJSON 的 ESLint 风格校验器linter用规则化、可配置的方式把地理数据里的结构性问题提前挡在开发和发布流程之外。很多人已经把 ESLint 当作前端工程的标配但地理数据这一侧的自动检查一直比较原始。GeoJSON 本身是具备空间语义的 JSON结构上和前端对象很相似但真正用起来它比普通 JSON 多了一整套坐标、几何类型、投影和拓扑规范。GeoLint 的思路就是把 ESLint 的“规则可配置、错误可定位、结果可自动化”这套机制原样搬到 GeoJSON 上。这篇文章会从 GeoJSON 数据格式的设计讲起分析数据文件为什么会出错、GeoLint 解决了哪些问题再带你走一遍环境准备、命令行启动、规则配置、批量校验和 CI 接入的完整流程最后给出针对性和可落地的排查清单与最佳实践。1. 核心能力速览先看一个概览方便你快速判断这个工具适不适合进入你现有的技术栈和数据处理流程能力项说明项目类型面向 GeoJSON 数据的命令行静态校验工具linter整体设计参考 ESLint 的规则机制解决的问题GeoJSON 文件结构错误、几何类型异常、属性字段缺失或命名不一致、坐标精度与范围异常等使用方式命令行CLI可以在终端中直接运行也可以接入脚本、构建流程和 CI/CD配置方式配置文件声明规则支持开启、关闭或调整规则级别适合团队统一规范批量任务支持通过通配符或目录遍历多个 GeoJSON 文件适合数据目录和前端素材目录批量检查与编辑器关系可直接处理原生 .geojson / .json 文件也可以配合 VS Code、geojson.io、QGIS 等工具使用硬件要求无需 GPU普通开发机即可运行主要依赖 CPU 和内存平台支持依赖 Node.js 环境通常跨平台可用具体以项目 README 说明为准是否提供修复能力取决于项目是否内置 fix 子命令或自动修复规则常见 lint 工具会提供相关扩展需按实际文档确认适合场景前端地图开发、数据治理、底图发布前置检查、团队数据规范落地、地理数据类开源项目维护从表格里能看出GeoLint 的工具定位很明确不替代 QGIS 这样的地理信息处理和可视化工具也不替代 geojson.io 这类在线预览站点而是作为“自动检查”的那一层负责在数据进入渲染管线之前发现明显和不明显的结构问题。2. 适用场景与使用边界2.1 适合谁第一类用户是前端工程师尤其是做地图可视化、WebGIS、数据大屏的开发同学。这类场景里 GeoJSON 文件通常来源于第三方数据平台、后端接口或设计同事导出的底图文件到手后如果手动打开很难一眼看出坐标范围超出中国范围还是属性字段缺失。GeoLint 能把这些检查写成固定规则集成到 npm scripts 里每次拿到数据先跑一遍命令再交给渲染层。第二类是数据工程师和数据分析师。他们经常要下载和转换各种地理数据源可能从省份边界、城市轮廓、路网、POI 数据等不同来源收集 GeoJSON 文件。这类数据往往格式来源混杂字段命名风格不统一几何类型忽而是 Polygon 忽而是 MultiPolygon。GeoLint 适合做“入库前校验”和“字段规范统一”的第一道关卡。第三类是开源项目维护者、数据包维护者和团队技术负责人。当一个数据仓库或前端物料库包含几十上百个 GeoJSON 文件时人工 Review 已经不可靠。配置一套标准规则后在 Git 提交或 CI 阶段自动运行能显著降低脏数据合入主分支的概率。2.2 能解决什么问题结构完整性检查文件是否是合法的 GeoJSONFeature、FeatureCollection、GeometryCollection 等顶层类型是否符合规范。几何坐标合法性坐标数组中经度、纬度的数值范围是否符合真实地理坐标例如经度 -180 到 180纬度 -90 到 90坐标层级嵌套关系是否匹配几何类型。属性字段一致性校验 properties 中固定字段是否存在、字段类型是否一致、编码是否有问题。投影坐标系声明如果数据来自第三方来源坐标是否统一到 WGS84EPSG:4326或者是否在数据说明中明确标出投影。文件级规范统一比如是否允许单个 Feature 文件、是否要求统一使用 FeatureCollection、文件后缀名和文件名规范等。2.3 不适合什么场景GeoLint 不负责帮你完成几何拓扑运算比如检查坐标点是否落在某个多边形内部、线要素是否自相交、多个面之间是否存在缝隙这些属于空间分析工具和拓扑校验工具的专业范围。它也不做地理数据格式转换GeoJSON 转 TopoJSON、转 Shapefile、转 MBTiles 等需求需要搭配其他工具链处理。另外GeoLint 解决的是“数据结构对不对”的问题不解决“数据内容准不准”的问题——一个合法坐标并不能保证这个坐标代表的边界是正确的。2.4 数据合规与使用边界使用 GeoJSON 数据时尤其是从网上下载的政区边界、道路路网、POI 数据需要注意数据版权和授权范围。边界位置可能涉及测绘成果部分数据来源有严格的发布限制商用场景下要确认许可条款。中国境内地理数据的采集、处理和发布还必须符合测绘地理信息相关法规涉及涉密信息的素材不能通过普通工具链处理和传播。这篇文章只讨论技术校验方法实际使用中请务必确认数据来源合法、授权明确、发布内容不涉及敏感信息。3. GeoJSON 数据格式与 GeoLint 的关系搜索“geojson 数据格式”“geojson 用什么软件打开”这类问题的读者通常正处在“手上有文件但不知道怎么检查”的阶段。GeoJSON 本质上是一个基于 JSON 的开放标准格式用于表达地理要素及其属性。最简单的 GeoJSON 文件是一个包含type和coordinates字段的几何对象完整的地理数据文件则通常是一个FeatureCollection下面包含多个Feature每个 Feature 里有geometry和properties。一个典型的 GeoJSON 对象大致是这个样子{ type: FeatureCollection, features: [ { type: Feature, properties: { name: 示例区域, code: 10001 }, geometry: { type: Polygon, coordinates: [ [ [116.0, 40.0], [117.0, 40.0], [117.0, 41.0], [116.0, 41.0], [116.0, 40.0] ] ] } } ] }从数据结构看GeoJSON 很规整但恰恰因为“看起来只是普通 JSON”很多人会忽略它的空间语义直接把数组当成普通嵌套数组来拼。前端常见的错误包括Polygon 的坐标数组层次少一层、环没有闭合、经纬度顺序写反、properties字段缺失、坐标数组里有空元素等。这类错误不会导致 JSON 解析失败所以直接用JSON.parse很难发现只有在渲染地图时才暴露出来。GeoLint 的切入点就在这里。它和 ESLint 解决的问题本质上是同一类问题ESLint 检查 JavaScript 代码的语法和风格问题GeoLint 检查 GeoJSON 数据的结构和规范问题。两者都遵循“规则驱动”思路规则是可插拔、可配置、可单独关闭的规则执行结果会指出文件路径、行列位置、规则名称和错误描述方便开发者在命令行里快速定位。理解了这层对应关系你就不难推测 GeoLint 的基础使用路径安装工具、准备配置、运行命令、查看报告在拿到具体错误之后再回到源文件修改。关于“geojson 用什么软件打开”这个问题值得多说一句。GeoJSON 是纯文本格式VS Code、Sublime Text 等编辑器都能直接当 JSON 打开需要看图形效果时可以用 geojson.io 在线拖拽预览或用 QGIS、kepler.gl 这类地理数据工具加载。GeoLint 的定位不是替代这些工具而是在它们之前先做一次机械化检查形成“编辑器打开 可视化预览 命令行自动校验”的组合工作流。4. 环境准备与前置条件作为命令行工具GeoLint 的部署成本比数据可视化平台低得多硬件门槛也很低。只要有一台普通的开发电脑不需要独立显卡不需要额外部署服务也不需要准备大量磁盘空间。重点要检查的是软件环境。4.1 基础环境检查清单操作系统Windows、macOS、Linux 都可以作为主环境具体支持范围以项目 README 为准。Node.js 环境GeoLint 如果是基于 Node.js 开发的 npm 包就需要本地有 Node.js 和 npm建议先在本机执行node -v和npm -v确认版本。终端工具Windows 下建议使用 PowerShell 或 Windows TerminalmacOS/Linux 使用系统自带终端。文件准备准备一个待校验的 .geojson 或 .json 文件可以先准备一个故意写错的测试文件。编辑器可选VS Code 打开 JSON 文件查看结构比较方便。4.2 确认 Node.js 环境node -v npm -v如果系统还没有 Node.js可以前往 Node.js 官网下载 LTS 版本。这里不需要特定大版本只要你本机的 Node.js 能顺利运行 npm 包即可。安装完成后重新打开终端再次执行上面的命令看到版本号输出就说明环境正常。4.3 准备测试文件建议按下面的目录结构准备一个最小测试项目方便验证geo-project/ ├── data/ │ ├── city.geojson │ └── region.geojson └── .geolintrc.jsondata目录放待检查的 GeoJSON 文件项目根目录放配置文件。第一次测试时可以故意把一个 Polygon 的坐标层次改错或者删掉properties字段这样能更直观地看到 lint 工具的输出效果。5. 安装部署与启动方式5.1 通过 npm 安装GeoLint 的正常安装路径是使用 Node.js 的包管理器。如果项目尚未初始化可以先执行npm init -y然后在项目内安装。以常见的 npm 包处理方式为例安装命令大概是npm install --save-dev geolint如果想全局使用也可以尝试npm install -g geolint注意这里的geolint包名是参照常见的 linter 工具写法进行的示意实际安装时请以项目 README 中给出的准确包名为准。安装完成后可以通过执行不带参数的命令来确认工具是否就绪例如npx geolint --help如果能输出帮助信息、可用参数和配置文件查找逻辑说明安装成功。5.2 命令行启动lint 类工具的基本工作方式是一致输入一个或多个文件路径工具读取配置核心引擎按规则逐一执行最后输出报告。GeoLint 的基础命令用法可以参照这个模板npx geolint ./data/*.geojson --config .geolintrc.json这个命令表示检查data目录下所有.geojson文件使用根目录的.geolintrc.json作为规则配置。实际项目中你需要根据 GeoLint 支持的参数替换--config和其他选项比如是否输出 JSON 格式结果、是否只显示error级别、是否进入自动修复模式。如果你已经在项目里安装了本地依赖并且不希望npx去远端查找也可以直接写geolint。5.3 通过 npm scripts 启动日常开发中把 linter 命令写入 package.json 脚本更便于团队复用{ scripts: { lint:geo: geolint ./data/**/*.geojson, check:geo: geolint ./data } }这样执行npm run lint:geo就能跑一遍数据校验也方便接进pre-commit、pre-push等流程。5.4 其他启动方式部分命令行工具会提供 Docker 镜像方便在隔离环境中执行避免污染开发机 Node 环境。如果 GeoLint 项目提供了官方 Docker 镜像你可以参照镜像仓库的说明运行容器。以通用格式为例docker run --rm -v $(pwd)/data:/data geolint-image /data/*.geojson这里的镜像名需要替换成项目实际发布名$(pwd)/data是本地数据目录挂载到容器内/data的路径。Docker 方式更适合在 CI 里使用本地开发阶段建议直接用 npm 方式省去容器本身占用的额外时间和资源。6. 规则配置与校验逻辑GeoLint 和 ESLint 的相似之处不只是名字更重要的是配置和规则设计哲学。ESLint 允许插件通过rules对象配置每条规则的打开状态GeoLint 很可能也遵循同样的思路。如果你拿到项目后文档里写了具体规则名以文档为准下面给出的是从 ESLint 经验推导出的通用示例配置方便你快速理解这种工具应该怎么把规则落到项目里。6.1 一个配置示例{ rules: { no-invalid-geometry-type: error, no-missing-coordinates: error, no-empty-feature-collection: error, require-properties: { level: error, options: { requiredFields: [name, code] } }, coordinate-range: { level: error, options: { longitude: [-180, 180], latitude: [-90, 90] } }, feature-collection-only: warn, no-duplicate-feature: warn } }这里的规则名和参数都是示意性的为的是说明三类常用配置简单开关型规则比如error或warn。带自定义参数的规则比如require-properties指定必须存在的属性字段。带数值边界的规则比如coordinate-range指定经纬度范围。配置文件的格式大概率会支持 JSON也可能同时支持 JS、YAML。如果你的项目同时存在多个数据目录还可能有overrides或按目录覆盖配置的机制类似 ESLint 对不同目录应用不同规则。6.2 规则级别与输出行为linter 的规则级别通常分三级。off表示关闭规则不参与校验warn表示校验到问题时只给警告不改变进程退出码error表示校验到问题时在输出中报错并且在存在至少一个 error 的情况下让进程返回非零退出码。这个机制非常重要因为 CI 里能否拦截提交本质上依赖退出码。调试阶段建议先开warn看报告再逐步调整正式接入团队流程后把必须守住的规则开成error。6.3 自定义规则如果你团队有内部数据规范比如所有政区边界数据的properties里必须包含adcode和level默认规则很可能覆盖不到。ESLint 社区的做法是写自定义规则插件GeoLint 如果具备扩展接口理论上也支持类似能力。建议你阅读项目文档中与“自定义规则”“插件”“访问器”相关的内容看是否支持往配置对象里注入额外的验证函数。写自定义规则时要注意输出信息要包含文件路径和明确的问题描述避免把错误判定逻辑写得过于宽松或过于严格。7. 功能测试与校验效果验证工具安装完成、配置准备好之后重点就是实际跑一遍。下面是按“最小验证 - 多文件验证 - 修复验证 - 配置调整”四个阶段展开的测试流程。7.1 最小验证故意写坏一个文件测试目的确认 GeoLint 能正确解析文件、执行规则并输出错误位置。操作步骤在 data 目录创建bad.geojson文件。写入一个缺少coordinates或坐标层次错误的 Feature。执行校验命令。观察输出结果。预期结果命令行输出中会出现错误描述、规则名和发生错误的数据位置如果写入了致命错误进程退出码应为非零。判断成功标准你能在输出里定位到具体文件和问题类型而不是只得到一个抽象的解析异常。7.2 多文件批量校验测试目的验证 GeoLint 能否正确处理一个目录下的多个 GeoJSON 文件。操作步骤npx geolint ./data/如果项目支持 glob 通配符也可以试试npx geolint ./data/**/*.geojson预期结果工具按顺序遍历所有文件逐个输出每个文件的校验报告而不是遇到第一个坏文件就终止。判断成功标准报告中能看到每个文件名的独立分组并且能统计出文件总数和错误总数。7.3 自动修复验证如果 GeoLint 提供了--fix或类似子命令可以验证自动修复能力。自动修复通常只处理确定性、无歧义的错误比如删除多余的分号、补齐空数组这对应到 GeoJSON 可能就是补齐括号、统一缩进或移除空 Feature。测试时先备份原始文件运行修复命令后再运行一次不带--fix的检查命令看错误数量是否下降。如果修复没有生效说明对应规则不支持自动修复需要手动改文件。7.4 配置调整验证测试目的验证配置文件的优先级和覆盖行为。操作步骤在项目根目录先创建一个只包含“空 FeatureCollection”警告的配置再在子目录创建一份把它改为error的配置然后分别运行命令。预期结果子目录下的 GeoJSON 文件按更严格的配置执行根目录文件按宽松配置执行。如果项目不支持多配置覆盖这个测试会出现相同结果这时需要考虑把数据按目录拆成多个 npm script 分头执行。7.5 验证阶段容易踩的坑配置文件没被读取检查文件名和所在目录是否匹配工具约定。规则名写错配置里写一个不存在的规则名工具可能直接报配置错误也可能静默忽略这取决于实现。文件路径里有中文或空格命令行执行时注意加引号。多个文件里第一个就报错导致后面没继续跑观察工具是“单文件失败即终止”还是“全部文件跑完再汇总”。8. 批量任务与工作流集成对于前端项目来说GeoJSON 文件的规模通常不会特别大因此 GeoLint 的批量任务更多是指“一次命令跑完整个数据目录”和“在自动流程里无人工介入地执行”。8.1 目录级批量检查建议按数据类型组织目录结构例如src/ assets/ geo/ boundary/ road/ poi/然后配置三个 npm script分别检查三个子目录。这样当数据局部变化时可以只跑对应子目录节省时间。如果数据量很大检查脚本可以配合globby、fast-glob这类文件遍历工具先过滤出变更过的文件列表再逐个执行 GeoLint。更稳妥的做法是先用单个文件测试新的规则和配置再把数据目录加进批量任务。8.2 接入 Git hooks如果你使用 Husky 管理 Git hooks可以在pre-commit阶段运行npx geolint ./src/assets/geo提交前发现数据问题会直接阻塞提交适合对数据准确性要求较高的项目。如果不想严格阻塞也可以先用warn级别观察一段时间。8.3 接入 CI/CD在 GitHub Actions、GitLab CI 或 Jenkins 中GeoGeoJSON 校验可以放在构建之前的独立 Job 里。以 GitHub Actions 为例可以写一个类似下面的步骤文件名和包名需要替换为实际值name: geojson-lint on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install - run: npm run lint:geo这样每一次代码推送都会自动检查 GeoJSON 数据文件。对于团队成员素质不一、经常不小心提交错误数据的项目这一步能明显减少“测试环境正常、部署后地图空白”的问题。8.4 批处理中的失败重试与日志当文件数量很多时建议把命令输出重定向到日志文件方便后续排查npx geolint ./data lint-result.log 21也可以让脚本在失败时输出 JSON 报告再写一个简单脚本解析失败文件清单。如果 GeoLint 支持退出码区分“有警告”“有错误”“无问题”那么在批处理脚本里可以针对不同退出码做不同动作。9. 资源占用与性能观察GeoLint 是命令行工具不涉及 GPU 和显存资源占用主要集中在 CPU 和内存上运行窗口很短。它更适合和 ESLint 做类比解析一个普通规模的 GeoJSON 文件性能瓶颈通常不在单个文件的大小而在文件数量和规则复杂度。观察方法执行time npx geolint ./data查看命令总耗时。在任务管理器Windows或topLinux/macOS里观察 Node.js 进程的内存占用确认没有内存持续上涨的异常。用一个超大 GeoJSON 文件几十 MB 或上百 MB测试看是否能正常完成校验、是否出现内存溢出。如果你发现校验速度慢可以从三个方向排查文件是否过大、规则是否写得太复杂、是否每次启动都重新加载整个项目依赖。对于超大文件linter 并不是最优手段更专业的做法是用 OGR/GDAL 等空间数据处理工具做并行化的数据质量检查。日常开发场景下GeoJSON 文件通常都在几 MB 以内GeoLint 的启动时间和执行时间完全可以接受。值得注意的一个点是不要把 GeoLint 放进热更新或浏览器运行时。它是开发期工具不是运行时工具。前端打包时不应该把 linter 的规则逻辑打进生产 bundle。10. 常见问题与排查方法问题现象可能原因排查方式解决方案运行geolint提示 command not found全局安装失败或当前项目依赖未安装执行npm list geolint查看包是否在依赖列表里重新npm install或改用npx geolint配置文件没生效规则都没有执行配置文件路径错误或文件格式不支持检查命令中--config路径确认配置文件扩展名把配置移动到项目约定的默认名或改用支持的格式检查时报 JSON 解析错误文件本身不是合法的 JSON或文件里有 BOM 头、多余逗号用 VS Code 打开文件查看 JSON 语法是否标红先修复 JSON 语法再跑 GeoLint坐标范围没有报错但数据明显不对没有启用坐标范围规则或经纬度顺序写反但数值恰好在范围内查看当前配置里是否包含范围规则对比源数据标记的经纬度顺序在配置中开启坐标范围规则并明确坐标顺序约定中文属性值乱码或显示异常文件编码不是 UTF-8或 Windows 下终端编码不一致用文本编辑器查看文件编码将文件转为 UTF-8 无 BOM 格式命令行报Permission denied全局安装目录权限不足检查 npm 全局目录权限使用本地依赖方式安装避免用 sudo 强行安装CLI 输出太啰嗦看不清楚哪些是错误没有设置输出格式或级别过滤查看帮助文档确认是否支持--quiet、--format只显示error级别或输出到文件再查看CI 里跑不过但本地没有问题CI 环境 Node 版本不一致或依赖未装全查看 CI 日志确认 Node 版本和安装步骤在 CI 中固定 Node 版本先npm ci再运行校验--fix执行后错误数量没有变化对应错误不支持自动修复或修复规则未开启看报告里是否标注“可修复”标记手动修改文件或把修复规则单独配置排查的总原则很简单先确认“文件本身是否合法 JSON”再确认“规则是否被正确读到”最后看“退出码是否符合预期”。绝大部分问题都出在这三层的某一层上。11. 最佳实践与使用建议11.1 从最小规则集开始不要第一次就把所有规则全部开成error。GeoJSON 数据太复杂不同来源的数据规范差异很大第一次全开大概率会让团队产生抵触情绪。建议先启用 4 到 6 条最能兜底错误的规则比如合法几何类型、坐标存在性、FeatureCollection 结构、坐标范围等跑通后再按团队规范加码。11.2 保留一份“最小可运行配置”把 GeoLint 配置、示例 GeoJSON 文件、安装命令写进项目 README。新成员拿到项目后不用看完整文档先跑一遍示例就能理解这个工具做了什么。这也方便你在未来升级或换工具时快速恢复流水线。11.3 数据、配置、报告分目录管理建议按下面的结构维护数据工程目录geo-project/ ├── data/ # 原始 GeoJSON 数据 ├── config/ # GeoLint 配置 ├── reports/ # 校验报告 └── scripts/ # 批量处理脚本reports目录建议加入.gitignore因为校验报告是过程产物不应该频繁提交进仓库但可以在 CI 里作为 Artifact 保留一份便于追溯当前主分支的数据质量。11.4 批量任务必须加日志和退出码判断写脚本的时候不要只执行一条裸命令至少要把退出码打印出来把日志保留到文件。这样即使某天任务卡住或失败你也能从日志里看到是哪一批数据、哪一条规则出问题。11.5 数据授权和合规提醒无论在你的项目里使用 GeoLint 校验多少遍都无法替代对数据来源合法性的判断。下载公开 GeoJSON 文件时注意查看数据提供方的许可协议发布或商用前确认数据是否包含受限制的测绘信息涉及个人位置数据时必须遵守隐私保护相关法律不能因为数据格式上合法就忽略使用场景是否合法。12. 总结与下一步GeoLint 最值得尝试的点是把 ESLint 那套成熟的规则引擎思路带进了 GeoJSON 数据质量检查让原本靠肉眼和经验判断的地理数据问题变成了可以自动执行、自动读报告、自动阻塞流程的工程化能力。建议你先准备一个破坏过的 GeoJSON 文件安装工具后跑一遍最小校验验证它能不能准确定位到你故意埋下的错误再去阅读项目文档里的规则列表按团队数据规范自定义配置。最容易踩的坑是“配置了但没生效”和“规则开太猛导致噪音太多”前者多查路径和文件名字后者从最小规则集起步。如果 GeoLint 项目本身还在早期阶段你可以重点观察它的规则扩展方式是否灵活、输出格式是否符合 CI 需求再用几套真实数据样本做压测。后续可以扩展的方向包括把 GeoLint 接入 ESLint 生态做成 frontend 工具体系的一环、为上线的地图素材增加数据版本校验、结合自动化测试在每次构建后自动生成数据质量报告。对于手头有成百上千个 GeoJSON 文件的项目先在数据侧建立标准再谈可视化效果是性价比很高的做法。建议收藏备用。 GeoLint：用ESLint规则引擎校验GeoJSON数据质量
如果你正在做前端地图可视化、数据治理或者给业务部门维护底图数据应该能体会 GeoJSON 文件里那些“看起来没毛病、一上线就出问题”的坑坐标数组少了一对括号、Feature 里漏掉 geometry、properties 字段名不统一、投影坐标没有声明。这类错误在浏览器里往往不会直接抛异常而是变成地图白屏、图层偏移或者样式错乱最后查半天才发现是数据源的问题。GeoLint 就是你在这个场景下的一个辅助工具一个面向 GeoJSON 的 ESLint 风格校验器linter用规则化、可配置的方式把地理数据里的结构性问题提前挡在开发和发布流程之外。很多人已经把 ESLint 当作前端工程的标配但地理数据这一侧的自动检查一直比较原始。GeoJSON 本身是具备空间语义的 JSON结构上和前端对象很相似但真正用起来它比普通 JSON 多了一整套坐标、几何类型、投影和拓扑规范。GeoLint 的思路就是把 ESLint 的“规则可配置、错误可定位、结果可自动化”这套机制原样搬到 GeoJSON 上。这篇文章会从 GeoJSON 数据格式的设计讲起分析数据文件为什么会出错、GeoLint 解决了哪些问题再带你走一遍环境准备、命令行启动、规则配置、批量校验和 CI 接入的完整流程最后给出针对性和可落地的排查清单与最佳实践。1. 核心能力速览先看一个概览方便你快速判断这个工具适不适合进入你现有的技术栈和数据处理流程能力项说明项目类型面向 GeoJSON 数据的命令行静态校验工具linter整体设计参考 ESLint 的规则机制解决的问题GeoJSON 文件结构错误、几何类型异常、属性字段缺失或命名不一致、坐标精度与范围异常等使用方式命令行CLI可以在终端中直接运行也可以接入脚本、构建流程和 CI/CD配置方式配置文件声明规则支持开启、关闭或调整规则级别适合团队统一规范批量任务支持通过通配符或目录遍历多个 GeoJSON 文件适合数据目录和前端素材目录批量检查与编辑器关系可直接处理原生 .geojson / .json 文件也可以配合 VS Code、geojson.io、QGIS 等工具使用硬件要求无需 GPU普通开发机即可运行主要依赖 CPU 和内存平台支持依赖 Node.js 环境通常跨平台可用具体以项目 README 说明为准是否提供修复能力取决于项目是否内置 fix 子命令或自动修复规则常见 lint 工具会提供相关扩展需按实际文档确认适合场景前端地图开发、数据治理、底图发布前置检查、团队数据规范落地、地理数据类开源项目维护从表格里能看出GeoLint 的工具定位很明确不替代 QGIS 这样的地理信息处理和可视化工具也不替代 geojson.io 这类在线预览站点而是作为“自动检查”的那一层负责在数据进入渲染管线之前发现明显和不明显的结构问题。2. 适用场景与使用边界2.1 适合谁第一类用户是前端工程师尤其是做地图可视化、WebGIS、数据大屏的开发同学。这类场景里 GeoJSON 文件通常来源于第三方数据平台、后端接口或设计同事导出的底图文件到手后如果手动打开很难一眼看出坐标范围超出中国范围还是属性字段缺失。GeoLint 能把这些检查写成固定规则集成到 npm scripts 里每次拿到数据先跑一遍命令再交给渲染层。第二类是数据工程师和数据分析师。他们经常要下载和转换各种地理数据源可能从省份边界、城市轮廓、路网、POI 数据等不同来源收集 GeoJSON 文件。这类数据往往格式来源混杂字段命名风格不统一几何类型忽而是 Polygon 忽而是 MultiPolygon。GeoLint 适合做“入库前校验”和“字段规范统一”的第一道关卡。第三类是开源项目维护者、数据包维护者和团队技术负责人。当一个数据仓库或前端物料库包含几十上百个 GeoJSON 文件时人工 Review 已经不可靠。配置一套标准规则后在 Git 提交或 CI 阶段自动运行能显著降低脏数据合入主分支的概率。2.2 能解决什么问题结构完整性检查文件是否是合法的 GeoJSONFeature、FeatureCollection、GeometryCollection 等顶层类型是否符合规范。几何坐标合法性坐标数组中经度、纬度的数值范围是否符合真实地理坐标例如经度 -180 到 180纬度 -90 到 90坐标层级嵌套关系是否匹配几何类型。属性字段一致性校验 properties 中固定字段是否存在、字段类型是否一致、编码是否有问题。投影坐标系声明如果数据来自第三方来源坐标是否统一到 WGS84EPSG:4326或者是否在数据说明中明确标出投影。文件级规范统一比如是否允许单个 Feature 文件、是否要求统一使用 FeatureCollection、文件后缀名和文件名规范等。2.3 不适合什么场景GeoLint 不负责帮你完成几何拓扑运算比如检查坐标点是否落在某个多边形内部、线要素是否自相交、多个面之间是否存在缝隙这些属于空间分析工具和拓扑校验工具的专业范围。它也不做地理数据格式转换GeoJSON 转 TopoJSON、转 Shapefile、转 MBTiles 等需求需要搭配其他工具链处理。另外GeoLint 解决的是“数据结构对不对”的问题不解决“数据内容准不准”的问题——一个合法坐标并不能保证这个坐标代表的边界是正确的。2.4 数据合规与使用边界使用 GeoJSON 数据时尤其是从网上下载的政区边界、道路路网、POI 数据需要注意数据版权和授权范围。边界位置可能涉及测绘成果部分数据来源有严格的发布限制商用场景下要确认许可条款。中国境内地理数据的采集、处理和发布还必须符合测绘地理信息相关法规涉及涉密信息的素材不能通过普通工具链处理和传播。这篇文章只讨论技术校验方法实际使用中请务必确认数据来源合法、授权明确、发布内容不涉及敏感信息。3. GeoJSON 数据格式与 GeoLint 的关系搜索“geojson 数据格式”“geojson 用什么软件打开”这类问题的读者通常正处在“手上有文件但不知道怎么检查”的阶段。GeoJSON 本质上是一个基于 JSON 的开放标准格式用于表达地理要素及其属性。最简单的 GeoJSON 文件是一个包含type和coordinates字段的几何对象完整的地理数据文件则通常是一个FeatureCollection下面包含多个Feature每个 Feature 里有geometry和properties。一个典型的 GeoJSON 对象大致是这个样子{ type: FeatureCollection, features: [ { type: Feature, properties: { name: 示例区域, code: 10001 }, geometry: { type: Polygon, coordinates: [ [ [116.0, 40.0], [117.0, 40.0], [117.0, 41.0], [116.0, 41.0], [116.0, 40.0] ] ] } } ] }从数据结构看GeoJSON 很规整但恰恰因为“看起来只是普通 JSON”很多人会忽略它的空间语义直接把数组当成普通嵌套数组来拼。前端常见的错误包括Polygon 的坐标数组层次少一层、环没有闭合、经纬度顺序写反、properties字段缺失、坐标数组里有空元素等。这类错误不会导致 JSON 解析失败所以直接用JSON.parse很难发现只有在渲染地图时才暴露出来。GeoLint 的切入点就在这里。它和 ESLint 解决的问题本质上是同一类问题ESLint 检查 JavaScript 代码的语法和风格问题GeoLint 检查 GeoJSON 数据的结构和规范问题。两者都遵循“规则驱动”思路规则是可插拔、可配置、可单独关闭的规则执行结果会指出文件路径、行列位置、规则名称和错误描述方便开发者在命令行里快速定位。理解了这层对应关系你就不难推测 GeoLint 的基础使用路径安装工具、准备配置、运行命令、查看报告在拿到具体错误之后再回到源文件修改。关于“geojson 用什么软件打开”这个问题值得多说一句。GeoJSON 是纯文本格式VS Code、Sublime Text 等编辑器都能直接当 JSON 打开需要看图形效果时可以用 geojson.io 在线拖拽预览或用 QGIS、kepler.gl 这类地理数据工具加载。GeoLint 的定位不是替代这些工具而是在它们之前先做一次机械化检查形成“编辑器打开 可视化预览 命令行自动校验”的组合工作流。4. 环境准备与前置条件作为命令行工具GeoLint 的部署成本比数据可视化平台低得多硬件门槛也很低。只要有一台普通的开发电脑不需要独立显卡不需要额外部署服务也不需要准备大量磁盘空间。重点要检查的是软件环境。4.1 基础环境检查清单操作系统Windows、macOS、Linux 都可以作为主环境具体支持范围以项目 README 为准。Node.js 环境GeoLint 如果是基于 Node.js 开发的 npm 包就需要本地有 Node.js 和 npm建议先在本机执行node -v和npm -v确认版本。终端工具Windows 下建议使用 PowerShell 或 Windows TerminalmacOS/Linux 使用系统自带终端。文件准备准备一个待校验的 .geojson 或 .json 文件可以先准备一个故意写错的测试文件。编辑器可选VS Code 打开 JSON 文件查看结构比较方便。4.2 确认 Node.js 环境node -v npm -v如果系统还没有 Node.js可以前往 Node.js 官网下载 LTS 版本。这里不需要特定大版本只要你本机的 Node.js 能顺利运行 npm 包即可。安装完成后重新打开终端再次执行上面的命令看到版本号输出就说明环境正常。4.3 准备测试文件建议按下面的目录结构准备一个最小测试项目方便验证geo-project/ ├── data/ │ ├── city.geojson │ └── region.geojson └── .geolintrc.jsondata目录放待检查的 GeoJSON 文件项目根目录放配置文件。第一次测试时可以故意把一个 Polygon 的坐标层次改错或者删掉properties字段这样能更直观地看到 lint 工具的输出效果。5. 安装部署与启动方式5.1 通过 npm 安装GeoLint 的正常安装路径是使用 Node.js 的包管理器。如果项目尚未初始化可以先执行npm init -y然后在项目内安装。以常见的 npm 包处理方式为例安装命令大概是npm install --save-dev geolint如果想全局使用也可以尝试npm install -g geolint注意这里的geolint包名是参照常见的 linter 工具写法进行的示意实际安装时请以项目 README 中给出的准确包名为准。安装完成后可以通过执行不带参数的命令来确认工具是否就绪例如npx geolint --help如果能输出帮助信息、可用参数和配置文件查找逻辑说明安装成功。5.2 命令行启动lint 类工具的基本工作方式是一致输入一个或多个文件路径工具读取配置核心引擎按规则逐一执行最后输出报告。GeoLint 的基础命令用法可以参照这个模板npx geolint ./data/*.geojson --config .geolintrc.json这个命令表示检查data目录下所有.geojson文件使用根目录的.geolintrc.json作为规则配置。实际项目中你需要根据 GeoLint 支持的参数替换--config和其他选项比如是否输出 JSON 格式结果、是否只显示error级别、是否进入自动修复模式。如果你已经在项目里安装了本地依赖并且不希望npx去远端查找也可以直接写geolint。5.3 通过 npm scripts 启动日常开发中把 linter 命令写入 package.json 脚本更便于团队复用{ scripts: { lint:geo: geolint ./data/**/*.geojson, check:geo: geolint ./data } }这样执行npm run lint:geo就能跑一遍数据校验也方便接进pre-commit、pre-push等流程。5.4 其他启动方式部分命令行工具会提供 Docker 镜像方便在隔离环境中执行避免污染开发机 Node 环境。如果 GeoLint 项目提供了官方 Docker 镜像你可以参照镜像仓库的说明运行容器。以通用格式为例docker run --rm -v $(pwd)/data:/data geolint-image /data/*.geojson这里的镜像名需要替换成项目实际发布名$(pwd)/data是本地数据目录挂载到容器内/data的路径。Docker 方式更适合在 CI 里使用本地开发阶段建议直接用 npm 方式省去容器本身占用的额外时间和资源。6. 规则配置与校验逻辑GeoLint 和 ESLint 的相似之处不只是名字更重要的是配置和规则设计哲学。ESLint 允许插件通过rules对象配置每条规则的打开状态GeoLint 很可能也遵循同样的思路。如果你拿到项目后文档里写了具体规则名以文档为准下面给出的是从 ESLint 经验推导出的通用示例配置方便你快速理解这种工具应该怎么把规则落到项目里。6.1 一个配置示例{ rules: { no-invalid-geometry-type: error, no-missing-coordinates: error, no-empty-feature-collection: error, require-properties: { level: error, options: { requiredFields: [name, code] } }, coordinate-range: { level: error, options: { longitude: [-180, 180], latitude: [-90, 90] } }, feature-collection-only: warn, no-duplicate-feature: warn } }这里的规则名和参数都是示意性的为的是说明三类常用配置简单开关型规则比如error或warn。带自定义参数的规则比如require-properties指定必须存在的属性字段。带数值边界的规则比如coordinate-range指定经纬度范围。配置文件的格式大概率会支持 JSON也可能同时支持 JS、YAML。如果你的项目同时存在多个数据目录还可能有overrides或按目录覆盖配置的机制类似 ESLint 对不同目录应用不同规则。6.2 规则级别与输出行为linter 的规则级别通常分三级。off表示关闭规则不参与校验warn表示校验到问题时只给警告不改变进程退出码error表示校验到问题时在输出中报错并且在存在至少一个 error 的情况下让进程返回非零退出码。这个机制非常重要因为 CI 里能否拦截提交本质上依赖退出码。调试阶段建议先开warn看报告再逐步调整正式接入团队流程后把必须守住的规则开成error。6.3 自定义规则如果你团队有内部数据规范比如所有政区边界数据的properties里必须包含adcode和level默认规则很可能覆盖不到。ESLint 社区的做法是写自定义规则插件GeoLint 如果具备扩展接口理论上也支持类似能力。建议你阅读项目文档中与“自定义规则”“插件”“访问器”相关的内容看是否支持往配置对象里注入额外的验证函数。写自定义规则时要注意输出信息要包含文件路径和明确的问题描述避免把错误判定逻辑写得过于宽松或过于严格。7. 功能测试与校验效果验证工具安装完成、配置准备好之后重点就是实际跑一遍。下面是按“最小验证 - 多文件验证 - 修复验证 - 配置调整”四个阶段展开的测试流程。7.1 最小验证故意写坏一个文件测试目的确认 GeoLint 能正确解析文件、执行规则并输出错误位置。操作步骤在 data 目录创建bad.geojson文件。写入一个缺少coordinates或坐标层次错误的 Feature。执行校验命令。观察输出结果。预期结果命令行输出中会出现错误描述、规则名和发生错误的数据位置如果写入了致命错误进程退出码应为非零。判断成功标准你能在输出里定位到具体文件和问题类型而不是只得到一个抽象的解析异常。7.2 多文件批量校验测试目的验证 GeoLint 能否正确处理一个目录下的多个 GeoJSON 文件。操作步骤npx geolint ./data/如果项目支持 glob 通配符也可以试试npx geolint ./data/**/*.geojson预期结果工具按顺序遍历所有文件逐个输出每个文件的校验报告而不是遇到第一个坏文件就终止。判断成功标准报告中能看到每个文件名的独立分组并且能统计出文件总数和错误总数。7.3 自动修复验证如果 GeoLint 提供了--fix或类似子命令可以验证自动修复能力。自动修复通常只处理确定性、无歧义的错误比如删除多余的分号、补齐空数组这对应到 GeoJSON 可能就是补齐括号、统一缩进或移除空 Feature。测试时先备份原始文件运行修复命令后再运行一次不带--fix的检查命令看错误数量是否下降。如果修复没有生效说明对应规则不支持自动修复需要手动改文件。7.4 配置调整验证测试目的验证配置文件的优先级和覆盖行为。操作步骤在项目根目录先创建一个只包含“空 FeatureCollection”警告的配置再在子目录创建一份把它改为error的配置然后分别运行命令。预期结果子目录下的 GeoJSON 文件按更严格的配置执行根目录文件按宽松配置执行。如果项目不支持多配置覆盖这个测试会出现相同结果这时需要考虑把数据按目录拆成多个 npm script 分头执行。7.5 验证阶段容易踩的坑配置文件没被读取检查文件名和所在目录是否匹配工具约定。规则名写错配置里写一个不存在的规则名工具可能直接报配置错误也可能静默忽略这取决于实现。文件路径里有中文或空格命令行执行时注意加引号。多个文件里第一个就报错导致后面没继续跑观察工具是“单文件失败即终止”还是“全部文件跑完再汇总”。8. 批量任务与工作流集成对于前端项目来说GeoJSON 文件的规模通常不会特别大因此 GeoLint 的批量任务更多是指“一次命令跑完整个数据目录”和“在自动流程里无人工介入地执行”。8.1 目录级批量检查建议按数据类型组织目录结构例如src/ assets/ geo/ boundary/ road/ poi/然后配置三个 npm script分别检查三个子目录。这样当数据局部变化时可以只跑对应子目录节省时间。如果数据量很大检查脚本可以配合globby、fast-glob这类文件遍历工具先过滤出变更过的文件列表再逐个执行 GeoLint。更稳妥的做法是先用单个文件测试新的规则和配置再把数据目录加进批量任务。8.2 接入 Git hooks如果你使用 Husky 管理 Git hooks可以在pre-commit阶段运行npx geolint ./src/assets/geo提交前发现数据问题会直接阻塞提交适合对数据准确性要求较高的项目。如果不想严格阻塞也可以先用warn级别观察一段时间。8.3 接入 CI/CD在 GitHub Actions、GitLab CI 或 Jenkins 中GeoGeoJSON 校验可以放在构建之前的独立 Job 里。以 GitHub Actions 为例可以写一个类似下面的步骤文件名和包名需要替换为实际值name: geojson-lint on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install - run: npm run lint:geo这样每一次代码推送都会自动检查 GeoJSON 数据文件。对于团队成员素质不一、经常不小心提交错误数据的项目这一步能明显减少“测试环境正常、部署后地图空白”的问题。8.4 批处理中的失败重试与日志当文件数量很多时建议把命令输出重定向到日志文件方便后续排查npx geolint ./data lint-result.log 21也可以让脚本在失败时输出 JSON 报告再写一个简单脚本解析失败文件清单。如果 GeoLint 支持退出码区分“有警告”“有错误”“无问题”那么在批处理脚本里可以针对不同退出码做不同动作。9. 资源占用与性能观察GeoLint 是命令行工具不涉及 GPU 和显存资源占用主要集中在 CPU 和内存上运行窗口很短。它更适合和 ESLint 做类比解析一个普通规模的 GeoJSON 文件性能瓶颈通常不在单个文件的大小而在文件数量和规则复杂度。观察方法执行time npx geolint ./data查看命令总耗时。在任务管理器Windows或topLinux/macOS里观察 Node.js 进程的内存占用确认没有内存持续上涨的异常。用一个超大 GeoJSON 文件几十 MB 或上百 MB测试看是否能正常完成校验、是否出现内存溢出。如果你发现校验速度慢可以从三个方向排查文件是否过大、规则是否写得太复杂、是否每次启动都重新加载整个项目依赖。对于超大文件linter 并不是最优手段更专业的做法是用 OGR/GDAL 等空间数据处理工具做并行化的数据质量检查。日常开发场景下GeoJSON 文件通常都在几 MB 以内GeoLint 的启动时间和执行时间完全可以接受。值得注意的一个点是不要把 GeoLint 放进热更新或浏览器运行时。它是开发期工具不是运行时工具。前端打包时不应该把 linter 的规则逻辑打进生产 bundle。10. 常见问题与排查方法问题现象可能原因排查方式解决方案运行geolint提示 command not found全局安装失败或当前项目依赖未安装执行npm list geolint查看包是否在依赖列表里重新npm install或改用npx geolint配置文件没生效规则都没有执行配置文件路径错误或文件格式不支持检查命令中--config路径确认配置文件扩展名把配置移动到项目约定的默认名或改用支持的格式检查时报 JSON 解析错误文件本身不是合法的 JSON或文件里有 BOM 头、多余逗号用 VS Code 打开文件查看 JSON 语法是否标红先修复 JSON 语法再跑 GeoLint坐标范围没有报错但数据明显不对没有启用坐标范围规则或经纬度顺序写反但数值恰好在范围内查看当前配置里是否包含范围规则对比源数据标记的经纬度顺序在配置中开启坐标范围规则并明确坐标顺序约定中文属性值乱码或显示异常文件编码不是 UTF-8或 Windows 下终端编码不一致用文本编辑器查看文件编码将文件转为 UTF-8 无 BOM 格式命令行报Permission denied全局安装目录权限不足检查 npm 全局目录权限使用本地依赖方式安装避免用 sudo 强行安装CLI 输出太啰嗦看不清楚哪些是错误没有设置输出格式或级别过滤查看帮助文档确认是否支持--quiet、--format只显示error级别或输出到文件再查看CI 里跑不过但本地没有问题CI 环境 Node 版本不一致或依赖未装全查看 CI 日志确认 Node 版本和安装步骤在 CI 中固定 Node 版本先npm ci再运行校验--fix执行后错误数量没有变化对应错误不支持自动修复或修复规则未开启看报告里是否标注“可修复”标记手动修改文件或把修复规则单独配置排查的总原则很简单先确认“文件本身是否合法 JSON”再确认“规则是否被正确读到”最后看“退出码是否符合预期”。绝大部分问题都出在这三层的某一层上。11. 最佳实践与使用建议11.1 从最小规则集开始不要第一次就把所有规则全部开成error。GeoJSON 数据太复杂不同来源的数据规范差异很大第一次全开大概率会让团队产生抵触情绪。建议先启用 4 到 6 条最能兜底错误的规则比如合法几何类型、坐标存在性、FeatureCollection 结构、坐标范围等跑通后再按团队规范加码。11.2 保留一份“最小可运行配置”把 GeoLint 配置、示例 GeoJSON 文件、安装命令写进项目 README。新成员拿到项目后不用看完整文档先跑一遍示例就能理解这个工具做了什么。这也方便你在未来升级或换工具时快速恢复流水线。11.3 数据、配置、报告分目录管理建议按下面的结构维护数据工程目录geo-project/ ├── data/ # 原始 GeoJSON 数据 ├── config/ # GeoLint 配置 ├── reports/ # 校验报告 └── scripts/ # 批量处理脚本reports目录建议加入.gitignore因为校验报告是过程产物不应该频繁提交进仓库但可以在 CI 里作为 Artifact 保留一份便于追溯当前主分支的数据质量。11.4 批量任务必须加日志和退出码判断写脚本的时候不要只执行一条裸命令至少要把退出码打印出来把日志保留到文件。这样即使某天任务卡住或失败你也能从日志里看到是哪一批数据、哪一条规则出问题。11.5 数据授权和合规提醒无论在你的项目里使用 GeoLint 校验多少遍都无法替代对数据来源合法性的判断。下载公开 GeoJSON 文件时注意查看数据提供方的许可协议发布或商用前确认数据是否包含受限制的测绘信息涉及个人位置数据时必须遵守隐私保护相关法律不能因为数据格式上合法就忽略使用场景是否合法。12. 总结与下一步GeoLint 最值得尝试的点是把 ESLint 那套成熟的规则引擎思路带进了 GeoJSON 数据质量检查让原本靠肉眼和经验判断的地理数据问题变成了可以自动执行、自动读报告、自动阻塞流程的工程化能力。建议你先准备一个破坏过的 GeoJSON 文件安装工具后跑一遍最小校验验证它能不能准确定位到你故意埋下的错误再去阅读项目文档里的规则列表按团队数据规范自定义配置。最容易踩的坑是“配置了但没生效”和“规则开太猛导致噪音太多”前者多查路径和文件名字后者从最小规则集起步。如果 GeoLint 项目本身还在早期阶段你可以重点观察它的规则扩展方式是否灵活、输出格式是否符合 CI 需求再用几套真实数据样本做压测。后续可以扩展的方向包括把 GeoLint 接入 ESLint 生态做成 frontend 工具体系的一环、为上线的地图素材增加数据版本校验、结合自动化测试在每次构建后自动生成数据质量报告。对于手头有成百上千个 GeoJSON 文件的项目先在数据侧建立标准再谈可视化效果是性价比很高的做法。建议收藏备用。