# React Native Expo 热更新项目
> 基于 Expo Router 和 EAS Update 的完整 React Native 项目，支持热更新（OTA）功能
[](https://expo.dev/)
[](https://reactnative.dev/)
[](https://www.typescriptlang.org/)
[](https://pnpm.io/)
## 📖 目录
- [项目特性](#-项目特性)
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [热更新使用指南](#-热更新使用指南)
- [开发指南](#-开发指南)
- [配置说明](#-配置说明)
- [常见问题](#-常见问题)
- [相关资源](#-相关资源)
## ✨ 项目特性
### 核心特性
- 🎯 **Expo Router** - 文件路由系统，类似 Next.js，支持类型安全的导航
- 📘 **TypeScript** - 完整的类型支持，提升代码质量
- 🔥 **EAS Update** - 热更新支持（CodePush 的官方替代方案）
- ⚡ **React Native 新架构** - 启用 Fabric 渲染器和 TurboModules
- 📦 **pnpm** - 快速、节省磁盘空间的包管理器
- 🧭 **标签导航** - 开箱即用的导航示例
- 🎨 **完整主题系统** - 深色/浅色/自动主题切换，完整的颜色配置 🎯
- 📱 **跨平台** - 支持 iOS、Android 和 Web
### 架构特性 🎯
- 📁 **扁平化目录结构** - 清晰的模块组织，符合社区最佳实践
- 🔄 **模块化导出** - 每个目录独立导出，避免循环依赖
- 💾 **双存储系统** - AsyncStorage（持久化）+ SessionStorage（临时）
- 🎨 **主题化组件** - ThemedText 和 ThemedView，自动适配主题
- 🔐 **API 加密** - 请求/响应自动加密解密
- 📊 **状态管理** - Zustand + AsyncStorage 持久化
- ✅ **数据验证** - Zod 表单验证
- 🎯 **类型安全** - 完整的 TypeScript 类型定义
## 🚀 快速开始
### 前置要求
- **Node.js** 18+ ([下载](https://nodejs.org/))
- **pnpm** ([安装指南](https://pnpm.io/installation))
- **Expo Go** App（可选，用于快速预览）
- [iOS App Store](https://apps.apple.com/app/expo-go/id982107779)
- [Android Play Store](https://play.google.com/store/apps/details?id=host.exp.exponent)
### 第一步：安装依赖
```bash
pnpm install
```
### 第二步：启动开发服务器
```bash
pnpm start
```
启动后，你会看到一个二维码和几个选项：
- 按 **`a`** - 在 Android 模拟器/设备上运行
- 按 **`i`** - 在 iOS 模拟器上运行（仅 macOS）
- 按 **`w`** - 在浏览器中运行
- **扫描二维码** - 在 Expo Go App 中运行
### 第三步：在设备上查看
#### 方法 1：使用 Expo Go（推荐用于快速预览）
1. 在手机上安装 Expo Go
2. 扫描终端中显示的二维码
3. 应用会自动加载并运行
#### 方法 2：使用模拟器
**Android 模拟器：**
```bash
pnpm android
```
**iOS 模拟器（仅 macOS）：**
```bash
pnpm ios
```
**Web 浏览器：**
```bash
pnpm web
```
## 📁 项目结构
```
rn-demo/
├── 📱 app/ # Expo Router 路由文件
│ ├── (tabs)/ # 标签导航组
│ │ ├── index.tsx # 首页 - 热更新演示 ⭐
│ │ ├── two.tsx # 第二个标签页
│ │ ├── demo.tsx # 完整示例页面 🎯
│ │ ├── paper.tsx # React Native Paper 示例
│ │ └── _layout.tsx # 标签布局
│ ├── test-page.tsx # 测试页面（无 tabs）🎯
│ ├── _layout.tsx # 根布局 - 自动检查更新 ⭐
│ ├── modal.tsx # 模态页面示例
│ ├── +html.tsx # Web HTML 模板
│ └── +not-found.tsx # 404 页面
│
├── 💻 业务代码目录
├── utils/ # 工具函数
│ ├── network/ # 网络相关
│ │ ├── api.ts # Axios API 配置
│ │ ├── helper.ts # 加密/解密工具
│ │ └── error.ts # 错误处理
│ ├── storage.ts # AsyncStorage 封装
│ ├── sessionStorage.ts # Session Storage 实现 🎯
│ ├── storageManager.ts # 统一存储管理器 🎯
│ ├── config.ts # 配置管理
│ ├── date.ts # Day.js 日期工具
│ ├── common.ts # 通用工具
│ └── index.ts # 统一导出
│
├── stores/ # Zustand 状态管理
│ ├── userStore.ts # 用户状态
│ ├── settingsStore.ts # 应用设置
│ ├── tenantStore.ts # 租户状态 🎯
│ └── index.ts # 统一导出
│
├── schemas/ # Zod 验证规则
│ ├── auth.ts # 认证验证
│ ├── user.ts # 用户验证
│ └── index.ts # 统一导出
│
├── services/ # API 服务层
│ ├── authService.ts # 认证服务
│ ├── userService.ts # 用户服务
│ ├── tenantService.ts # 租户服务 🎯
│ └── index.ts # 统一导出
│
├── hooks/ # 自定义 Hooks
│ ├── useDebounce.ts # 防抖 Hook
│ ├── useThrottle.ts # 节流 Hook
│ ├── useHaptics.ts # 触觉反馈 Hook
│ ├── useRequest.ts # 请求 Hook 🎯
│ ├── useTheme.ts # 主题 Hooks 🎯
│ ├── useColorScheme.ts # 颜色方案 Hook 🎯
│ ├── useColorScheme.web.ts # Web 平台颜色方案 🎯
│ ├── useClientOnlyValue.ts # 客户端值 Hook 🎯
│ ├── useClientOnlyValue.web.ts # Web 平台客户端值 🎯
│ └── index.ts # 统一导出
│
├── types/ # TypeScript 类型
│ ├── api.ts # API 类型定义
│ └── index.ts # 统一导出
│
├── screens/ # 业务页面组件 🎯
│ └── index.ts # 统一导出
│
├── 🧩 components/ # 可复用组件
│ ├── Themed.tsx # 主题化组件 🎯
│ ├── ThemeDemo.tsx # 主题演示组件 🎯
│ ├── ExternalLink.tsx # 外部链接组件
│ └── index.ts # 统一导出 🎯
│
├── 🎨 theme/ # 主题系统 🎯 NEW!
│ ├── index.ts # 统一导出
│ ├── utils.ts # 主题工具函数
│ └── styles.ts # 样式工厂（类似 CSS 类名）
│
├── 🎯 constants/ # 常量配置
│ ├── Colors.ts # 颜色主题（完整配置）🎯
│ └── network.ts # 网络常量
│
├── 🎨 assets/ # 静态资源
│ ├── images/ # 图片资源
│ └── fonts/ # 字体文件
│
├── 📚 docs/ # 项目文档 🎯
│ ├── USAGE_EXAMPLES.md # 使用示例
│ ├── LIBRARIES.md # 工具库使用指南
│ ├── PROJECT_STRUCTURE_V2.md # 项目结构说明 🎯
│ ├── MIGRATION_TO_FLAT_STRUCTURE.md # 扁平化迁移报告 🎯
│ ├── STORES_ARCHITECTURE.md # Stores 架构设计 🎯
│ ├── STORAGE_GUIDE.md # 存储系统使用指南 🎯
│ ├── THEME_GUIDE.md # 主题系统使用指南 🎯 NEW!
│ └── ... 更多文档
│
├── 🔧 scripts/ # 脚本文件
│ └── proxy-server.js # 代理服务器 🎯
│
├── ⚙️ 配置文件
│ ├── .env.development # 开发环境变量 🎯
│ ├── .env.production # 生产环境变量 🎯
│ ├── app.json # Expo 配置 ⭐
│ ├── eas.json # EAS 构建和更新配置 ⭐
│ ├── package.json # 项目依赖
│ ├── pnpm-lock.yaml # pnpm 锁文件
│ ├── tsconfig.json # TypeScript 配置
│ └── .gitignore # Git 忽略文件
│
└── 📄 文档文件
├── README.md # 项目主文档（本文件）
└── CHANGELOG.md # 更新日志
⭐ = 热更新相关的关键文件
🎯 = 新增/更新的文件/目录
```
### 关键目录说明
#### 📱 `app/` - 路由和页面
- **`app/_layout.tsx`** - 应用启动时自动检查更新
- **`app/(tabs)/index.tsx`** - 热更新演示页面
- **`app/(tabs)/demo.tsx`** - 完整示例页面，展示所有工具的使用 🎯
- **`app/test-page.tsx`** - 测试页面示例（不包含底部 tabs）🎯
#### 💻 业务代码目录（扁平化结构）🎯
项目采用扁平化目录结构，所有业务模块都在根目录下：
- **`utils/`** - 工具函数
- 网络请求（Axios + 加密）
- 存储管理（AsyncStorage + SessionStorage）🎯
- 日期处理（Day.js）
- 配置管理
- **`stores/`** - 状态管理（Zustand）
- 用户状态（登录、用户信息）
- 应用设置（主题、语言、触觉反馈）
- 租户状态 🎯
- **`schemas/`** - 数据验证（Zod）
- 认证表单验证
- 用户数据验证
- **`services/`** - API 服务层
- 认证服务
- 用户服务
- 租户服务 🎯
- **`hooks/`** - 自定义 Hooks
- 防抖/节流
- 触觉反馈
- 请求管理 🎯
- 主题 Hooks（useColorScheme, useTheme, useClientOnlyValue）🎯
- **`types/`** - TypeScript 类型定义
- **`screens/`** - 业务页面组件 🎯
- **`theme/`** - 主题系统 🎯 NEW!
- 统一的主题配置导出
- 主题工具函数
- 样式工厂（类似 CSS 类名）
每个目录都有 `index.ts` 文件，负责统一导出该目录下的所有模块。
#### 🧩 `components/` - 可复用组件
- **`Themed.tsx`** - 主题化组件（ThemedText, ThemedView）🎯
- **`ThemeDemo.tsx`** - 主题演示组件 🎯
#### 📚 `docs/` - 项目文档 🎯
完善的项目文档，包含：
- **使用指南** - 如何使用各个工具
- **代码示例** - 实际的代码示例
- **配置说明** - 项目配置详解
- **架构设计** - Stores 架构、存储系统等
- **主题系统** - 主题配置和样式使用指南 🎯 NEW!
- **迁移报告** - 扁平化目录结构迁移
### 核心文件说明
#### 热更新相关 ⭐
- **`app.json`** - Expo 配置，包含热更新设置
- **`eas.json`** - EAS 构建和更新通道配置
- **`app/_layout.tsx`** - 自动检查更新逻辑
- **`app/(tabs)/index.tsx`** - 手动检查更新功能
#### 工具配置 🎯
- **各目录的 `index.ts`** - 统一导出，从这里导入所有工具
- **`.env.development` / `.env.production`** - 环境变量配置 🎯
- **`tsconfig.json`** - 配置了路径别名 `@/*`
### 已安装的工具库
项目已安装并配置好以下工具库：
| 类别 | 工具库 | 用途 | 状态 |
| ------------ | ----------------------------------------- | ------------------- | ---- |
| **工具类** | lodash-es | JavaScript 工具函数 | ✅ |
| | dayjs | 日期处理 | ✅ |
| | axios | HTTP 请求 | ✅ |
| **状态管理** | zustand | 轻量级状态管理 | ✅ |
| **表单处理** | react-hook-form | 表单管理 | ✅ |
| | zod | 数据验证 | ✅ |
| **原生功能** | @react-native-async-storage/async-storage | 本地存储 | ✅ |
| | expo-image | 优化的图片组件 | ✅ |
| | expo-haptics | 触觉反馈 | ✅ |
| **UI 组件** | react-native-paper | Material Design 组件 | ✅ |
### 快速开始
1. **查看完整示例** - 运行应用，点击 "Demo" tab 🎯
2. **阅读文档** - 查看 [docs/](./docs/) 目录中的文档
3. **使用工具** - 从各个模块目录导入所需的工具
```typescript
// ✅ 推荐：从模块目录导入
import { Storage, SessionStorage, StorageManager, formatDate } from '@/utils';
import { useUser, useTheme, useLanguage } from '@/stores';
import { authService, userService } from '@/services';
import { useDebounce, useHaptics, useColorScheme, useThemeColors, useClientOnlyValue } from '@/hooks';
import { loginSchema } from '@/schemas';
// ✅ 主题系统：统一从 theme 目录导入 🎯 NEW!
import {
useColorScheme,
useThemeColors,
ThemedText,
ThemedView,
commonStyles,
createThemeStyles,
} from '@/theme';
// ✅ 也可以：直接从具体文件导入
import { useUser } from '@/stores/userStore';
import { formatDate } from '@/utils/date';
```
## 🔥 热更新使用指南
> **重要提示**：热更新功能需要在真实构建（Development Build 或 Production Build）中测试，Expo Go 不支持自定义热更新配置。
### 步骤 1：登录 EAS
```bash
eas login
```
如果没有账号，访问 [expo.dev](https://expo.dev) 注册一个免费账号。
### 步骤 2：初始化 EAS 项目
```bash
eas init
```
这会：
- 创建一个唯一的项目 ID
- 自动更新 `app.json` 中的 `extra.eas.projectId`
### 步骤 3：构建开发版本
**Android 开发构建：**
```bash
eas build --profile development --platform android
```
**iOS 开发构建（需要 macOS 和 Apple 开发者账号）：**
```bash
eas build --profile development --platform ios
```
构建过程需要 **10-20 分钟**。完成后：
1. 在 [expo.dev](https://expo.dev) 控制台下载构建的 APK/IPA 文件
2. 安装到你的设备上
### 步骤 4：发布热更新
1. **修改代码**（例如修改 `app/(tabs)/index.tsx` 中的文本）
2. **发布更新到指定通道：**
```bash
# 发布到开发通道
eas update --channel development --message "测试热更新功能"
# 发布到预览通道
eas update --channel preview --message "修复了某个 bug"
# 发布到生产通道
eas update --channel production --message "v1.0.1: 添加了新功能"
```
### 步骤 5：测试更新
1. 打开已安装的应用
2. 点击首页的 **"检查更新"** 按钮
3. 应用会自动下载更新
4. 点击 **"立即重启"** 应用更新
5. 重启后即可看到更新内容 🎉
### 更新通道说明
项目配置了三个更新通道（在 `eas.json` 中定义）：
| 通道 | 用途 | 适用场景 |
| --------------- | -------- | -------------- |
| **development** | 开发环境 | 日常开发和测试 |
| **preview** | 预览环境 | 内部测试和 QA |
| **production** | 生产环境 | 正式发布给用户 |
不同的构建配置会订阅不同的更新通道：
```bash
# 构建订阅 development 通道的版本
eas build --profile development --platform android
# 构建订阅 preview 通道的版本
eas build --profile preview --platform android
# 构建订阅 production 通道的版本
eas build --profile production --platform android
```
### 推荐的发布流程
```bash
# 1. 开发和本地测试
pnpm start
# 2. 发布到 preview 通道进行内部测试
eas update --channel preview --message "测试新功能"
# 3. 测试通过后，发布到 production 通道
eas update --channel production --message "v1.0.1: 修复了登录问题"
# 4. 如果需要回滚
eas update --channel production --branch main --message "回滚到稳定版本"
```
### 监控和管理更新
```bash
# 查看所有更新历史
eas update:list
# 查看特定通道的更新
eas update:list --channel production
# 查看更新详情
eas update:view [update-id]
```
## 💻 开发指南
### 常用命令
```bash
# 开发相关
pnpm start # 启动开发服务器
pnpm android # 在 Android 上运行
pnpm ios # 在 iOS 上运行（仅 macOS）
pnpm web # 在浏览器中运行
# 热更新相关
eas login # 登录 EAS
eas init # 初始化 EAS 项目
eas build --profile development --platform android # 构建开发版本
eas update --channel development --message "更新说明" # 发布热更新
eas update:list # 查看更新历史
# 构建相关
eas build --profile preview --platform android # 构建预览版本
eas build --profile production --platform android # 构建生产版本
```
### 修改代码示例
尝试修改以下内容来测试热更新：
#### 示例 1：修改首页标题
打开 `app/(tabs)/index.tsx`，找到：
```tsx
🚀 热更新演示
```
改为：
```tsx
🎉 热更新测试成功！
```
#### 示例 2：修改按钮样式
在 `app/(tabs)/index.tsx` 的 `styles` 中修改：
```tsx
button: {
backgroundColor: '#FF6B6B', // 改为红色
paddingHorizontal: 30,
paddingVertical: 15,
borderRadius: 10,
marginBottom: 20,
minWidth: 200,
alignItems: 'center',
},
```
#### 示例 3：添加新功能
在首页添加一个计数器：
```tsx
const [count, setCount] = useState(0);
// 在 JSX 中添加
setCount(count + 1)}>
点击次数: {count}
;
```
修改后，运行 `eas update` 发布更新，然后在应用中检查更新即可看到变化。
### 自定义更新行为
#### 自动静默更新
修改 `app/_layout.tsx` 中的更新逻辑，移除 Alert 提示：
```tsx
if (update.isAvailable) {
await Updates.fetchUpdateAsync();
await Updates.reloadAsync(); // 直接重启，不提示
}
```
#### 强制更新
不提供"稍后"选项：
```tsx
Alert.alert(
'发现新版本',
'请更新到最新版本',
[
{
text: '立即更新',
onPress: async () => {
await Updates.reloadAsync();
},
},
],
{ cancelable: false } // 不可取消
);
```
## ⚙️ 配置说明
### app.json 配置
关键配置项：
```json
{
"expo": {
"name": "rn-demo",
"slug": "rn-demo",
"version": "1.0.0",
"newArchEnabled": true, // 启用 React Native 新架构
"updates": {
"url": "https://u.expo.dev/your-project-id" // EAS Update 服务器
},
"runtimeVersion": {
"policy": "appVersion" // 运行时版本策略
},
"plugins": [
"expo-router", // Expo Router 插件
"expo-updates" // 热更新插件
],
"ios": {
"bundleIdentifier": "com.rndemo.app"
},
"android": {
"package": "com.rndemo.app"
}
}
}
```
**配置说明：**
- `updates.url` - EAS Update 服务器地址（运行 `eas init` 后自动生成）
- `runtimeVersion.policy` - 运行时版本策略，确保更新兼容性
- `appVersion` - 基于 `version` 字段（当前使用）
- `nativeVersion` - 基于原生构建号
- `plugins` - 启用的 Expo 插件
- `newArchEnabled` - 启用 React Native 新架构（Fabric + TurboModules）
### eas.json 配置
构建和更新配置：
```json
{
"build": {
"development": {
"developmentClient": true, // 开发客户端
"distribution": "internal", // 内部分发
"channel": "development" // 订阅 development 更新通道
},
"preview": {
"distribution": "internal",
"channel": "preview" // 订阅 preview 更新通道
},
"production": {
"channel": "production" // 订阅 production 更新通道
}
}
}
```
**配置说明：**
- `developmentClient` - 是否为开发客户端（包含开发工具）
- `distribution` - 分发方式（`internal` 或 `store`）
- `channel` - 更新通道，决定应用接收哪个通道的更新
## 📋 热更新最佳实践
### 何时使用热更新
✅ **适合热更新的场景：**
- ✅ 修复 JavaScript/TypeScript 代码 bug
- ✅ 更新 UI 样式和布局
- ✅ 修改业务逻辑
- ✅ 更新文本内容和翻译
- ✅ 调整配置参数
- ✅ 添加新的 JS 功能
❌ **不适合热更新的场景（需要重新构建）：**
- ❌ 添加/删除原生依赖（如 `react-native-camera`）
- ❌ 修改原生代码（iOS/Android）
- ❌ 更改应用权限（如相机、位置权限）
- ❌ 修改 `app.json` 中的原生配置
- ❌ 升级 React Native 或 Expo SDK 版本
- ❌ 修改应用图标或启动屏幕
### 版本管理策略
**appVersion 策略**（当前使用）：
- 基于 `app.json` 中的 `version` 字段
- ✅ 优点：简单直观，易于理解
- ⚠️ 注意：每次原生构建需要手动更新版本号
**nativeVersion 策略**：
- 基于原生构建号（iOS 的 `buildNumber`，Android 的 `versionCode`）
- ✅ 优点：自动管理，无需手动更新
- ⚠️ 注意：需要配置原生构建号
### 更新策略建议
1. **开发阶段**：频繁发布到 `development` 通道
2. **测试阶段**：发布到 `preview` 通道，进行 QA 测试
3. **生产发布**：测试通过后发布到 `production` 通道
4. **紧急修复**：直接发布到 `production` 通道，快速修复线上问题
## ❓ 常见问题
### Q: 为什么在 Expo Go 中看不到热更新功能？
**A:** Expo Go 是开发工具，不支持自定义热更新。需要使用 `eas build` 构建真实应用。
### Q: 更新后没有生效？
**A:** 检查以下几点：
1. 确保应用完全关闭后重新打开（不是后台切换）
2. 检查更新通道是否匹配（development/preview/production）
3. 确保 `runtimeVersion` 匹配
4. 查看控制台是否有错误信息
5. 检查网络连接
### Q: 如何回滚到之前的版本？
**A:**
```bash
# 查看更新历史
eas update:list --channel production
# 重新发布之前的更新
eas update --channel production --branch main --message "回滚到稳定版本"
```
### Q: 热更新的大小限制是多少？
**A:** EAS Update 没有严格的大小限制，但建议：
- 保持更新包 < 10MB 以确保良好的用户体验
- 避免在更新中包含大量图片或资源文件
- 使用 CDN 托管大型资源
### Q: 如何强制用户更新？
**A:** 修改 `app/_layout.tsx` 中的更新逻辑：
```tsx
if (update.isAvailable) {
await Updates.fetchUpdateAsync();
Alert.alert(
'发现新版本',
'请更新到最新版本',
[{ text: '立即更新', onPress: async () => await Updates.reloadAsync() }],
{ cancelable: false } // 不可取消
);
}
```
### Q: 更新检查的频率是多少？
**A:**
- **应用启动时**：自动检查（在 `app/_layout.tsx` 中配置）
- **手动检查**：用户点击"检查更新"按钮
- **后台检查**：可以配置定时检查（需要自己实现）
### Q: 如何在开发时测试热更新？
**A:**
1. 构建 Development Build：`eas build --profile development --platform android`
2. 安装到设备
3. 修改代码
4. 发布更新：`eas update --channel development --message "测试"`
5. 在应用中点击"检查更新"
### Q: Web 平台的警告信息怎么处理？
**A:** 运行 `pnpm web` 时可能会看到 `pointerEvents` 的弃用警告，这是 `react-native-web` 库的内部问题，不影响功能，可以安全忽略。详见 [docs/KNOWN_ISSUES.md](./docs/KNOWN_ISSUES.md)。
## 💡 开发提示
- 开发时使用 `pnpm start` 即可，支持快速刷新（Fast Refresh）
- 只有在测试热更新功能时才需要构建真实应用
- 热更新只能更新 JavaScript/TypeScript 代码，不能更新原生代码
- 建议使用 Git 管理代码版本，方便回滚
- 每次发布更新时添加清晰的 `--message` 说明，便于追踪
## 📚 相关资源
### 官方文档
- [Expo 官方文档](https://docs.expo.dev/)
- [Expo Router 文档](https://docs.expo.dev/router/introduction/)
- [EAS Update 文档](https://docs.expo.dev/eas-update/introduction/)
- [EAS Build 文档](https://docs.expo.dev/build/introduction/)
- [React Native 文档](https://reactnative.dev/)
### 学习资源
- [Expo Router 最佳实践](https://docs.expo.dev/router/best-practices/)
- [EAS Update 最佳实践](https://docs.expo.dev/eas-update/best-practices/)
- [React Native 新架构](https://reactnative.dev/docs/the-new-architecture/landing-page)
### 社区
- [Expo Discord](https://chat.expo.dev/)
- [Expo Forums](https://forums.expo.dev/)
- [React Native Community](https://reactnative.dev/community/overview)
## 📚 项目文档
更多详细文档请查看 [docs](./docs/) 目录：
### 使用指南
- **[使用示例](./docs/USAGE_EXAMPLES.md)** - 实际代码示例
- **[工具库使用指南](./docs/LIBRARIES.md)** - 详细的工具库使用方法和示例
- **[存储系统使用指南](./docs/STORAGE_GUIDE.md)** - AsyncStorage 和 SessionStorage 使用 🎯
---
**祝你开发愉快！** 🎉
如有问题，请查看 [常见问题](#-常见问题) 或访问 [Expo 官方文档](https://docs.expo.dev/)。