简介Gosmore是一款基于OpenStreetMap数据的开源导航应用面向需要在离线环境下查看地图、搜索地点并规划路线的旅行者、户外爱好者也适合想研究导航软件实现或参与开源定制的开发者。压缩包共22个文件类型包括可执行文件、动态链接库、图标数据、XML样式、声音提示等其中exe与dll支撑程序运行14个wav提示音覆盖左转、右转、调头、停止等导航指令pak与csv存放默认配置和图标属性整体仅6.2MB下载携带都很方便。目前已有47人学习下载。借助离线地图数据和逐行路由规划用户即使没有网络也能完成地图浏览、目的地搜索与路线生成2D/3D视角还能帮助理解地形同时代码开源开发者可自由查看和修改结合XML样式与资源文件可深入理解桌面导航工具的结构。这份小型工具包适合快速尝鲜也是认识开源导航应用内部组成的实用样例。1. Gosmore 开源一个能离线导航的轻量级 OSM 路由引擎为什么它还值得上手如果你搜索过「Gosmore 开源」大概率是遇到了两个场景要么在做离线地图导航时发现 OSRM 太重、GraphHopper 要装 Java 环境要么是在看老外的开源基于 OpenStreetMap 的项目时被 Gosmore 这个名词卡住了。Gosmore 是一个用 C 写的 OSM 路由引擎它最特别的地方是整个编译产物就是一个单一二进制文件配上一份 PBF 地图数据就能跑起来通过 HTTP 接口就能做路线查询根本不需要装数据库、不需要写后端服务甚至能直接编译到嵌入式设备里做离线导航。它不像 OSRM 那样要预处理数据到专门的存储格式也不像 Nominatim 那样要搭 PostgreSQL 全家桶——你下载它、编出来、喂个地图文件它就能说话。适合谁想快速搭一个内部路径规划服务的人、做嵌入式导航实验的开发者、以及被现代路由引擎的重依赖折腾过想回归朴素方案的一线工程师。这篇我把从编译、喂数据到调接口、避坑的过程完整拆出来照着走就能起来。2. Gosmore 的核心定位单文件路由引擎的取舍与适用边界2.1 Gosmore 与 OSRM、GraphHopper 的本质区别它把「预处理」省到了什么程度大多数人在选路由引擎时第一反应是去对比性能、语言、扩展性但 Gosmore 的定位完全不同。它属于「内存映射型」路由引擎编译出来的可执行文件直接读取一份 PBF 格式的 OpenStreetMap 数据启动时把地图文件映射进内存然后基于这份数据实时算路。OSRM 的做法是先用 osrm-extract、osrm-partition、osrm-customize 三步把 PBF 转成自己的二进制格式查询时走预先算好的节点表和压缩表GraphHopper 则要先把数据导入到 LevelGraph 的存储里启动一个 Java 进程才提供服务。Gosmore 跳过了这些它本质上就是一个能直接读 PBF 的轻量路由器。这种设计带来的直接好处有三个。第一是启动速度快地图文件越大越明显因为不是解析导入而是毫米级的内存映射第二是占用空间小磁盘上只需要一份原始 PBF不用额外存预处理结果对存储紧张的嵌入式环境太友好第三是更新地图简单想换新数据直接替换 PBF 文件重启进程不像 OSRM 那样每次更新数据都要重新跑一遍提取和压缩三步。但代价也很明显因为实时读取原始 PBF 并解析路由关系它的并发能力和极端性能不如 OSRM适合并发量不大、但要求低成本和可控性的场景。我一般会把 Gosmore 用在「离线 Linux 小盒子」或者「开发阶段的本地路线原型」里。比如做一个园区巡检路径规划车辆不超过二十辆QPS 要求低但必须能断网工作Gosmore 一台树莓派就能扛住。至于高并发、多车道精细路网分析那还是老老实实选 OSRM别拿仙人的剑砍菜。2.2 数据源与依赖Gosmore 到底吃哪类 OSM 数据Gosmore 读取的是 PBF 格式的 OSM 全量数据也就是你在 Geofabrik 或 OSM 官网下载的那种后缀为.osm.pbf的文件。它不是按区域裁剪出来的小数据包就一定能跑Gosmore 设计上基于「整块地图数据」工作理论上你给它一份中国的 PBF它就只认中国路网给你一份某城市的 PBF它也只认那个城市。实际使用中我建议直接下载目标区域的 pbf然后可以配合 osmfilter/osmconvert 做裁剪不需要把全球数据拖下来。编译环境上Gosmore 依赖了 libcurl、libxml2、libpqPostgreSQL 客户端库、zlib 这一套老牌 C 库。这个依赖清单从早期版本到现在的版本基本没变过虽然项目很久没活跃更新但依赖都是基础库在 2025 年的 Ubuntu 上依然能顺利编译。唯一有点老派的是它默认用 Makefile 而不是 CMake要找好 configure 文件的入口。2.3 到底能用它做什么路由查询、最近节点、地图导出Gosmore 对外暴露的 HTTP 接口足够完成三类基本操作。第一是路径规划route给它起点和终点的经纬度它会返回一条经过路网的最短路径路径点、距离、耗时都能拿到。第二是最近邻查询near给定一个经纬度它返回距离最近的路网节点这在把 GPS 坐标吸附到道路上时非常好用。第三是矢量地图瓦片导出map它可以在给定范围和层级下导出 SVG 格网自己搭轻量地图渲染时能顶一下用。接口返回格式支持 JSON 和 XML默认终端友好。虽然是老项目但接口设计很克制没有花哨的推送、自动补全就是朴素的三板斧。对这种「能用、够用、不折腾」的路由引擎我在内部工具链里反而更放心因为它的黑匣子小出了问题直接读代码就能定位。3. 编译与安装在 Ubuntu 上把 Gosmore 从源码变成可执行文件3.1 准备编译环境需要哪些系统包和工具链编译 Gosmore 需要先确保系统具备 C 编译器与依赖库。以 Ubuntu 22.04 为例在干净环境中依次执行以下命令把所有依赖一次性装齐。这里有一个容易翻车的点早期教程会让你apt-get install libpq-dev但某些精简镜像里缺了 build-essential编译时会报找不到头文件所以我习惯先把基础环境也明确装上。sudo apt-get update sudo apt-get install -y build-essential autoconf automake libtool \ libcurl4-openssl-dev libxml2-dev libpq-dev zlib1g-dev pkg-config这六组包对应 Gosmore 源码里实际引用的头文件和链接库libcurl 负责 HTTP 请求相关的辅助功能libxml2 负责解析 XML 格式的 OSM 数据虽然 PBF 是主要输入但某些导出功能仍用得到libpq 是 PostgreSQL 的客户端库源码里 pgsql 输出模块会调用它zlib 用于解压 gzip 数据autoconf/automake 是经典 autotools 构建流程的必要工具。如果你后续想把 Gosmore 的查询结果直接写入 PostgreSQLlibpq 不是可选而是必选否则编译时会出现pq_开头的符号未定义错误。3.2 获取源码与 autogen.sh 构建流程Gosmore 的源码托管在 GitHub 上项目名就叫 gosmore。注意仓库里没有现成的 configure 脚本只有 configure.ac 和 Makefile.am所以你必须先执行 autogen.sh 生成 configure再依次执行 configure 和 make。这一步很多新手直接跑./configure会得到 No such file or directory不是源码坏了而是你没有先生成 configure。git clone https://github.com/gosmore/gosmore.git cd gosmore ./autogen.sh ./configure --prefix/usr/local make -j4 sudo make install执行./autogen.sh时它会调用 autoreconf 工具扫描 configure.ac生成 configure、Makefile.in 等一堆文件这个过程如果报了libtoolize缺失就去安装 libtool上面命令里已经包含了。configure 的参数我建议只改--prefix把可执行文件安装到/usr/local/bin这样后续命令行直接gosmore就能调用不用配置 PATH。make -j4表示用 4 个并行任务编译如果你的机器是低配虚拟机改成make -j2更稳否则内存不够会中途报错。编译完成后src/gosmore这个可执行文件就是最终产物。它不依赖运行时目录你甚至可以直接把它和 PBF 文件拷到另一台相同架构的系统上运行。3.3 启动服务命令行参数到底怎么给Gosmore 启动时通过命令行参数指定监听地址和地图文件路径没有配置文件。最典型的启动方式是gosmore /path/to/your-map.osm.pbf --port 8080这个命令把工作目录下的 PBF 文件加载进内存并让服务监听本机 8080 端口。这里有两个细节需要说清楚第一PBF 文件路径建议给绝对路径避免因为 CWD 不一致导致加载失败第二--port不指定时默认端口是 8080如果系统里已经有服务占用启动时会直接报 bind 错误退出。启动成功后终端会输出类似gosmore ready的日志但没有任何监听成功的提示去过新手期的人容易在这块发怵。我一般会立刻用curl探一下接口确认路由引擎真的活了curl http://localhost:8080/?lat39.9042lon116.4074lat239.9163lon2116.3972formatjson参数依次是起点纬度、起点经度、终点纬度、终点经度。如果返回了一段 JSON 数组而不是 HTML 错误页面就说明服务已经正常工作了。常见的错误是返回空数组这通常意味着起点或终点不在路网范围内或者 PBF 数据裁剪过度导致没有可路由路段后边避坑章会细说。4. 数据准备与路由查询把 PBF 喂给 Gosmore 并拿到路径4.1 下载与裁剪 PBFGeofabrik 与 osmconvert 的组合最省事的方式是直接从 Geofabrik 下载目标区域的 PBF比如「中国-latest.osm.pbf」。但完整中国包体积大启动时内存占用接近 1.5 倍文件体积如果只做城市级别测试裁剪是更明智的。常用工具是 osmconvert能按 bounding box、行政边界等多种方式裁剪。我一般先用 osmconvert 按经纬度范围切出一个小区域测试通了再扩展到完整地图。osmconvert china-latest.osm.pbf -b115.5,39.0,117.5,41.0 --complete-ways -obeijing.osm.pbf这里的-b后面四个数字分别是最小经度、最小纬度、最大经度、最大纬度顺序千万不能写反。--complete-ways是一个容易被忽略的关键选项裁切时如果没有它会丢失那些只有部分节点落在边界框内的道路导致路网断裂Gosmore 算路时明明有近路却绕远路。用完整区域 PBF 的话不需要裁剪这一步但如果你从其他渠道拿到已经切碎的小包务必确认路网完整性。加载 PBF 时Gosmore 读取的是未经拓扑处理的原始数据这意味着数据里冗余的单向道路、禁止转弯关系它都会在首次请求时实时处理。这也是为什么它在超大区域上首次查询会慢第二次以后因为内存页缓存生效才快起来。4.2 路由查询参数详解format、fast、layer 等Gosmore 的 HTTP API 查询参数是它在main.c里直接解析的翻源码时你会发现参数数量并不多但每个都影响结果形态。核心参数我整理成表格方便照着用参数取值示例作用lat / lon39.9042 / 116.4074起点坐标必填lat2 / lon239.9163 / 116.3972终点坐标必填formatjson / xml / gpx控制响应格式gpx 可拿来直接画轨迹fast0 / 1 / 20 表示最短距离1 表示最快路径2 表示优先推荐路线layerroad / bicycle / foot选择路由道路类型默认走机动车道zoom / x / y12 / 1066 / 1563地图导出接口的瓦片参数near纬度,经度返回距离最近的路网点使用fast0时Gosmore 会按纯距离计算最短路径适合徒步fast1才会考虑道路限速和类型得到驾车最短时间路径。这里有个典型的理解偏差很多人以为默认就是驾车最快其实默认值是按距离算的。我曾经在这里翻过车拿着默认参数给客户演示明明走高速更快但路线一直穿小路客户直接问是不是路网数据没更新其实只是没加fast1。请求示例与返回字段示例如下curl http://localhost:8080/?lat39.9042lon116.4074lat239.9163lon2116.3972formatjsonfast1返回的 JSON 是一个数组前两项通常是「路径总距离」和「预计耗时」之后是密集的经纬度点串。这个点串就是构成道路折线的坐标序列前端可以直接连成线画在地图上。耗时的单位是毫秒乘以一千才是小时别直接展示。4.3 在 Python 里封装 Gosmore 查询做一个最简客户端实际工程里不会总用 curl 裸调我一般会写一个极简的 Python 封装把坐标纠偏、参数构造、超时重试统一处理掉。下面这段代码是实际能用版本的一部分import requests import math class GosmoreClient: def __init__(self, base_urlhttp://127.0.0.1:8080): self.base_url base_url def route(self, from_xy, to_xy, fast1, layerroad): params { lat: from_xy[0], lon: from_xy[1], lat2: to_xy[0], lon2: to_xy[1], format: json, fast: fast, layer: layer, } r requests.get(self.base_url, paramsparams, timeout5) r.raise_for_status() data r.json() if not data or len(data) 2: return None # data[0] 为距离, data[1] 为耗时毫秒 return {distance: data[0], duration_ms: data[1], geometry: data[2:]}这里timeout5是防呆设置如果地图数据大导致首次查询慢5 秒可能会不够但与其无限制等待不如让它快速失败并打印日志。调用完成后geometry就是一组连续的[lat, lon]点可直接传给高德或 Leaflet 绘制。4.4 返回结果的坐标系陷阱与距离单位一个值得重点说明的坑Gosmore 返回的坐标点是「纬度在前、经度在后」的顺序和常见 GeoJSON 的[lon, lat]正好相反。如果你直接拿返回数组里的点去喂给支持 GeoJSON 的前端库地图上的线会跑到完全错误的位置。解决办法很简单在封装层把每个点翻转一下geometry [[lon, lat] for lat, lon in data[2:]]距离字段的数值是米耗时是毫秒这两个单位在接口文档里没有明确提示但源码里写得很清楚。所以封装时一定要做单位换算不然展示到页面上会出现「到目的地还要 0.5 毫秒」这种诡异数据。单位搞错的问题比接口报错更隐蔽因为返回永远有一串数值看起来像正常工作。5. 避坑与常见问题五个把 Gosmore 跑崩或算错路的实战踩坑记录5.1 现象启动时提示cannot open pbf file很多人第一次从 GitHub 拉完源码编译成功启动时却直接报couldnt open /path/to/data.osm.pbf。这个报错看起来像是文件不存在或者权限不足但我遇到的真实原因大多不是权限而是路径里的相对路径问题。Gosmore 启动后会把当前工作目录作为基准如果你用 systemd 服务启动工作目录会被强制设置成/那么你写的相对路径data.osm.pbf实际定位到了/data.osm.pbf这个不存在的位置。解决方式第一启动脚本里明确cd到 PBF 所在目录再执行第二直接使用绝对路径第三如果用了 systemd务必在 service 文件里配置WorkingDirectory指向地图目录。三种方式里我推荐第二种最简单直接因为 Gosmore 本身不做路径解析绝对路径能彻底消掉这个问题。5.2 现象查询返回空数组且没有任何日志输出启动成功后访问接口返回[]或者返回只有[0, 0]的异常结果。这不代表服务故障而是你的起点终点坐标没有落在路网上。Gosmore 内部会把经纬度映射到最近的路网节点如果起点和终点周围 200 米内没有任何已识别路网结果就是空数组。常见于自己画了一个县城中心的坐标结果 PBF 里只包含高速公路那当然算不出道路。解法和思路分两步先用near参数检测坐标最近的路网节点curl http://localhost:8080/?near39.9042,116.4074formatjson如果返回[9999,9999]或者空值说明这个位置周围没有道路数据那你需要换一个更靠近实际道路的坐标或者重下覆盖范围更大的 PBF。如果near返回正常但 route 仍为空再检查起点和终点是否在同一连通的路网内——被河流、隧道隔断且无桥无路时路由引擎会判定不可达返回空数组是正确行为服务端没问题。这种「查询无害无错」的假象最容易让人怀疑编译器有问题其实只是地理数据拓扑不完整。5.3 现象启动后 CPU 占用持续 100%首次查询尤其明显Gosmore 是内存映射加惰性解析的架构服务启动后并不会把整张图的所有道路拓扑全部提前建好而是在收到第一次路由请求时才把相关区域的 PBF 数据块解析出来并构造寻路图。因此当你第一次发请求时CPU 瞬间飙升属正常现象。但如果持续 100% 超过一分钟且请求还没返回就需要注意是不是地图太大、内存不足导致频繁换页。我遇到过的典型场景是用一台 1 核 512MB 的小云服务器跑省份级 PBF启动不报错首次查询直接卡死。解决方法是给地图「瘦身」用 osmfilter 只保留highway*相关道路过滤掉建筑、水系、土地利用这些对路由无用的大块数据。具体命令如下osmfilter input.pbf --keephighway motorway motorway_link trunk trunk_link primary primary_link secondary secondary_link tertiary tertiary_link residential service filtered.osm osmconvert filtered.osm -ofiltered.osm.pbf这样生成的 PBF 体积通常只有原来的 30% 不到启动后内存占用大幅下降查询响应时间也从无法承受降低到可接受范围。注意这个过滤会丢失步行小路如果你要跑徒步或骑行保留标签里要加上foot*或bicycle*。5.4 现象返回路径绕远路明明中间有条直线道路却不走这种情况十有八九是fast参数含义没设对。Gosmore 的fast0时采用「最短路径」算法只衡量几何距离不理会道路等级和禁止转向限制所以可能出现从小路穿越或者绕远走路网密集区域的现象。而fast1才会考虑道路速度、单行道、转弯惩罚结果更贴近汽车导航。还有一个隐蔽点是layer参数如果设成footGosmore 会优先检索允许步行的道路通常绕路距离会明显增加。另外如果 PBF 数据本身缺少道路连接关系比如路网数据年代久远新修的道路不在数据里任何参数都救不了。验证办法是对照同一路径用 OSM 官网的在线 DEMO 查询若 OSM 官网能走通而 Gosmore 绕路优先确认你的数据版本是不是太老。数据新鲜度在 OSM 生态里是永恒的痛点Gosmore 因为是直读 PBF所以这个问题比其他引擎更突出——OSRM 至少会在预处理时提示数据完整性Gosmore 静默吞掉一切。5.5 现象编译时报undefined reference to PQconnectdb这个链接错误几乎只在使用--without-pgsql或者系统缺少 libpq 头文件时出现。Gosmore 源码里有一个可选的 PostgreSQL 支持模块默认是编译进去的所以系统里必须存在 libpq 的开发包。如果你为了精简环境故意不装libpq-dev编译到最后一步就会爆出这个错误。另一种情况是库文件装了但链接器找不到符号通常发生在 64 位系统下多架构混用后同步库路径出了偏差。最省心的解决方式就是重新检查依赖安装sudo apt-get install --reinstall libpq-dev然后清理编译产物重新生成 configuremake clean ./autogen.sh ./configure make -j4如果确认不需要 PostgreSQL 功能也可以在 configure 时加--without-pgsql关闭该模块但我不建议这样干因为后续如果你想调数据入库又要重编一次。6. 进阶用 Gosmore 做批量路径规划与响应时间优化把 Gosmore 跑通以后你会发现它真正顺手的地方在于「批量路径规划」和「离线批量分析」。比如你要对一万个配送单做路线距离估算按照传统方式调在线地图 API既烧钱又受 QPS 限制而本地跑一个 Gosmore只要把起点终点坐标按顺序排好循环请求就行没有配额上限也没有网络延迟瓶颈。我在做车辆路径问题VRP预计算时就把它当距离矩阵提供方用——给一组配送点和取货点把所有点对距离算出来喂给优化算法。单进程循环请求会有性能浪费因为每个请求都要做坐标吸附和路径搜索但只要地图区域不大速度完全够。如果追求更高吞吐可以利用fork方式启动多个 Gosmore 进程每个进程监听不同端口然后在上游用 Nginx 配置负载均衡到这些后端。这里要注意Gosmore 内部没有共享缓存多进程下每个进程都要独立映射同一份 PBF好在操作系统层面页面缓存是共享的实际内存增量没有想象中翻倍。还有一个实用技巧是预热缓存批量查询前先对区域内几个关键点发起一次“空跑”请求强制让 Gosmore 把该区域的 PBF 数据块加载到内存页缓存中。之后真正跑批量任务时每次查询都命中缓存响应时间能下降 70% 以上。这个技巧不算 Gosmore 独有的而是所有内存映射类程序的通用优化思路但在这里特别好用因为 Gosmore 没有预热接口你需要自己用请求去“顶开”数据页。操作上很简单循环查几百个均匀分布的坐标对即可。这个「缺什么就手动补什么」的思路正是我愿意在工程里继续用它的原因。现代路由引擎把预处理、容灾、监控做得很完善平台化氛围浓但换到离线小环境总觉得使不上劲。Gosmore 朴素到连日志都靠 printf反而每一项都透明可控。从那以后我每次在嵌入式设备或离线服务器上要快速出路线结果都会强制走一遍这套流程拿 PBF、编译、用 curl 探活、再写批量脚本。虽然它的代码已经很少有人维护了但对想理解路由引擎底层行为的人来说它依然是一台拆得开的机器。希望这份实战拆解帮到你少踩几个我已经替你踩过的坑。本文还有配套的精品资源点击获取