Expo 项目安装、创建与 Android 真机启动指南

中秋还没赏月
66 阅读8分钟

Expo 项目安装、创建与 Android 真机启动指南

本文以 Windows 11 + pnpm + Android 真机 为主要环境，介绍 Expo 项目的前置条件、项目创建方法，以及如何通过 Expo Go 在 Android 手机上运行项目。

一、Expo 简介

Expo 是基于 React Native 的应用开发框架，可以使用 React 和 TypeScript 开发 Android、iOS 和 Web 应用。

对于刚开始学习 Expo 的开发者，最简单的运行方式是：

  1. 在电脑上启动 Expo 项目。
  2. 在 Android 手机上安装 Expo Go。
  3. 使用 Expo Go 扫描项目二维码。
  4. 在真机上预览和调试应用。

这种方式不需要先安装 Android Studio，也不需要配置 Android SDK。

二、开始前需要准备什么

开始前准备以下工具即可：

检查电脑环境：

node --version
pnpm --version

两个命令都能输出版本号即可。

本文以 Android 真机为主。使用 Expo Go 调试时，不需要安装 Android Studio、Android SDK 或 Android Emulator。

三、创建 Expo 项目

1. 进入项目存放目录

打开 终端（ PowerShell 或 Windows Terminal），进入准备好的存放项目的目录：

cd D:\Users\zhangyue\Desktop\demo

2. 创建项目

执行：

pnpm create expo-app@latest my-expo-app

其中，my-expo-app 是项目名称，可以替换成自己的项目名。

创建完成后进入项目目录：

cd my-expo-app

3. 检查项目（可选）

可以执行以下命令检查 Expo 配置和依赖：

pnpm exec expo-doctor

如果没有关键错误，就可以启动项目。

四、在电脑上启动 Expo 项目

确保终端位于项目根目录，然后执行：

pnpm exec expo start

也可以使用项目默认脚本（推荐）：

pnpm start

启动成功后，终端会显示：

  • 项目二维码

  • Metro 开发服务器地址

    例如这样

开发服务器运行期间不要关闭该终端。

五、在 Android 真机上安装 Expo Go

在 Android 手机的应用商店或浏览器(expo.dev/go)中搜索并安装 Expo Go。

安装后打开 Expo Go。首次启动时，系统可能会请求以下权限：

  • 相机权限：用于扫描二维码
  • 通知权限：可按需允许
  • 局域网或网络访问权限：用于连接电脑上的开发服务器

其中，相机和网络访问是扫码运行项目的关键条件。

Expo Go 适合学习、快速预览和使用 Expo SDK 已支持的功能。如果以后使用 Expo Go 不包含的自定义原生模块，需要改用 Development Build。

六、使用 Android 真机运行项目

1. 连接同一个局域网

首先让电脑和 Android 手机连接到同一个局域网。

常见连接方式：

  • 电脑和手机连接同一个 Wi-Fi
  • 电脑使用网线，手机连接同一路由器的 Wi-Fi
  • 手机开启热点，电脑连接该热点

电脑使用网线、手机使用 Wi-Fi 并不一定有问题，关键是两台设备需要位于可以互相访问的局域网中。

尽量不要使用以下网络：

  • 开启设备隔离的公共 Wi-Fi
  • 限制设备互访的校园网或公司网络
  • 需要网页认证的访客网络

2. 启动开发服务器

在项目根目录执行：

pnpm start

终端中会显示二维码。

Windows 第一次启动时，防火墙可能询问是否允许 Node.js 访问网络。

如果没有询问可以在电脑的“设置”中查询：

image-20260825183107005

为了让手机连接电脑，应允许其访问专用网络。（ ！！！！！非常重要）

3. 扫描二维码

在 Android 手机上：

  1. 打开 Expo Go。
  2. 点击扫描二维码的入口。
  3. 扫描电脑终端中显示的二维码。
  4. 等待 JavaScript Bundle 加载完成。
  5. 项目会在 Expo Go 中打开。

首次加载可能需要较长时间。成功打开后，修改项目代码并保存，手机通常会自动刷新。

4. 验证开发环境（可选）

修改项目首页中的一段文字并保存。如果手机画面随之更新，说明以下链路都已正常工作：

  • Expo 项目已成功创建
  • Metro 开发服务器运行正常
  • 手机可以连接电脑
  • Expo Go 可以加载项目
  • 代码热更新正常

七、真机扫描后无法连接怎么办

Android 真机开发中，最常见的问题是手机无法连接电脑上的开发服务器。

1. 确认开发服务器仍在运行

终端中必须保持 pnpm start 运行。如果终端已关闭，重新执行：

pnpm start

2. 确认手机和电脑在同一网络

检查：

  • 两台设备是否连接同一个路由器
  • 手机是否正在使用移动数据
  • 手机是否开启了 VPN
  • 电脑是否开启了会改变网络路由的代理或 VPN
  • 路由器是否开启了 AP Isolation 或客户端隔离

可以临时关闭手机移动数据，避免手机自动切换网络。

3. 检查 Windows 防火墙

如果启动 Expo 时拒绝了 Windows 防火墙提示，手机可能无法访问开发服务器。

微信图片_20260825140939_14_121

应确认 Node.js 可以通过 Windows 防火墙访问 “ 专用网络 ” 。修改后，关闭并重新启动 Expo 开发服务器。

4. 使用 Tunnel 模式

如果当前网络禁止设备互相访问，可以使用 Tunnel：

pnpm exec expo start --tunnel

重新扫描生成的二维码即可。

Tunnel 通过外部服务转发连接，因此：

  • 不要求手机和电脑处于同一局域网
  • 启动和加载速度可能更慢
  • 依赖电脑和手机都能正常访问互联网
  • 仅在 LAN 模式连接失败时使用即可

5. 清除 Metro 缓存

如果二维码可以连接，但项目一直加载、白屏或代码不更新，可以清除缓存：

pnpm exec expo start --clear

然后使用 Expo Go 重新扫描二维码。

6. 检查 Expo Go 与项目 SDK

Expo Go 支持的 Expo SDK 版本有限。如果项目 SDK 过旧，而手机上的 Expo Go 已更新，项目可能无法打开。

新项目建议直接使用：

pnpm create expo-app@latest my-expo-app

已有项目出现版本问题时，先运行：

pnpm exec expo-doctor

根据检查结果处理依赖版本，不要随意单独升级 React Native 或 Expo 的核心依赖。

7. 重启连接链路

仍然无法连接时，可以按以下顺序重试：

  1. 关闭手机中的 Expo Go。
  2. 在终端按 Ctrl + C 停止开发服务器。
  3. 确认电脑和手机网络正常。
  4. 重新执行 pnpm exec expo start。
  5. 重新打开 Expo Go 并扫描二维码。

八、Android 真机调试常用操作

重新加载应用

可以在运行 Expo 的终端中按：

r

也可以在 Expo Go 的开发菜单中选择 Reload。

打开开发菜单

在终端中按：

m

也可以在 Android 手机上摇动设备打开开发菜单。不同设备或系统设置下，摇动手势可能不可用，此时使用终端快捷键更方便。

查看运行日志

应用中的 console.log 通常会显示在运行 Expo 的终端中。例如：

console.log('应用已启动');

调试时应关注终端中的红色错误信息和手机上的错误界面。

停止项目

在运行开发服务器的终端中按：

Ctrl + C

停止后，手机中的 Expo Go 将无法继续从该开发服务器加载项目。

九、安装项目依赖

普通 JavaScript 依赖

使用 pnpm 安装：

eg ：

pnpm add axios

开发依赖使用：

eg ：

pnpm add --save-dev prettier

Expo 或 React Native 原生依赖

优先使用 Expo CLI 安装：

eg ：

pnpm exec expo install expo-camera

expo install 会根据当前 Expo SDK 选择兼容版本。对于 Expo 原生库，不建议直接使用 pnpm add 盲目安装最新版。

安装后可以再次检查项目（可选）：

pnpm exec expo-doctor

不要混用包管理器

项目使用 pnpm 后，应继续使用 pnpm，不要交替执行：

  • npm install
  • yarn install
  • pnpm install

项目中应保留 pnpm-lock.yaml，避免同时出现多个包管理器的锁文件。

十、Expo Go 的适用范围

Expo Go 适合：

  • 学习 Expo 和 React Native
  • 开发普通页面和交互
  • 使用 Expo Go 已内置的 Expo SDK 模块
  • 快速进行 Android 真机预览

以下情况通常需要 Development Build，而不能只依赖 Expo Go：

  • 使用 Expo Go 未包含的第三方原生模块
  • 编写或修改 Android 原生代码
  • 测试特定的原生配置
  • 需要更接近正式安装包的开发环境

刚开始学习时先使用 Expo Go 即可，不需要提前配置 Development Build。

总结

使用 Android 真机开始 Expo 开发，不需要先安装 Android Studio。准备好 Node.js、pnpm、Android 手机和 Expo Go 后，只需要创建项目并启动开发服务器：

pnpm create expo-app@latest my-expo-app
cd my-expo-app
pnpm start

随后使用 Android 手机上的 Expo Go 扫描二维码即可。真机无法连接时，优先检查局域网和 Windows 防火墙，必要时再使用 --tunnel 模式。

avatar
文章
阅读
粉丝