用 React Native + Expo 从零构建门店巡检应用:Android / iOS / Web 三端一码实践指南

原创2026-09-13 22:23:311,980 阅读
文章标签:文档教程Vibe Coding人工智能

用 React Native + Expo 从零构建门店巡检应用:Android / iOS / Web 三端一码实践指南

门店巡检是典型的移动端业务场景:店员每天需要核对冷藏柜温度、安全出口、货架陈列与交接事项,勾选任务、记录现场问题并保存结果。本文基于 easy-vibe 开源课程仓库中「React Native 与 Expo」专题文档(docs/ar-sa/stage-3/cross-platform/react-native-expo/index.md),从空白 Expo 项目出发,逐步构建一个可在 Android、iPhone 与浏览器中打开的门店巡检应用,并讲清本地存储、安全存储、离线同步与真机验证的边界。读完本文,你将掌握 create-expo-app 脚手架的使用、巡检首页与任务勾选交互的搭建、基于 AsyncStorage/expo-sqlite 的本地持久化方案,以及 Expo Go 与 Development Build 的选型原则。

1. 认清两件工具的分工:React Native 负责界面,Expo 负责工程

在动手之前,需要先理解技术栈中两个核心角色:

  • React Native:用 React 和 TypeScript 编写 Android 与 iOS 的原生界面。它渲染的是原生控件,而不是把网页套进一个应用窗口。
  • Expo:围绕 React Native 提供整套工程能力,包括项目创建、开发服务器、常用设备 API(相机、相册、安全存储等)、构建、更新与商店提交服务。即便产品后续需要自定义原生代码,也可以先以 Expo 起步,再逐步深入。

三者关系可以这样理解:中间的项目保存页面和业务逻辑;React Native 负责把页面渲染到 Android 和 iPhone;Expo 负责启动项目、提供通用 API 并产出测试应用。同一套页面还可以在浏览器中打开——"一套代码多端运行"不等于"每一行都相同",而是指共享的产品逻辑集中在一起,少数真实的平台差异保持小而明确。

图片来源:React Native 与 Expo 的项目结构示意(位于仓库 docs/zh-cn/stage-3/cross-platform/react-native-expo/images/ 目录,为本专题文档配图,展示了项目、React Native、Expo 三者关系)。

React Native 与 Expo 的多平台项目结构示意

2. 三种已经落地的真实产品:这个技术栈不是纸上谈兵

专题文档用三个真实产品说明 React Native 与 Expo 在不同业务中的适用性,巡检应用可以从中提取可复用的产品设计经验。

Shopify POS:面向门店经营的零售平台

Shopify POS 常被放在收银台或拿在店员手里,用于收款、查库存、处理退换货和调取订单客户资料。Shopify 在正式采用 React Native 之前,专门用性能较低的 Android 设备做过实验——开发电脑上运行流畅,不代表门店里的旧设备也能顺畅使用。对巡检应用的启示是:首页就应该直接展示门店、班次、完成进度与待办任务,真实店员不应该为打开当天状态而翻越多个装饰性页面。

Shopify POS 官方产品页展示的库存与门店界面

Discord:Android 与 iOS 共用一份产品

Discord 是面向兴趣社群与工作团队的交流平台,用户在其中聊天、加入语音频道、管理成员与角色。Discord 原本分别维护 Android 和 iPhone 应用,新功能经常不能同时到达两边;改用 React Native 后,两边可以共用更多页面和功能,但返回手势、字体与系统习惯仍然分别处理。对巡检应用的启示是:先共享页面与业务逻辑,只有两个平台确实需要不同行为时,才引入平台专属文件。

Discord 官方展示的 Android 角色管理页面改版前后对比

MTA TrainTime:Expo 支撑的生产级应用

纽约大都会运输署(MTA)用 Expo 开发 TrainTime 等出行应用,乘客可能赶车时查下一班列车、站台买票、上车后出示车票——这些操作都发生在时间紧、网络环境不断变化的通勤途中。MTA 团队使用 Expo 提供的打包与更新服务:打包把开发中的项目做成可安装的测试应用,更新把确认过的小修改送到用户设备。这证明 Expo 不仅能做课堂演示,也能支撑生产级发布流程。

Expo 官方案例展示的 MTA TrainTime 应用

3. 准备开发环境:Node.js LTS 与代码编辑器

浏览器版本第一版只需准备两样工具:

  • Node.js:让电脑能够运行项目工具。安装页面看到 LTS 时选择它即可——LTS 表示维护周期较长的稳定版本。专题文档记录的验证环境为 Node.js 22.14 与 Expo SDK 57。
  • 代码编辑器:用来打开项目并与 AI 协作修改文件,Trae、VS Code 等均可。

浏览器版本完成之后,Android 侧需要 Android Studio(Google 提供的 Android 开发工具),iPhone 侧需要 Xcode(Apple 提供的开发工具,仅能安装在 Mac 上)。

4. 创建并启动空白项目:三条命令跑通第一版

在项目目录中打开终端,执行 Expo 官方脚手架:

npx create-expo-app@latest store-inspection
cd store-inspection
npm run web

三条命令的含义分别是:创建名为 store-inspection 的 Expo 项目、进入项目目录、启动浏览器版本。终端出现二维码后按 W 即可在浏览器中打开;看到空白起始页说明项目启动成功。

更精确的写法可以显式指定 TypeScript 模板:

npx create-expo-app@latest store-inspection --template blank-typescript
cd store-inspection
npx expo start

如果项目没有启动,把完整错误信息交给 AI 修复:

Expo 没有启动,错误是【粘贴错误】。请只修复启动问题。

实践经验:不要让 AI 在同一句话里同时加入登录、相机、离线同步和后端——先确认首页能打开,再逐步叠加功能。

5. 搭出巡检首页:从静态数据到可勾选任务

第一版巡检任务只做四个常规检查项:入口照明(entrance lighting)、价签(price labels)、过道整洁(aisle cleanliness)与安全出口(fire exits)。向 AI 编程助手分步提出需求:

  1. 修改首页标题并显示门店名称与班次;
  2. 加入四项巡检任务,先用演示数据;
  3. 显示完成进度,并在任务列表下方加入"现场问题"区域(先静态);
  4. 让任务可勾选与取消,进度根据已勾选数量实时变化。

逐项点击验证:勾选一项进度增加,取消勾选进度减少。先把这条最基本的交互测通再继续。如果数字变化不对,让 AI 只修复进度计算逻辑,不改页面样式:

我勾选一项后进度错误。请只修复进度计算,不改页面样式。

界面信息过多时,不要让 AI 全部重写,而是给出明确的保留与删除清单:

首页信息太多。保留门店、进度、巡检项目和现场问题,其他先删掉。

以下截图来自专题实际创建的 Expo 项目,页面真实运行在浏览器中(expo-web-running.png);浏览器窗口变窄后,内容应自动变为手机宽度,按钮与文字不能挤在一起(expo-web-mobile-layout.png)。窄屏截图只用于检查窄窗口下的排列,Android 与 iPhone 的运行结果仍需在对应设备中验证。

门店巡检应用真实运行在 Expo Web

同一个 Expo Web 应用的窄屏移动布局

6. 记录现场问题并保存:从输入框到持久化

任务可勾选之后,在"现场问题"区域加入输入框与保存按钮。分三步完善:

  1. 输入框能打字后,处理空内容:没有填写时不保存,并在输入框下方提示"请填写现场问题";
  2. 保存后清空输入框,并把刚才的内容显示在下方;
  3. 展示保存结果卡片:时间、已完成项目数与备注。

专题文档给出了一次真实操作的结果:勾选"检查安全出口"后进度从 1/4 变为 2/4;输入"消防通道有纸箱,已通知值班员移走"并保存后,记录出现在页面且输入框恢复为空(见 expo-web-record-saved.png)。

真实点击与保存后的巡检记录

本机持久化:AsyncStorage 还是 expo-sqlite

刷新页面或关闭应用后,仅存于组件状态的记录会丢失。这一阶段的完成标准是:再次打开应用时,刚才的进度和记录还在。让 AI 将进度与记录保存到本机("请把巡检进度和现场记录保存在本机"),并按固定顺序验证:勾选两项任务 → 保存一条现场问题 → 完全关闭应用 → 重新打开确认数据仍在。

选型建议(文档明确给出):

  • AsyncStorage:适合少量简单键值数据,如同应用自带的小记事本;
  • expo-sqlite:当数据增长为"巡检单—明细项—待重试队列"这种带关系的结构时,数据库更易管理;
  • 浏览器版本需要对应的 Web 存储方案。

注意:本阶段明确不要添加服务器。先让本地路径跑通,再讨论同步。

7. 进阶能力:图片、登录与后端——但注意安全边界

图片记录(放在保存跑通之后)

拍照/选图使用 Expo 的 ImagePicker 工具(expo-image-picker)。先实现一个小动作:

允许用户为未完成的巡检项附加一张图片。显示预览并允许移除。

相机涉及权限弹窗与更多设备相关测试,在目标手机上实际尝试之前,不要宣称"可以拍照"。

登录与后端:后端拥有权限,App 只负责展示

后端是拥有账号、门店权限、共享记录与上传图片的服务器。移动端应当展示后端返回的数据,而不是自行决定谁是店长。分两步接入:

  1. 先描述数据关系(用户、门店、巡检、清单项、图片如何关联),不写代码;
  2. 再接入已有登录 API:用户只能看到服务器分配的门店。

两条必须遵守的安全红线(文档明确强调):

  • 登录令牌保存在 SecureStore,而不是普通文本存储;
  • 绝不把公司机密放进应用或 EXPO_PUBLIC_ 前缀的环境变量——随应用分发的值最终都能被用户读取。

离线同步:本地优先,逐步补状态

"离线同步"指设备在网络不可用时先把工作保存在本地,网络恢复后再上传;第一版原型并不要求具备。等本地保存与后端都稳定后,再逐个增加状态:先把未发送记录标记为 Pending,加入"重试"按钮在联网后发送单条记录;之后可扩展 Sending、Synced、Failed 状态。每次提交携带唯一请求 ID,避免重试造成同一条巡检记录被创建两次。若已接入服务器,用两个账号重复测试:账号 B 应能看到同一门店允许共享的交接记录,但绝不能看到其他门店的数据——页面上隐藏入口不算权限控制,服务器必须拒绝越权读取。

8. 真机验证与发布边界:Expo Go、Development Build 与诚实测试

三种运行入口

  • 浏览器:按 W 后检查鼠标键盘操作、刷新行为与窄屏布局;准备发布网页时执行 npx expo export --platform web 生成可部署的静态文件。
  • Android:安装 Android Studio 后创建并启动虚拟手机,回到 Expo 终端按 A;也可以在真机安装 Expo Go,扫描终端二维码打开当前项目。完成标准:应用可打开、系统返回键可用、输入框不被键盘遮挡。
  • iPhone:在 Mac 的 Xcode 设置中下载 iPhone 模拟系统,启动模拟器后按 I。检查顶部内容是否被刘海遮挡、返回手势是否可用、输入框是否被键盘遮挡。浏览器窄屏截图不能作为 iPhone 验证结果。

Expo Go 与 Development Build 的选型

  • Expo Go:适合项目早期,覆盖其内置原生模块支持的功能;
  • Development Build:加入自定义原生代码后的选择,是只属于当前项目的可安装测试应用。

配置 Development Build 前先让 AI 列出本机还缺什么("请列出配置 Development Build 前需要准备的内容,不要修改项目"),准备完成后再让其配置。Expo 支持本机构建与云端打包服务(使用云端需要 Expo 账号);公开发布还需要 App Store 或 Google Play 的开发者账号。

发布前需在真实设备上逐项测试:首次启动与权限弹窗、软键盘下的文本输入、选图或拍照、关闭后重开、弱网重试与防重复提交、账号隔离与退出登录、从旧版本升级且不丢失本地记录。

文档声明的验证边界

专题文档明确记录了本专题的验证情况:原型使用 Expo SDK 57 与 TypeScript 创建,类型检查通过,Web 生产导出成功,应用在浏览器中实际打开;任务勾选、记录保存与窄屏布局均在运行构建中测试过。由于测试机器没有可用的 Android 模拟器,也没有 iOS Simulator 运行时,文档没有宣称完成手机构建、相机权限、签名或商店提交。在自己的项目中同样应遵守这条规则:如实记录"在哪个设备、哪个构建上、运行了什么"。

9. 最小可行里程碑与后续路线

本专题给出的第一个有用里程碑很小:打开清单 → 完成一项 → 保存一条备注 → 重新看到这条记录。这条路径稳定可靠之后,再按以下顺序推进:

  1. 补自动测试:先测"勾选任务后进度增加",再测"现场问题为空时不能保存"——一次只测一件事;
  2. 内部测试版:Android 与 iOS 分开准备("请告诉我生成 Android 内部测试版需要准备什么"),只发给自己与同事,先让少量用户用稳定再考虑公开发布;
  3. 模拟交接班:同一设备完成"早班完成三项巡检、保存现场记录、关闭重开、晚班继续最后一项",验证晚班店员无需询问即可看懂哪些已完成、现场发生了什么、自己还要处理哪一项;
  4. 请真实用户试用:观察其能否独立完成打开任务、勾选、写记录、关闭重开的四步,并明确区分"保存在本机"与"已经同步"。

10. 专题文档与源码导航

以下仓库文件与本文内容对应,可供继续深入:

登录后查看全文
easy-vibe