从零构建门店巡检应用:React Native 与 Expo 的完整实战指南
从零构建门店巡检应用:React Native 与 Expo 的完整实战指南
门店巡检应用需要同时覆盖 Android、iPhone 与浏览器三种运行环境:店员打开首页即可查看当天任务、勾选完成进度、记录现场问题,并在关闭应用后仍然保留数据。本文基于 Datawhale easy-vibe 项目中 React Native 与 Expo 门店巡检专题(德文版)与 中文源文档 编写,从项目创建、交互开发、本地存储到真机验证与发布,完整还原这套"项目制学习"的落地路径。读完你将掌握:用 Expo 脚手架创建 TypeScript 项目、按步迭代出可勾选可保存的巡检页面、用 AsyncStorage 实现本地持久化,并理解 Development Build、内部测试版与三端验收的完整流程。
1. React Native 与 Expo:两个工具如何分工
React Native 负责用 React 与 TypeScript 编写页面,并把它渲染成 Android 和 iOS 的原生界面(不是 HTML,也不是 WebView);Expo 则在此基础上补齐了工程化能力——项目脚手架、开发服务器、设备 API、构建与更新服务。两者结合,让"一套 TypeScript 代码跑三端"成为可能。
仓库中的 架构示意图 直观地展示了这套结构:中间是保存页面、表单、状态与业务规则的可复用代码库;React Native 把 React 界面交给各平台真正渲染;Expo 提供脚手架、Router、设备 API、开发构建与云端构建;Android 最终生成 APK/AAB,iOS 生成 App,Web 端则由 React Native for Web 生成静态资源。
需要强调的是,共用代码不等于三端完全一致。相机、通知、权限、返回手势和发布流程仍然要分别在每个平台上单独验证——这一点贯穿整个专题的验收标准。
2. 三个已经落地的真实产品
三个知名产品分别展示了 React Native 与 Expo 在不同业务中的用法,也为巡检应用的页面信息顺序提供了参照。
Shopify POS:零售收银场景
Shopify POS 用于门店收银、查库存、退换货调单。Shopify 在正式采用 React Native 前,专门用性能较低的 Android 设备做过实验——开发者电脑上运行流畅,不代表门店里的旧设备也流畅。巡检首页沿用了同样的信息顺序:先显示门店和班次,再显示完成进度、待办任务和现场问题,店员打开页面就能看到当天的巡检状态。
Discord:跨端共用的社区产品
Discord 原本分别维护 Android 与 iPhone 应用,新功能经常不能同时到达两边;改用 React Native 后两边共用更多页面和功能,但返回手势、字体和系统习惯仍需分别处理。对巡检应用而言,这意味着主要内容可以共用,但依然要在 Android 和 iPhone 上分别打开检查。
MTA TrainTime:Expo 驱动的公共交通应用
纽约大都会运输署(MTA)用 Expo 开发出行应用,乘客在赶车、买票、上车验票等网络不断变化的场景中使用。Expo 提供的"打包"(把开发中的项目做成可安装的测试应用)与"更新"(把已确认的小修改送到用户设备)能力,让他们在遇到严重问题时能快速发布修复。
3. 创建项目与巡检清单
3.1 准备开发环境
浏览器版本只需两样工具:
- Node.js:安装页面选择 LTS(维护时间较长的稳定版本)即可;本专题验证环境使用 Node.js 22.14。
- 代码编辑器:Trae、VS Code 等均可,用于打开项目并与 AI 协作修改文件。
浏览器版本完成后,Android 使用 Android Studio(Google 提供),iPhone 使用 Xcode(Apple 提供,仅支持 Mac)。创建新项目时使用 Expo 官方脚手架给出的当前 SDK 版本即可,本专题验证环境为 Expo SDK 57。
3.2 用脚手架创建空白项目
直接执行 Expo 官方脚手架:
npx create-expo-app@latest store-inspection --template blank-typescript
cd store-inspection
npx expo start
三行命令分别表示:创建项目、进入项目目录、启动项目。终端出现二维码后按 W 在浏览器中打开,看到空白页面即启动成功。也可以让 AI 编程工具代为执行:"请创建一个名为 store-inspection 的 Expo TypeScript 项目。"
如果项目没有启动,把错误信息交给 AI:"Expo 没有启动,错误是【粘贴错误】。请只修复启动问题。"
3.3 用 AI 提示词逐步搭出巡检首页
从最小页面开始,分三步完成首页:
- "请把首页标题改成'门店巡检',并显示门店名称和班次。"
- "请在首页加入四项巡检任务,先用演示数据。"
- "请显示巡检完成进度,并在任务列表下面加入'现场问题'区域。"
任务勾选与进度联动是核心交互,建议按小步迭代并逐次验证:"请让巡检任务可以勾选和取消",确认四项任务都能点击后,再执行"请让完成进度根据已勾选的任务数量变化"。如果进度计算有误,可用"我勾选一项后进度错误。请只修复进度计算,不改页面样式"这类提示词限定修复范围。
下面两张截图来自本次创建的 Expo 项目(页面实际运行在浏览器中)。宽屏下展示门店"江南路门店"、班次"早班·08:30-12:00"、进度 1/4 和巡检任务列表:
浏览器窗口变窄后,内容应自动切换为手机宽度,按钮和文字不能挤在一起——这张窄屏图仅用于检查窄窗口下的排列,不能代替 Android 与 iPhone 的真机验证:
4. 保存巡检报告:从内存到本地持久化
4.1 现场问题的输入与保存
在"现场问题"区域加入输入框和保存按钮后,需要依次处理三个细节:
- 空内容拦截:"没有填写内容时不要保存,并在输入框下面提示'请填写现场问题'。"
- 保存成功反馈:"保存后清空输入框,并把刚才的内容显示在下面。"
实际验证路径是:勾选"检查安全出口"后进度从 1/4 变成 2/4;输入"消防通道有纸箱,已通知值班员移走"并保存,记录出现在页面,输入框恢复为空。下方截图展示的正是保存后的状态——进度 2/4、"已记录 1 条"及问题描述均正确显示:
4.2 关闭应用后保留数据
刷新页面或关闭应用后记录消失,是因为数据只停留在内存状态里。这一阶段的完成标准是:再次打开应用时,刚才的进度和记录还在。对应的提示词是"请把巡检进度和现场记录保存在本机"。
改完后按固定顺序检查:勾选两项任务 → 保存一条现场问题 → 完全关闭应用 → 重新打开确认数据还在。德语原版文档对此给出了明确的选型建议:
- AsyncStorage:适合保存少量键值数据,相当于"应用自己的小记事本";
- expo-sqlite:当记录量增加、需要在"巡检、明细、待办"之间建立关系并支持搜索分类时,改用本地数据库更合适。
4.3 一条记录上传到服务器
本地数据只留在这台设备上,换手机或店长要在后台查看,就需要上传到服务器。建议从一条记录开始:
- 先让 AI 列出所需条件:"我想把巡检记录同步到服务器。请先告诉我最少需要准备什么,不要修改代码。"
- 再让 AI 只做上传功能:"请先实现'上传一条巡检记录'。"
上传成功时页面显示"已同步";上传失败时本机记录仍然要保留——分别测试成功与失败两种情况,结果清晰后再增加自动重试。一条记录跑通后,再依次增加登录、门店权限、图片上传和数据隔离。
5. 照片与后端:后续阶段的扩展方向
德语版文档明确把照片和后端放在"之后添加"的位置,并给出了两条安全与架构边界:
5.1 照片记录
在开放的问题点允许拍照,需要包含预览与移除能力。文字记录完成后,可以使用 Expo 的拍照与相册工具 ImagePicker(expo-image-picker)增加照片记录。
5.2 凭据安全与离线同步
- 移动端 Token 属于 SecureStore:敏感凭据应放入
expo-secure-store,而不是普通存储; - 企业级机密禁止进客户端:既不能写死在 App 里,也不能放进
EXPO_PUBLIC_环境变量——EXPO_PUBLIC_前缀的变量会被打进客户端包,任何用户都能提取; - 离线同步在本地存储与 API 稳定之后再引入:先保证"本机数据可靠 + 接口可访问",再谈冲突处理与同步策略。
6. 在真实设备上收尾:Expo Go、Development Build 与验收清单
6.1 三端打开与验收
- Android:安装 Android Studio 并创建启动一台虚拟手机,回到 Expo 终端按
A;也可在真机安装 Expo Go,扫码终端二维码打开项目。验收标准包括:应用可打开、系统返回键可用、输入框不被键盘挡住。 - iPhone:Xcode 中下载 iPhone 模拟系统,启动模拟器后按
I。检查顶部内容是否被刘海挡住、返回手势是否可用、输入框是否被键盘挡住。浏览器窄屏截图不能作为 iPhone 验证结果。 - 浏览器:按
W检查鼠标键盘操作、刷新与窄屏布局;准备发布时生成静态文件:
npx expo export --platform web
本专题在浏览器中实际完成了勾选、进度变化与文字保存三项验证;由于测试机没有可启动的 Android 虚拟手机、也未下载 iPhone 模拟系统,因此没有把 Android 与 iPhone 写成"已验证"——这是文档刻意保持的严谨边界。
6.2 Development Build 与内部测试版
Expo Go 是大家共用的体验工具,适合查看第一版页面;项目继续开发后,需要制作只属于当前项目的测试应用(Development Build)。先让 AI 列出准备项:"请列出配置 Development Build 前需要准备的内容,不要修改项目",再执行"请为当前项目配置 Development Build"。
Expo 支持本机打包与云端打包服务,云端服务需要 Expo 账号;公开发布还需要 App Store 或 Google Play 的开发者账号。开发版安装到真机后,要实测相机、照片、通知、离线恢复和后台切换——模拟器能打开,不代表设备能力已经完成。
准备给同事试用时,Android 与 iOS 分开准备内部测试版("内部测试版"只发给同事,不会出现在应用商店)。在此之前,先给两个已跑通的小功能补上自动测试,一次只测一件事:
- "请测试:勾选一项任务后,完成进度会增加。"
- "请测试:现场问题为空时不能保存。"
自动测试守住简单规则;相机、权限和手机性能仍需真机检查。最后请一位未参与开发的同事走一遍完整流程:打开当天任务、勾选两项、写一条现场问题、完全关闭再重新打开。如果同事总问"我刚才到底保存了吗",说明页面没有把"已保存在本机"与"已上传"的结果讲清楚,应先把状态显示明白再继续加功能。
7. 验证边界与完成标准小结
德语版文档在结尾给出了一条重要的验证声明:原型基于 Expo SDK 57、TypeScript 与真实 Web 导出测试通过;而在没有 Android 模拟器与 iOS 模拟器运行环境的情况下,移动端构建与签名不能视为"已完成"。
汇总本专题的完整验收链路:
| 阶段 | 完成标准 | 验证手段 |
|---|---|---|
| 首页搭建 | 门店、班次、任务、进度、现场问题区域齐全 | 浏览器宽屏 + 窄屏检查 |
| 交互逻辑 | 勾选联动进度、空内容拦截、保存后清空并回显 | 浏览器实际操作 |
| 本地持久化 | 关闭并重开后进度与记录仍在 | 完全关闭应用再打开 |
| 服务器同步 | 成功显示"已同步",失败保留本机记录 | 分别测试成功与失败 |
| 三端验证 | Android 返回键/键盘、iPhone 刘海/返回手势、浏览器刷新 | 各端独立验证,互不替代 |
| 设备能力 | 相机、照片、通知、离线恢复、后台切换 | Development Build 真机测试 |
| 测试与发布 | 自动测试通过、内部测试版跑通 | 一次只测一件事,逐项推进 |
从"一个空白项目"到"一份可保存、可同步、可发布的门店巡检应用",这套流程的关键不在于一次写对,而在于每完成一次修改都重新运行项目并检查页面变化。这正是 easy-vibe 项目"项目制学习"的核心方法论——通过可运行的小步骤持续收敛,最终在真实设备上交付可用的第一版。想继续深入时,可参阅仓库中的 中文源文档(含 13 个步骤的完整提示词与验证清单)以及 stage-3 跨端专题目录 中的其他平台实践。





