2026年1月

当前的 React Native 开发生态中 Expo 已成为官方主推和社区广泛采用的开发方案。相比传统的 React Native CLI，Expo 有更简洁的项目初始化流程、更强大的工具链支持以及跨平台预览能力，适合初学者快速上手和中小型项目高效开发。

React Native CLI 依然可用，但其配置复杂、原生依赖管理繁琐，容易在不同操作系统上遇到兼容性问题。Expo 通过托管工作流（Managed Workflow）简化了原生模块的集成与构建流程，是现代 React Native 开发的首选方式。

本文将带你从零开始，完整走一遍使用 Expo 创建 React Native 项目、本地运行调试、打包 Android APK 与 iOS IPA 的全流程，涵盖环境准备、开发调试、签名配置及发布准备等关键环节。

一、环境准备

在开始之前，确保你的开发机器已安装以下工具：

Node.js
包管理器：npm、yarn 或 pnpm 都可以，推荐优先用 npm 或 pnpm，后者在性能和依赖扁平化方面表现更好。

尽量保持所有工具为最新稳定版本。旧的 Node.js 或 npm 可能导致 node_modules 安装失败、依赖冲突或构建报错，出现莫名其妙的问题。

验证安装是否成功

打开终端（Terminal），依次执行以下命令：

node -v
npm -v

若能正常输出版本号（例如 v20.11.0 和 10.2.0），说明环境已就绪。

二、创建 React Native 项目

Expo 推荐使用 create-expo-app 快速初始化项目，无需手动配置 Webpack、Babel 原生工程。

初始化项目

在你希望存放项目的目录下执行：

npx create-expo-app myApp

创建一个标准 Expo 项目结构，里面有基础页面、配置文件和依赖项。

进入项目并启动开发服务器

cd myApp
npm start

成功启动后，终端会显示 Metro 打包服务（Metro Bundler）的运行界面，并自动打开浏览器页签（Expo DevTools）。

此时你会看到：

一个 ASCII 风格的二维码
一行提示文字：Scan the QR code above with Expo Go (Android) or the Camera app (iOS)
多个快捷操作按钮（如运行模拟器、Web 预览等）

三、运行方式

Expo 支持多种方式运行应用。

1. 手机扫码运行

Android 设备

在 Google Play 商店下载并安装 Expo Go 应用。
打开应用 → 点击 "Scan QR Code" 。
对准电脑终端或浏览器中显示的二维码进行扫描。
应用将自动加载并运行。

iOS 设备

直接使用 系统相机 App 扫描二维码。
扫描后会弹出一个链接通知，点击选择在 Expo Go 中打开。
应用加载运行。

优势：无需数据线、无需编译，热重载（HMR）支持良好，非常适合真机调试。

2. 模拟器运行

在 Metro 终端界面中按对应键即可快速启动：

按 a：启动 Android 模拟器（需已安装 Android Studio）
按 i：启动 iOS 模拟器（仅限 macOS 用户）
按 w：在浏览器中打开 Web 预览（基于 React Native for Web）

提示：Web 预览虽不能完全还原原生行为，但可用于快速验证 UI 布局和部分交互逻辑。

四、Android 打包

完成开发并准备发布测试包时，需要将项目构建成原生安装包（APK）。以下是基于 Expo 裸工作流（Bare Workflow）的手动打包流程。

配置 Android 构建环境

安装 Android Studio（推荐最新稳定版），安装过程中确保包含：
- Android SDK
- Android SDK Platform-Tools
- Android SDK Build-Tools
- Android Emulator（可选）
配置系统环境变量：
- 新建系统变量 ANDROID_HOME，值为 SDK 路径（常见路径）：

C:\Users\<你的用户名>\AppData\Local\Android\Sdk

- 将以下路径添加到 `PATH`：

%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\emulator  （可选，用于命令行启动模拟器）

验证：终端执行 adb devices，若有设备列表返回则说明配置成功。

进入项目并运行原生构建命令

# 在项目根目录执行
npx expo run:android

首次运行可能出现红字警告提示未检测到设备或模拟器，可暂时忽略。此命令会尝试连接设备或启动模拟器。

随后进入原生工程目录：

cd android

创建 `local.properties` 文件（指定 SDK 路径）

在 android/ 目录下创建 local.properties 文件，内容如下（Windows 示例）：

sdk.dir=C:\\Users\\<你的用户名>\\AppData\\Local\\Android\\Sdk

注意：如果是 Windows，路径中的反斜杠需用双反斜杠转义，且路径必须真实存在。

生成不同类型的 APK 包

1. 生成 Debug 包（用于测试）

./gradlew assembleDebug

输出路径：android/app/build/outputs/apk/debug/app-debug.apk
未签名，仅用于本地测试，不可上架。

2. 生成 Release 包（用于发布）

./gradlew assembleRelease

输出路径：android/app/build/outputs/apk/release/app-release.apk
可发布，但必须完成签名配置，否则无法安装。

五、Release 签名配置

为了发布到应用市场，APK 必须经过数字签名。以下是完整的签名流程配置。

1. 生成 Keystore 文件

在项目合适位置（如 android/app/）生成密钥库：

keytool -genkeypair -v -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 \
-keystore keystor.jks -alias keystor

将生成的 keystor.jks 文件复制到 android/app/ 目录下。

2. 配置全局变量（`android/gradle.properties`）

在该文件中添加以下内容（若不存在可手动创建）：

MYAPP_UPLOAD_STORE_FILE=keystor.jks
MYAPP_UPLOAD_KEY_ALIAS=keystor
MYAPP_UPLOAD_STORE_PASSWORD=你的仓库密码
MYAPP_UPLOAD_KEY_PASSWORD=你的密钥密码

安全建议：不要将密码硬编码在代码中，可考虑使用环境变量或 CI/CD 秘钥管理。

3. 修改构建脚本（`android/app/build.gradle`）

找到 android {... } 块内的 signingConfigs，修改 release 配置：

signingConfigs {
    release {
        if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
            storeFile file(MYAPP_UPLOAD_STORE_FILE)
            storePassword MYAPP_UPLOAD_STORE_PASSWORD
            keyAlias MYAPP_UPLOAD_KEY_ALIAS
            keyPassword MYAPP_UPLOAD_KEY_PASSWORD
        }
    }
}

同时确保 buildTypes.release 使用了该签名配置：

buildTypes {
    release {
        signingConfig signingConfigs.release
        minifyEnabled false
        shrinkResources false
    }
}

完成签名后重新打包

./gradlew clean
./gradlew assembleRelease

此时生成的 app-release.apk 即为已签名的正式发布包，可用于内测或上传应用商店。

六、iOS 打包

重要提醒：在 Windows 系统上无法编译 iOS 安装包。iOS 构建必须在 macOS 系统 上完成，并需配备 Xcode 和真实设备测试。

打包前提条件

一台运行较新 macOS 的 Mac 电脑
已安装 Xcode（App Store 下载）
已安装 Command Line Tools
网络通畅（建议开启代理以加速依赖下载）
已有可运行的 Expo 项目

1. 验证 Xcode 命令行工具

终端执行：

xcode-select -p

预期输出：

/Applications/Xcode.app/Contents/Developer

若无输出，请运行：

sudo xcode-select --install

2. 安装依赖并预构建项目

npm install
npx expo prebuild -p ios

prebuild 命令会根据 app.json 配置生成原生工程目录（ios/ 和 android/）。若已有原生目录，可加 --clean 强制重建。

若提示 CocoaPods 错误

请先安装 Homebrew（若未安装）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

再安装 CocoaPods：

brew install cocoapods

然后进入 ios/ 目录执行：

cd ios
pod install --repo-update

3. 使用 Xcode 打开项目

打开生成的 Workspace 文件：

open MyApp.xcworkspace

务必打开 **.xcworkspace**，而非 .xcodeproj，否则可能导致依赖加载失败。

4. 登录 Apple ID 并配置签名

个人开发者账号（未支付 $99/年）

在 Xcode 中进入 Preferences > Accounts，点击 “+” 添加 Apple ID。
登录后选中该账号，在项目 General 设置中选择对应的 Team。
同意最新的开发者协议（可能需访问 Apple Developer 网站确认）。

5. 添加设备 UDID

使用 “爱思助手” 获取 iPhone 的 UDID，使用 https://www.applicationloader.net 来添加UDID。

完成后重启 Xcode，确保签名状态变为 “Ready to Run”。

6. 手动生成 IPA

确保无误之后编译 Archive。

编译无误完成后会弹出如下界面：

在 Xcode 的 Products 目录下找到 .app 文件。
新建一个文件夹命名为 Payload。
将 .app 文件复制进去。
右键压缩 Payload 文件夹 → 得到 Payload.zip。
将 .zip 改名为 .ipa，即得到可安装的 IPA 包。

可通过邮件、企业分发平台等方式发送给测试人员安装。

七、结语

通过 Expo 构建 React Native 项目，不仅能享受“开箱即用”的开发体验，还能灵活切换托管与裸工作流，在需要时深入原生配置进行定制化打包。

场景	推荐方式
快速原型开发	Expo 托管工作流 + Expo Go 扫码
内测发布	配置签名后构建 Release APK/IPA
上架应用市场	使用 Expo Application Services (EAS) 或 Xcode 归档上传
持续集成	推荐使用 EAS Build + CI/CD 工具链

随着 Expo 对 EAS（Expo Application Services）的持续优化，未来开发者甚至可以完全脱离本地原生环境，通过云端构建一键生成 Android 和 iOS 安装包，进一步降低入门门槛。

从零开始的React Native项目创建