Expo CLI常用命令详解：完整指南

Expo CLI 实战手册：从零构建到上线发布的全流程精解

你是否经历过这样的开发日常？刚搭建好 React Native 环境，Xcode 编译失败、Android SDK 路径报错；改了几行代码要等三分钟重新打包；修复一个紧急 bug 却不得不走一周的应用商店审核流程……

别担心，Expo就是为解决这些痛点而生的。它不是简单的脚手架工具，而是一整套“开箱即用”的 React Native 开发体系。而它的核心入口——Expo CLI，正是我们掌控这套系统的钥匙。

本文不堆砌命令列表，而是带你像工程师一样思考：每条命令背后的原理是什么？在什么场景下该用哪一条？如何避免踩坑？我们将以真实项目节奏为主线，深入剖析关键命令，并穿插实战技巧与避坑指南。

从expo init开始：不只是创建项目

很多教程告诉你：“先运行expo init”。但你知道这个命令背后到底发生了什么吗？

当你敲下：

expo init MyTodoApp

Expo 并没有凭空生成文件。它会连接到 expo/templates 仓库，拉取预定义的项目模板。你可以选择：

• blank：最简结构，适合学习或自定义架构。
• tabs：带底部标签页导航（Tab Navigator），适合内容分类明确的应用。
• drawer：侧边栏菜单布局，常见于企业级应用。
• minimal：比 blank 更轻量，几乎不含示例代码。

📌建议实践：初学者选blank，避免被模板中的导航逻辑干扰对核心机制的理解。

执行完成后，你会看到一个干净的项目结构：

MyTodoApp/ ├── App.js ├── app.json ├── package.json └── ...

其中app.json是 Expo 的配置中枢，包含应用名称、图标路径、权限声明等元信息。所有这些都已按最佳实践初始化完毕——这正是 Expo 的价值：把重复劳动自动化，让你专注业务本身。

⚠️ 注意：如果你还没安装 Expo CLI，请先运行：

bash npm install -g expo-cli

或使用 yarn：

bash yarn global add expo-cli

expo start：你的开发引擎

初始化完成，进入项目目录后第一件事就是启动开发服务器：

expo start

这时终端会出现一个二维码和几个快捷键提示。打开手机上的Expo Go应用，扫描二维码，你的应用就跑起来了！

但这背后发生了什么？

Metro 打包器 + WebSocket 实时通信

expo start实际上启动了Metro bundler—— Facebook 官方的 JavaScript 模块打包工具。它将你的.js/.jsx文件编译成可在原生环境中运行的 bundle，并通过 WebSocket 推送给客户端。

更厉害的是HMR（Hot Module Replacement）。当你修改代码保存后，Metro 不仅会重新打包，还会尝试“热替换”变更的模块，而不是整页刷新。这意味着你可以保留当前页面状态继续调试，极大提升开发体验。

快速切换平台的小技巧

不想扫码？可以用命令直接启动模拟器：

expo start --android # 自动拉起 Android 模拟器 expo start --ios # 启动 iOS 模拟器（需 macOS） expo start --web # 在浏览器中预览（需启用 web 支持）

为了方便团队协作，通常会在package.json中封装这些命令：

"scripts": { "start": "expo start", "android": "expo start --android", "ios": "expo start --ios", "web": "expo start --web" }

这样新人加入项目时只需运行npm run android即可快速上手，无需记忆复杂参数。

🔥避坑提醒：

• 确保手机和电脑在同一局域网。
• 防火墙可能拦截默认端口19000和19001，请提前放行。
• 若遇到白屏或连接超时，尝试重启服务或更换网络环境。

当你需要访问原生能力：prebuild与run:android/ios

Expo 的最大优势是简化开发，但它也有边界：某些高级功能（如蓝牙深度控制、特定第三方 SDK）只能在“裸机”（bare workflow）环境下使用。

这时候就需要揭开 Expo 的“黑盒”。

第一步：生成原生工程

运行以下命令生成ios/和android/目录：

npx expo prebuild

这条命令会根据当前配置自动生成对应的 Xcode 工程和 Gradle 项目。从此你就可以像传统 React Native 项目一样编辑原生代码。

第二步：本地构建并运行

有了原生目录后，就可以使用：

expo run:android # 构建并部署到 Android 设备 expo run:ios # 构建 iOS 版本（仅限 macOS）

它们本质上是在调用底层的gradlew assembleDebug或xcodebuild，只是 Expo 帮你封装了复杂的参数。

💡适用场景举例：

• 集成需要手动配置AndroidManifest.xml的广告 SDK。
• 添加自定义推送通知服务。
• 进行性能分析或内存泄漏检测。

⚠️门槛提醒：此模式要求你安装完整的原生开发环境：

• Android：JDK、Android Studio、SDK Tools
• iOS：Xcode 及 Command Line Tools

对新手有一定挑战，建议非必要不 eject。

依赖管理的艺术：为什么必须用expo install

你可能会问：“我不能直接用npm install吗？”

答案是：可以，但非常危险。

React Native 生态中许多库（如react-native-reanimated、react-native-gesture-handler）对 Expo SDK 版本高度敏感。例如，v3 的 reanimated 只能在 Expo SDK 49+ 上运行。如果版本不匹配，轻则警告，重则闪退。

expo install的聪明之处在于：它知道你当前使用的 Expo SDK 版本，并自动为你选择兼容的依赖版本。

比如你要安装相机模块：

expo install expo-camera

它不会简单地装最新版，而是查询官方维护的兼容性表，确保所选版本能正常工作。

同样适用于社区库：

expo install react-native-reanimated react-native-gesture-handler

✅最佳实践：

无论安装什么包，只要项目基于 Expo，一律优先使用expo install。这是保障项目稳定性的第一道防线。

发现问题比解决问题更重要：expo doctor的真正用途

当项目突然无法启动、构建失败、OTA 更新异常时，很多人第一反应是查 Stack Overflow。但其实你应该先运行：

expo doctor

这个命令就像一位经验丰富的“系统医生”，它会检查：

• Node.js 版本是否过低
• Expo SDK 是否存在已知漏洞
• 依赖之间是否有冲突
• 配置文件语法是否正确

输出结果不仅指出问题，还会附带官方文档链接和修复建议。例如：

Warning: react-native-reanimated@2.3.1 requires Expo SDK 44+ Your project is using SDK 42. Consider upgrading. 👉 https://docs.expo.dev/versions/latest/

🧠高阶用法：

在 CI/CD 流程中加入expo doctor --exit-code，一旦发现问题自动中断构建，防止脏代码流入生产环境。

OTA 更新的秘密武器：expo publish

想象一下：线上用户反馈某个按钮点击无效。你修好了代码，然后呢？

传统方式：提交审核 → 等待 24~72 小时 → 用户更新 → 问题解决。
Expo 方式：运行一条命令，几分钟内全球用户自动更新。

这就是expo publish的魔力：

expo publish

它会做三件事：

1. 使用 Metro 打包最新的 JS bundle；
2. 将资源上传至 Expo 托管的 CDN；
3. 更新版本清单（manifest），通知客户端有新版本可用。

下次用户打开 App 时，Expo Updates 模块会自动下载并激活新代码，整个过程对用户透明。

使用发布通道实现灰度发布

你可以通过--release-channel参数区分不同环境：

expo publish --release-channel staging # 发布测试版 expo publish --release-channel production # 正式上线

配合 SDK 中的Updates.checkForUpdateAsync()和fetchUpdateAsync()，你可以实现更精细的控制策略，比如：

• 内部员工强制更新 staging 版本；
• 新用户首次启动时不更新，避免流量消耗；
• 版本差异过大时引导用户去应用商店升级。

⚠️重要限制：

OTA 只能更新 JavaScript 和静态资源，无法更改原生代码或权限声明。涉及原生变更仍需重新构建二进制包。

构建发布包：告别本地编译噩梦

过去，发布 APK/IPA 最头疼的就是本地构建环境不稳定。Gradle 报错、签名失败、Xcode 版本不兼容……这些问题现在都可以交给云端解决。

曾经的方案：expo build:android/ios

expo build:android expo build:ios

这两个命令利用 Expo 云服务远程编译你的应用。你只需提供签名密钥和构建配置，剩下的交给 Expo 完成。

但请注意：该功能已于 2023 年逐步停用，官方推荐迁移到更强大的 EAS（Expo Application Services）。

现代化替代：EAS Build

eas build --platform android eas build --platform ios

EAS 提供更多优势：

• 支持自定义构建镜像（Docker-based）
• 可缓存依赖加速构建
• 允许注入环境变量
• 构建日志实时查看，便于排查问题

✅迁移建议：

新项目直接使用 EAS；老项目尽早迁移。配置文件从app.json升级为eas.json即可。

一个完整的工作流示范：待办事项 App 上线之旅

让我们把所有命令串起来，走一遍真实的开发闭环。

1. 初始化项目

expo init TodoList --template blank cd TodoList

2. 启动开发

npm run android

手机扫码查看效果。

3. 安装依赖

expo install @react-navigation/native react-native-screens react-native-safe-area-context

4. 日常开发与热更新

编写完新功能后，直接发布 OTA：

expo publish --release-channel staging

邀请测试人员验证。

确认无误后推送到生产：

expo publish --release-channel production

5. 准备上线构建包

eas build --platform android --profile preview

其中--profile指向eas.json中定义的构建配置。

6. 发布到应用市场

下载生成的 AAB 文件，上传至 Google Play Console，提交审核。

那些没人告诉你的细节：经验之谈

如何合理使用 Release Channel？

不要只用production和staging。更合理的做法是结合版本号动态生成 channel 名：

expo publish --release-channel prod-v1.2.0

这样你可以精确控制哪些用户接收哪些更新，甚至回滚到旧版本。

什么时候该运行expo doctor？

• 每次升级 Expo SDK 前后
• 引入新的原生模块后
• CI 构建失败时
• 团队成员出现“在我机器上是好的”问题时

OTA 更新真的安全吗？

虽然方便，但也带来风险：恶意攻击者若劫持 CDN，可能注入恶意脚本。因此建议开启Code Signing功能，确保更新包完整性。

我应该 eject 吗？

除非你有明确且持久的原生定制需求，否则永远不要 eject。保持在 managed workflow 中，你能持续享受 Expo 团队带来的自动化红利。

结语：工具的意义是让人更自由

Expo CLI 看似只是一组命令行工具，实则是现代移动开发理念的缩影：把繁琐留给机器，把创造力还给人。

从init到publish，每一个命令都在帮你缩短“想法 → 产品”的距离。你不再需要成为 Xcode 专家或 Gradle 工程师，也能交付高质量的跨平台应用。

未来，随着 EAS 不断整合 CI/CD、监控、A/B 测试等功能，Expo 正朝着“一体化移动开发平台”演进。而今天的你，已经站在了这场变革的起点。

如果你正在寻找一种更快、更稳、更专注的 React Native 开发方式，不妨从今天开始，认真对待每一条 Expo CLI 命令。

👉动手试试看：打开终端，输入expo init，迈出高效开发的第一步。如果有任何疑问，欢迎在评论区交流！