这个项目前后我断断续续做了大概三周核心目标很朴素用 React Native 把乘客端和司机端两个 App 跑起来用 Node.js 把订单、计价、实时位置这些后端能力撑住。做成之后乘客能发单司机能抢单地图上能看到对方的位置移动下车后按里程和时长自动结算。整体流程对标 Uber 的订单机制同时加了 InDriver 那种乘客自选价、司机可响应议价的玩法。这篇文章不是入门教程我把为什么要这样选型、环境里那些坑、前端定位地图怎么做、后端 Socket.IO 怎么推位置、订单状态机怎么设计全部按实操顺序写出来。想完整走一遍“跨端开发 后端服务 实时通信”流程的开发者可以参考这份总结。1. 项目定位与技术选型思路1.1 为什么选 React Native Node.js 这套组合先回答一个最常见的问题网约车类应用为什么不用纯原生开发或者后端为什么不选 Spring Boot / Go我的判断有几个层面。首先是跨端成本。这个项目需要乘客端和司机端两个 App核心交互逻辑高度相似地图、订单、定位是同一套东西。用 React Native 可以一份代码同时出 Android 和 iOS个人开发者在有限时间内能维护得过来。纯原生意味着至少两套工程、两套代码规范光是地图 SDK 集成和权限配置就要折腾两遍。然后是技术栈统一。React Native 用的是 JavaScript/TypeScriptNode.js 后端用的也是同一门语言。前端定义的数据结构、字段命名、事件写法在后端可以直接复用不用在脑子里来回切换语言。调试的时候从 App 端追到 Node.js 服务端心智负担小很多。这一点在一个人干全栈项目时尤其重要。还有一点经常被忽略Node.js 的并发模型非常适合这个场景。网约车应用的核心压力不是复杂计算而是高频率的轻量请求——经纬度上报、订单状态广播、司机位置推送基本都是 I/O 密集操作。Node.js 的事件循环机制在这种场景下表现稳定单机处理几百个并发连接完全没问题。如果选 Spring Boot不是不行但启动一个 JVM 的重量级服务来干这种事对个人项目来说有点“杀鸡用牛刀”了。1.2 网约车应用的核心模块拆解在动手写代码之前我先把整个产品拆成了五个模块这个习惯直接决定了后续开发节奏模块技术载体核心职责乘客端 AppReact Native注册登录、地图选点、发布订单、实时查看司机位置、支付模拟司机端 AppReact Native注册登录、接收新订单广播、抢单/议价、上报位置、状态切换API 服务Node.js Express用户认证、订单 CRUD、计费、司机查询实时通信服务Node.js Socket.IO订单广播、位置同步、状态通知数据存储PostgreSQL Redis用户/订单关系数据、实时位置缓存这个拆法遵循一条原则实时性要求高的走 Socket.IO实时性要求一般的走 REST API。比如乘客发单可以走 HTTP因为这是一次性动作不用维持长连接。但司机抢单、位置上报必须走 Socket因为要服务端主动推给另一端。把这两个通道混在一起后面很容易出现“状态更新了但对方没收到”的玄学问题。2. 环境准备Node.js 版本坑与工程初始化2.1 Node.js 到底是干什么的如果你之前主要写前端可能对 Node.js 的认知停留在“能跑 JavaScript 的服务器”这个层面。但它在这个项目里其实承担了三份工作第一它是 React Native 开发工具链的运行时Metro 打包器就是用 Node.js 跑起来的第二它是后端服务的运行环境Express 和 Socket.IO 都跑在它上面第三它自带的 npm 是管理依赖的唯一入口。可以这么理解RN 工程的构建工具和后端服务是两套独立的东西但它们共享同一个 Node.js 运行时。所以环境准备阶段第一件事就是把 Node.js 装对版本。版本不对前面所有工作直接堵死。2.2 Ubuntu 安装 Node.js 20 的正确姿势我这里以 Ubuntu 环境为例因为很多后端服务和 CI 跑在 Linux 上。我记得早期在 Ubuntu 上直接执行apt install nodejs装的是老版本像 14.x 甚至 12.x早就过了维护期。装完后跑 RN 的新版本工具链经常报 OpenSSL 相关的错误就是因为 Node.js 版本太老内置加密模块和现代打包器不兼容。正确做法是用 NodeSource 的 apt 源或者用 nvm 管理版本。我推荐 nvm因为后面切换版本方便。安装步骤curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20执行完检查一下node -v npm -v这里有一个必须避开的坑。网上能看到不少教程让你安装“最新版 Node.js”有些人直接去官网下载了 24.x 之类的非 LTS 版本。实际开发中我见过一个很典型的报错error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这个报错翻译过来就是你指定的这个版本号在当前版本源里不存在。原因通常是教程里写了一串不存在的版本号或者 nvm 的版本列表还没同步到最新。解决办法很朴素——不要指定精确到小版本的号直接给大版本nvm install 20它会自动帮你选择当前最新的 LTS 版本。Node.js 官网页面上的 LTS 下载入口就是给生产项目用的RN 工具链和 Express 框架都对 LTS 版本做了充分适配。为了尝鲜去用非稳定版本后面依赖报错只能自己兜着。注意装完 Node.js 后再用 npm 全局安装 RN 工具链时尽量不要用 sudo。权限混乱会导致全局包目录归属错乱后续升级或删除非常麻烦。用 nvm 装 Node.js 天然规避了这个问题。2.3 RN 工程初始化与结构说明环境准备好之后用 React Native 官方 CLI 初始化工程。我这里选的是裸 RN 工程而不是 Expo理由是网约车项目需要集成原生地图 SDK、后台持续定位、推送这些能力Expo 的托管工作流在这些点上会有限制。虽然 Expo 现在也支持 prebuild 弹出原生代码但作为学习项目直接用 CLI 让每一步都可见、可控制更利于理解整个链路。初始化命令npx react-native-community/clilatest init RideClone推荐用 TypeScript 模板后续类型定义在前后端对接时能省下大把时间。初始化完的目录结构里核心关注这几个位置src/放业务代码App.tsx是入口android/和ios/是原生工程。业务代码建议按模块分目录src/screens/、src/components/、src/services/、src/store/别把所有组件都堆在一个目录里否则项目到中后期自己都找不到文件。依赖方面我装的是这一套npm install react-navigation/native react-navigation/native-stack npm install react-native-maps react-native-geolocation-service npm install react-native-async-storage/async-storage axios socket.io-client npm install reduxjs/toolkit react-redux这里提醒一句RN 生态的依赖版本兼容性是个门槛React 版本、RN 版本、原生模块版本三者必须对齐。我吃过一次亏装了一个较新的原生地图库结果要求 RN 必须升到新版本而新版本又和其他库冲突。后来养成了习惯每次装依赖前先看一眼它的 peerDependencies 要求尽量选 RC 版本比较成熟的库。3. 前端核心功能实现地图、定位、订单流转3.1 地图组件选型与高德接入地图是网约车应用的脸面也是技术复杂度最高的部分。RN 环境里最成熟的地图方案是react-native-maps它其实是一个封装层底层可以切换 Google Maps 或 Apple Maps。国内环境更常用高德需要配合react-native-amap3d这类库或者自己桥接 SDK。我开发时用的是 Google Provider因为跨平台表现一致。关键代码大概是这样import MapView, { Marker, Polyline, PROVIDER_GOOGLE } from react-native-maps; MapView provider{PROVIDER_GOOGLE} style{{ flex: 1 }} initialRegion{{ latitude: 31.2304, longitude: 121.4737, latitudeDelta: 0.01, longitudeDelta: 0.01, }} showsUserLocation showsMyLocationButton Marker coordinate{{ latitude: driverLat, longitude: driverLng }} title司机位置 / Polyline coordinates{routeCoordinates} strokeColor#4A90D9 strokeWidth{3} / /MapView地图接入的坑主要集中在 Key 配置上。Android 端要申请 API Key并且要在AndroidManifest.xml里配置iOS 端同样要申请 Key 并且在AppDelegate里注册。包名和指纹信息必须和申请 Key 时填写的一致否则地图加载出来是灰的或直接报错。调试时一个现象是Key 只配了 release 环境debug 环境地图空白。这种问题查起来不难但容易忽略。3.2 乘客端叫车流程与定位获取乘客端核心流程是进入页面定位当前位置 - 长按地图或点击输入框选择目的地 - 系统计算预估价格 - 确认发单。其中定位能力是基础。定位权限这一步Android 需要在AndroidManifest.xml里声明权限uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION / uses-permission android:nameandroid.permission.ACCESS_COARSE_LOCATION /iOS 需要在Info.plist里加用途描述keyNSLocationWhenInUseUsageDescription/key string需要获取你的位置以查找附近的司机/string keyNSLocationAlwaysAndWhenInUseUsageDescription/key string后台持续获取位置用于订单功能/stringJS 代码里用react-native-geolocation-service请求授权并监听位置import Geolocation from react-native-geolocation-service; Geolocation.requestAuthorization(whenInUse); const watchId Geolocation.watchPosition( (pos) { setLatitude(pos.coords.latitude); setLongitude(pos.coords.longitude); }, (error) console.error(error.code, error.message), { enableHighAccuracy: true, distanceFilter: 10, interval: 5000 } );注意distanceFilter和interval这两个参数它们决定了定位的更新频率。我开始时把distanceFilter设为 1结果每秒都在回调手机发烫且耗电严重。后来改成 10 米既不会频繁跳动也不会漏掉关键位置变化。网约车场景下不要追求每米一次上报后端扛得住电池也扛不住。3.3 司机端抢单与行程状态处理司机端比乘客端多一个“抢单”操作。乘客发单后服务端通过 Socket.IO 把订单广播给符合条件的司机司机端收到广播后在屏幕上弹出一个抢单卡片。这里有个业务细节不是所有司机都能收到所有订单后端要判断司机和乘客的距离范围超出范围就不广播。这个过滤逻辑可以放在服务端减少无效推送。司机端的核心是状态管理。司机既要维护自己的在线状态空闲/忙碌也要维护当前行程状态前往中/服务中/结束。我用 Redux Toolkit 统一管理定义一个枚举const DriverStatus { OFFLINE: offline, IDLE: idle, ACCEPTED: accepted, ARRIVING: arriving, IN_PROGRESS: in_progress, COMPLETED: completed };状态切换的时机靠 Socket 事件驱动。司机点击“接单” - 前端调用 REST API 确认订单 - 后端更新订单状态 - 通过 Socket.IO 通知乘客端。这套流程的核心不是 UI 写得多花哨而是状态和事件必须严格对应否则会出现“司机已经在路上乘客页面还显示等待接单”这种严重的体验问题。此外司机端在行程进行中需要持续向服务端上报自己的经纬度每 5 秒上报一次。这个上报只负责实时位置展示和订单状态无关两条链路分开处理避免位置更新的高频率影响订单状态的稳定性。3.4 React Native 启动白屏问题排查记录“启动白屏”是 RN 初学者遇到最多的现象也是最容易劝退人的坑。我开发过程中就碰到过几次现象是 App 启动后一片白屏过很久才有内容甚至永远没有内容。第一次遇到时我的排查思路是这样的先看 Metro 打包器是否正常启动。终端执行npx react-native start如果终端输出Metro waiting on port 8081说明打包器在跑。如果端口被占用会直接报错这时候要么关掉占用进程要么改端口。确认 Metro 没问题后尝试摇一摇设备在开发者菜单点 Reload。如果重新加载后页面能出来说明是首次加载时 Bundle 拉取超时。Android 真机调试时真机默认连不上电脑的 localhost需要执行adb reverse tcp:8081 tcp:8081。这一步不执行真机永远白屏模拟器却正常很容易让人怀疑是代码问题。再进一步用浏览器直接请求 Bundle 地址确认是否可访问curl http://localhost:8081/index.bundle?platformandroiddevtrue。只要能返回一段 JS 代码说明 Metro 没问题问题出在 App 内部加载逻辑。如果 Release 包白屏通常不是 Metro 的问题而是 JS 代码在 Hermes 引擎执行时出错。去原生日志里看报错 —— Android 用adb logcat *:EiOS 直接看 Xcode 控制台。我那次白屏的最终原因特别简单依赖版本冲突react-native-maps和 RN 新架构不兼容原生模块加载失败。解决办法是降级到兼容版本清缓存重装依赖cd android ./gradlew clean npm start -- --reset-cache排除白屏问题时一定要有系统性从外到内一层层剥打包器 - 连接 - Bundle - 原生日志。不要一上来就翻业务代码十有八九是环境问题而不是业务问题。4. Node.js 后端REST API 实时通信4.1 后端结构与关键 API 设计后端我用了最简单的分层routes 定义接口controllers 做参数校验services 写业务逻辑models 对应数据库表。这种方式结构清晰项目长大后也容易拆微服务。核心 API 清单方法路径用途POST/api/auth/register乘客或司机注册POST/api/auth/login登录并返回 JWTPOST/api/orders乘客创建订单GET/api/orders/:id查询订单详情POST/api/orders/:id/accept司机接受订单POST/api/orders/:id/start司机开始行程POST/api/orders/:id/complete司机完成行程并结算POST/api/orders/:id/cancel取消订单GET/api/drivers/nearby获取附近空闲司机创建订单的路由示例const express require(express); const router express.Router(); router.post(/orders, async (req, res) { const { passengerId, pickup, dropoff, price } req.body; if (!passengerId || !pickup || !dropoff) { return res.status(400).json({ code: 400, message: 缺少必要参数 }); } const order await orderService.createOrder({ passengerId, pickup, dropoff, price }); res.status(201).json({ code: 0, data: order }); });这里有个经验接口返回结构统一用{ code, message, data }code 为 0 表示成功。前端封装一个统一的请求函数所有接口都走同一套逻辑出问题排查时能少走很多弯路。数据库我选的是 PostgreSQL因为订单状态变更、计费结算涉及事务关系型数据库在这方面的强一致性更可靠。表结构最核心的是三张users乘客和司机共用、orders订单主表、ride_events行程事件流水。如果做 InDriver 那样的议价模式会给orders表加一个negotiated_price字段再建一个bids表记录司机的出价。4.2 Socket.IO 实时位置同步实现实时通信是网约车应用的心脏。乘客能看到司机在地图上移动靠的不是轮询而是服务端通过 WebSocket 主动推送位置。我选了 Socket.IO原因是它自带重连机制、支持房间和广播正好省了自己手写心跳和断线逻辑。服务端核心逻辑如下const http require(http); const { Server } require(socket.io); const server http.createServer(app); const io new Server(server, { cors: { origin: * } }); io.on(connection, (socket) { socket.on(driver:join, ({ driverId }) { socket.join(driver_${driverId}); }); socket.on(order:accept, ({ orderId, driverId }) { socket.join(order_${orderId}); io.to(order_${orderId}).emit(order:accepted, { orderId, driverId }); }); socket.on(driver:location, ({ orderId, lat, lng }) { socket.to(order_${orderId}).emit(order:location, { lat, lng }); }); });流程是这样司机接单后服务端把司机 socket 加入order_订单号这个房间司机位置变动时通过driver:location事件上报服务端把坐标转发给同房间的乘客。乘客端只需要监听order:location拿到坐标刷新地图 marker。乘客端连接和监听import { io } from socket.io-client; const socket io(http://你的服务器地址:3000); socket.on(order:accepted, (data) { setOrderStatus(accepted); }); socket.on(order:location, ({ lat, lng }) { setDriverPosition({ lat, lng }); });两个注意点。第一客户端要监听后端约定好的事件名两边不一致是联调时最常踩的坑。我建议把事件名抽成常量文件前后端共用一套。第二位置上报不要每秒钟都发实测每 5 秒上报一次乘客端看到的司机移动轨迹已经很连续了。每 1 秒发一次服务端压力增长 5 倍体验提升却不明显。4.3 订单状态机与计价逻辑订单不能只用几个 if-else 随便改状态那样写到后面一定会出现非法跳转。我一开始就定义了状态机const OrderStatus { PENDING: pending, // 待接单 ACCEPTED: accepted, // 已接单 ARRIVING: arriving, // 司机前往上车点 IN_PROGRESS: in_progress, // 行程中 COMPLETED: completed, // 已完成 CANCELLED: cancelled // 已取消 };合法的状态流转路径pending - accepted - arriving - in_progress - completed pending - cancelled accepted - cancelled在 service 层写一个状态流转表任何非法跳转直接拒绝。服务端在接收到“开始行程”请求时先校验当前状态是否为arriving不是就直接返回错误不要在代码里用大量 if 判断散落各处。计价逻辑是网约车应用的另一块核心。Uber 模式是系统定价起步价 里程单价 * 里程 时间单价 * 时长再乘以动态溢价系数。实现代码function calcRideFee({ distanceKm, durationMin, baseFee 10, perKm 2.5, perMin 0.4, surge 1.0 }) { const fee (baseFee perKm * distanceKm perMin * durationMin) * surge; return Math.max(fee, baseFee); }InDriver 模式的差异化在于“乘客出价、司机竞单”。乘客下单时填一个自己愿意接受的价格司机端看到这个价格后选择接受或者出一个自己的报价。这个模式在实现上只需要在订单表增加一个passenger_price字段再加一个driver_price字段用于司机还价。真正的难点是这些价格的可视化和协商流程前端交互比 Ube 模式多不少。5. 联调与疑难杂症排查实录5.1 高频问题速查表完整跑完一个全栈项目遇到的问题五花八门。我把高频问题整理成了一张速查表你在开发时遇到类似现象可以直接对照现象原因排查方向解决方案启动白屏Metro 未启动 / Bundle 拉取失败终端 Metro 状态、adb reverse启动 Metro、执行adb reverse tcp:8081 tcp:80818081 端口被占用其他进程占用lsof -i:8081关掉占用进程或改 RN 端口真机连不上 Metrolocalhost 不通手机和电脑是否同一局域网用adb reverse或局域网 IP地图空白API Key 配置错误包名、SHA1、Bundle ID 是否匹配重新申请 Key 并确认配置定位权限无提示权限声明缺失AndroidManifest / Info.plist补充权限声明和用途描述Gradle 下载慢网络问题构建日志使用镜像源配置npm install 报 ERESOLVE依赖版本冲突查看冲突依赖锁定版本或升级相关库到兼容版本Socket.IO 收不到事件事件名不一致或房间未加入服务端日志事件名抽成常量前后端对齐司机位置不动位置上报间隔过长或后端未转发检查 watchPosition 参数合理设置 interval检查房间转发逻辑这个表格是我在开发过程中边踩坑边积累下来的。看到现象不要慌先对号入座定位方向再去看日志效率能提升不少。5.2 踩坑心得与建议整个项目做下来最花时间的不是写代码而是各端联调。乘客端、司机端、后端、地图 SDK四个环节中只要有一个版本不一致或字段不统一问题就会以非常隐蔽的方式出现。我的第一个建议是动手写业务代码前先把订单状态机画在纸上。这个项目里如果一开始就把状态流转定死后续就不会出现“司机端已经进入行程中乘客端还停在已接单”这种需要同时改两端代码的尴尬。第二个建议是位置上报一定要做节流。这个按钮虽然不起眼但直接影响后端压力、耗电量和流量。我实测下来 5 秒一次是体验和性能比较平衡的点。你可以按 10 米距离过滤但不要用 500 毫秒的 interval设备根本扛不住。第三个建议也是我认为对任何全栈开发者都通用的点接口返回结构、错误码、事件名这些约定一定要前置。前后端如果各写各的联调阶段就是灾难。我后来会写一份非常简单的接口约定文档哪怕只有半页纸也能让联调时间缩短至少三分之一。另外关于克隆应用我多说一句。这个项目的定位是学习和技术验证。我把工程代号起成了 RideClone图标配色都做了原创设计没有动现有产品的任何素材。如果你也想做类似的东西建议先想清楚目的是搞懂技术还是上架运营。如果是前者这些代码随便改随便用如果是后者界面品牌必须自己设计业务规则也要结合行业合规要求来定。包名、仓库名、商店描述里都不要出现现有产品的商标名这是底线。最后说一个我自己的小习惯后端所有接口返回结构统一用{ code, message, data }前端所有请求封装成一个函数。这个习惯看着简单但当你半夜两点排查线上问题时会发现它省下的时间是实打实的。这个项目做完我最大的感受是真正难的不是某个功能写不出来而是让四个端在同一条数据流上对齐。把这根线理顺了项目就已经成了一大半。