麻雀窝 Sparrow Zoo

从 Expo 57 脚手架到双端模拟器:一次完整的安装与验证记录

记录 Expo 57 移动端脚手架的版本选择、依赖安装、Android 与 iOS 工具链、原生构建、模拟器故障排查和实际交互验证,并解释每一层验证能证明什么。

准备在 macOS 上搭建 Expo 57、构建 iOS 与 Android 开发版的开发者;环境记录为 2026-10-21。发布于 更新于
Expo 57 双端落地脚手架 · 原生构建 · 模拟器验证一套 TypeScript 工程Router · NativeWind · Dev ClientAndroidAPK + 模拟器iOSApp + 模拟器检查 → 构建 → 安装 → 交互相机采集与真机发布另行验证
阅读目录

结论先行

这个 Expo 57 脚手架已经完成依赖检查、JavaScript 打包、iOS 和 Android 原生构建,并在两端模拟器安装、启动和操作。iOS 验证了页面导航、计数和浅色/深色显示;Android 验证了首页、组件页与计数交互,用户随后在可见模拟器中手动确认运行正常。

这些结果证明基础开发链路可用。相机只接入依赖并声明权限,尚无采集页面或真机拍摄结果;iOS 模拟器产物未签名,也不是可发布安装包。

问题背景

项目目标是给智能客服和多模态素材生产业务准备一套 iOS/Android 移动端基础工程。首期只需要页面导航、基础组件、主题切换和后续接入相机的原生依赖,不接后端、登录或云构建。

Expo 负责组织 React Native 工程及原生配置;React Native 把 React 组件渲染为平台界面。JavaScript 能打包,仍可能因 Xcode、Android SDK、CocoaPods 或原生模块而无法生成 App。因此这次把“代码检查、原生编译、模拟器安装、实际交互”分层验证。

详细内容

1. 版本先按兼容组合确定

项目由 create-expo-app@5.0.0 的 blank-typescript@sdk-57 模板创建,使用 Node.js 24.22.0、npm 11.19.1。实际依赖为 Expo 57.0.30、React Native 0.86.3、React 19.2.3、Expo Router 57.0.28 和 Expo Dev Client 57.0.20。

样式选择 NativeWind 4.2.7 与 Tailwind CSS 3.4.19;动画依赖为 Reanimated 4.5.1、Worklets 0.10.1。相机预备依赖为 VisionCamera 5.2.3、Nitro Modules 0.37.1 和 Nitro Image 0.15.2。选择 SDK 57 的依据是当时 NativeWind 稳定版的兼容说明;没有逐包追最新版本。

Expo Router 的间接依赖曾让 npm 选入不同代的 react-dom、expo-font 和手势包。package.json 用 overrides 固定为 19.2.3、57.0.4、2.32.0,并以锁文件和 expo install --check 校验组合。这里的版本锁定需要在未来升级 Expo 时一并复核。

2. 脚手架里有什么

src/app 中有首页、组件示例页和根导航;Expo Router 根据文件位置生成页面路由。示例页使用按需复制的 React Native Reusables Button、Text 源码及许可证,没有引入整套组件库。NativeWind 提供浅色、深色和跟随系统模式。

app.json 是原生配置来源:包标识为 com.sparrow.mobile,scheme 为 sparrow-mobile,同时声明 iOS/Android 相机和麦克风用途。VisionCamera 5 通过原生自动关联进入工程;配置里没有旧版 VisionCamera Expo plugin。应用启动时不申请相机权限。

TypeScript 6 对 CSS 副作用导入的检查曾报错,工程增加 styles.d.ts 后通过类型检查。ios/、android/、dist/ 和 node_modules/ 是本地生成物,已被 Git 忽略;修改原生依赖或权限后,需要重新生成并构建原生工程。

3. 从依赖到原生工程,分别验证什么

code
cd front/mobile
npm ci
npm ls --all --json
npx expo install --check
npm run check
npm run export
npx expo-doctor
CI=1 npm run prebuild

npm ci 严格按锁文件重装;npm ls 看完整依赖树;expo install --check 核对 Expo 配套版本;npm run check 执行 TypeScript 和 ESLint。npm run export 成功生成 iOS、Android 的 Hermes JavaScript bundle。

prebuild 根据 app.json 和依赖生成 iOS/Android 工程,并检查生成的权限声明。它没有安装 Pods,也没有编译 App。最初 expo-doctor 为 20/21,通过项之外的缺项是 CocoaPods;这个结果只代表当时的环境快照,不代表最终 iOS 构建失败。

npm 默认缓存里有旧的 root 属主文件,出现 EACCES。本次仅对安装命令指定 npm_config_cache=/tmp/sparrow-mobile-npm-cache,没有修改家目录权限。锁文件使用的 npmmirror 在受限网络里一度无法解析;获准联网后重装成功。

4. Android:补齐工具链,局部指定 JDK

原生构建需要 Android Command-Line Tools、SDK Platform 36、Build Tools 36.0.0、NDK 27.1.12297006 和 Gradle wrapper 9.3.1。缺其中任何一环,prebuild 成功也不能产生 APK。工具装齐后生成了调试包 android/app/build/outputs/apk/debug/app-debug.apk,约 274 MB。

本机默认 JDK 25 在 Gradle 的 CMake 相关步骤失败。Android Studio 自带 JDK 17.0.7 可以完成本次构建,因此只在那次构建命令的进程环境中指定它;没有改全局 JAVA_HOME、shell 配置或系统默认 JDK。这也是先查 java -version、再定位失败步骤的原因:脚手架本身与当前构建工具链需要分开判断。

code
cd front/mobile/android
JAVA_HOME='/Applications/Android Studio.app/Contents/jbr/Contents/Home' ./gradlew assembleDebug

这条命令展示局部 JDK 的做法;实际执行仍以生成工程所需的环境变量和 SDK 路径为准。调试 APK 只用于本地安装,不等同于签名发布包。

5. Android 模拟器:镜像、程序与 CPU 架构要对齐

起初 Android SDK 里看似存在系统镜像目录,但内容为空,不能创建可启动设备。随后下载官方 Android 36 Google APIs ARM64 镜像,压缩包约 1.87 GB,解压约 4.3 GB,并在临时目录创建 sparrow-validation AVD。

这台 Mac 的模拟器镜像是 ARM64。新版 SDK 命令行工具经 Rosetta 运行时,曾误装 x86_64 版 Emulator 37.2.12,与 ARM64 镜像不匹配;换成 Google 官方同版本 Darwin ARM64 模拟器程序,校验压缩包并确认 Mach-O 架构后,模拟器才可启动。排查此类错误要同时看 Mac、Emulator 可执行文件和系统镜像三者的架构。

安装 APK 后,用 adb reverse tcp:8082 tcp:8082 把模拟器内的 8082 端口转到宿主机 Metro 服务,再通过开发版 deep link 加载。实际截图确认首页、组件页和按钮计数从 0 到 1。后来重启为有窗口的模拟器供手动操作,用户也确认验证 OK。

6. iOS:Xcode、Pods、运行时和签名各管一段

获授权后安装 Apple Developer 官方 Xcode 26.3 到 /Applications/Xcode.app,并完成许可与首次初始化;配套有 iOS 26.2 SDK。另装 CocoaPods 1.17.0 和 CMake 4.4.4,再执行 pod install。Pods 阶段曾因受限网络和缺 CMake 失败,补齐后成功,Hermes 官方组件也完成下载与校验。为腾出空间,仅清理了获授权的 Yarn 缓存,约 39 GiB。

iOS 26.3.1 模拟器运行时下载约 8.39 GB。下载后 simctl runtime list -v 已显示 Ready,但 simctl list runtimes 仍为空,说明运行时镜像尚未挂载;执行下面的命令后才被模拟器识别。重新下载不是当时的必要修复。

code
xcrun simctl runtime scan-and-mount

随后 xcodebuild 对 generic iOS Simulator 目标以退出码 0 完成 Debug 构建,生成 ios/build/DerivedData/Build/Products/Debug-iphonesimulator/mobile.app,约 347 MB。CODE_SIGNING_ALLOWED=NO 表示本次是无签名模拟器构建,不能直接在真机分发。

cd front/mobile
xcodebuild -quiet -workspace ios/mobile.xcworkspace -scheme mobile -configuration Debug -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath ios/build/DerivedData CODE_SIGNING_ALLOWED=NO build

7. Metro 连接失败:构建成功之后仍要看监听地址

iPhone 17 Pro 模拟器已安装并打开开发版,但第一次用 --localhost --port 8082 启动 Metro 时出现红屏。服务只监听 IPv6 的 ::1,而开发版试图通过 IPv4 127.0.0.1:8082 取 JavaScript bundle,因而被拒绝连接。原生 App 能启动并不代表 JavaScript 已加载。

code
cd front/mobile
npm start -- --host lan --port 8082

改用 --host lan 后服务监听可用地址;通过 sparrow-mobile://expo-development-client/?url=http%3A%2F%2F127.0.0.1%3A8082 打开开发版,首页和组件页均正常显示,导航可用,按钮计数从 0 增至 5,浅色与深色页面正常。开发版在这种模式下依赖正在运行的 Metro;这与独立发布包是不同的交付方式。

8. 最终验证结果与边界

2026-10-21 本机结果
层次结果能说明什么
依赖与静态检查通过版本树、类型、lint 无当前错误
JS 导出与 prebuild通过Bundle 和原生工程能生成
Android APK构建成功本机 Android 原生链路可编译
iOS Simulator App构建成功本机 iOS 模拟器链路可编译
模拟器交互双端通过首页、组件页和基础交互可运行
相机/真机/发布未验证不能从模拟器结果推定

Android 运行结果来自安装、截图与用户手动确认;iOS 运行结果来自实际页面和交互检查。VisionCamera 只完成依赖和权限配置,没有相机页面、权限请求、录制或真机测试。项目也没有后端接入、登录、EAS 云构建、发布签名或商店上架。

总结归纳

这次把 Expo 工程从模板带到了两端模拟器:先锁定兼容依赖,再确认 JavaScript 与原生配置,分别补齐 Android 和 iOS 工具链,最后在运行中的开发版检查页面和交互。最有用的经验是让每项结果只证明它实际覆盖的范围:export 不能代替原生构建,编译成功不能代替启动和交互,模拟器通过也不能代替相机真机与发布验收。

参考资料

  1. Expo:创建项目

    模板初始化与 Expo 项目入口。

  2. Expo:Prebuild

    配置生成原生工程的机制与边界。

  3. Expo:Development builds

    开发版与 Expo Go、JavaScript 开发服务的关系。

  4. Expo Router

    基于文件的路由。

  5. NativeWind 安装说明

    样式依赖及兼容选择的依据。

  6. VisionCamera 文档

    原生依赖、权限与相机能力的边界。

  7. Android Emulator 文档

    模拟器与系统镜像安装依据。

  8. Apple:安装模拟器运行时

    iOS Simulator 运行时的安装背景。

  9. CocoaPods 指南

    iOS 原生依赖安装流程。