正在加载文档...
文档内容较大，正在处理中，请稍候
正在加载文档...
文档内容较大，正在处理中，请稍候
EAS Build 是 Expo 官方推荐的云端构建服务，无需本地 Android 开发环境。
cd apps/app-rn-ts
pnpm run eas:login如果没有账号，先注册：
npx eas-cli registerpnpm run eas:configure预览版 APK（使用生产环境 API）：
pnpm run build:android:apk开发版 APK（使用开发环境 API）：
pnpm run build:android:dev生产版 AAB（用于正式发布）：
pnpm run build:android:prod构建完成后，EAS 会提供下载链接，你可以：
如果你有 Docker，可以使用 EAS 的本地构建功能。这样可以避免网络问题，构建速度也更快。
Docker Desktop：确保已安装并运行
docker --version
docker psEAS CLI：已包含在项目依赖中
预览版 APK（使用生产环境 API）：
pnpm run build:android:apk:local开发版 APK（使用开发环境 API）：
pnpm run build:android:dev:local生产版 AAB（用于正式发布）：
pnpm run build:android:prod:local如果你有 Android Studio 和本地 Android 开发环境，可以使用完全本地构建。
1. 生成原生 Android 项目
cd apps/app-rn-ts
npx expo prebuild --platform android --clean2. 使用 Android Studio 构建
Open → 选择 apps/app-rn-ts/android 目录Build → Build Bundle(s) / APK(s) → Build APK(s)android/app/build/outputs/apk/debug/ 或 release/ 目录3. 使用命令行构建
cd apps/app-rn-ts/android
# 构建 Debug APK
./gradlew assembleDebug
# 构建 Release APK（需要配置签名）
./gradlew assembleRelease4. APK 文件位置
android/app/build/outputs/apk/debug/app-debug.apkandroid/app/build/outputs/apk/release/app-release.apk注意： Release APK 需要配置签名密钥，建议使用 EAS Build 处理签名。
项目已配置了三种构建配置：
development：开发构建
http://localhost:8888)preview-apk：预览构建（推荐用于测试）
https://admin.liyq666.top)production：生产构建
Apple Developer 账号：必须拥有以下之一
Expo 账号：需要注册 Expo 账号（免费）
EAS CLI：已包含在项目依赖中
注意：iOS 应用必须使用 Apple Developer 账号签名才能安装到真机。没有账号只能构建模拟器版本。
EAS Build 是 Expo 官方推荐的云端构建服务，无需本地 macOS 和 Xcode 环境。
cd apps/app-rn-ts
pnpm run eas:login如果没有账号，先注册：
npx eas-cli registerpnpm run eas:configure开发版（使用开发环境 API）：
pnpm run build:ios:dev预览版（使用生产环境 API，用于测试）：
pnpm run build:ios:preview生产版（用于正式发布）：
pnpm run build:ios:prod首次构建 iOS 时，EAS 会提示你：
登录 Apple Developer 账号
选择证书管理方式
等待构建完成
构建完成后，你可以：
如果你有 macOS 系统，可以使用本地构建。这样可以避免网络问题，构建速度也更快。
sudo gem install cocoapods验证环境：
# 检查 Xcode 版本
xcodebuild -version
# 检查 CocoaPods
pod --version
# 检查 Docker
docker --version
docker ps开发版：
pnpm run build:ios:dev:local预览版：
pnpm run build:ios:preview:local生产版：
pnpm run build:ios:prod:localsudo xcodebuild -license accept如果你有 macOS 和 Xcode，可以使用完全本地构建。这种方式需要手动配置签名和配置文件。
sudo gem install cocoapods1. 生成原生 iOS 项目
cd apps/app-rn-ts
npx expo prebuild --platform ios --clean2. 安装 CocoaPods 依赖
cd ios
pod install
cd ..3. 使用 Xcode 构建
Open → 选择 apps/app-rn-ts/ios 目录中的 .xcworkspace 文件（不是 .xcodeproj）Product → Archive 构建归档4. 使用命令行构建（高级）
cd apps/app-rn-ts/ios
# 构建归档
xcodebuild -workspace app-rn-ts.xcworkspace \
-scheme app-rn-ts \
-configuration Release \
-sdk iphoneos \
-archivePath build/app-rn-ts.xcarchive \
archive
# 导出 IPA（需要配置 ExportOptions.plist）
xcodebuild -exportArchive \
-archivePath build/app-rn-ts.xcarchive \
-exportPath build \
-exportOptionsPlist ExportOptions.plist注意： 完全本地构建需要手动配置签名和配置文件，建议使用 EAS Build 自动处理。
构建产物位置：
ios/build/app-rn-ts.xcarchiveios/build/app-rn-ts.ipa（导出后）项目已配置了四种构建配置：
development：开发构建
preview：预览构建（iOS）
preview-apk：预览构建（Android）
https://admin.liyq666.top)production：生产构建
项目配置位于 apps/app-rn-ts/app.json：
Android 配置：
com.wladmin.app1.0.0iOS 配置：
com.wladmin.app1.0.0修改配置示例：
{
"expo": {
"version": "1.0.1",
"android": {
"package": "com.wladmin.app",
"permissions": ["CAMERA", "READ_EXTERNAL_STORAGE"]
},
"ios": {
"bundleIdentifier": "com.wladmin.app",
"infoPlist": {
"NSCameraUsageDescription": "需要访问相机来拍摄头像",
"NSPhotoLibraryUsageDescription": "需要访问相册来选择头像"
}
}
}
}构建时会根据 eas.json 中的 env 配置设置环境变量：
EXPO_PUBLIC_ENV=development：开发环境EXPO_PUBLIC_ENV=production：生产环境这些环境变量会在 src/config/api.config.ts 中使用，自动切换 API 地址。
Expo Go 是最简单的真机调试方式，无需构建，直接扫码运行。
安装 Expo Go
启动开发服务器
cd apps/app-rn-ts
pnpm start连接设备
exp://192.168.x.x:8081 的地址开始调试
安装 Expo Go
启动开发服务器
cd apps/app-rn-ts
pnpm start连接设备
exp://192.168.x.x:8081 的地址开始调试
注意： Expo Go 不支持某些原生模块（如 expo-camera），如果需要使用这些模块，请使用开发构建。
开发构建允许你使用自定义原生模块（如 expo-camera），并提供更接近生产环境的体验。
Android:
cd apps/app-rn-ts
# 使用 EAS Build（云端构建）
pnpm run build:android:dev
# 或使用本地构建（需要 Docker）
pnpm run build:android:dev:localiOS:
cd apps/app-rn-ts
# 使用 EAS Build（云端构建）
pnpm run build:ios:dev
# 或使用本地构建（需要 macOS 和 Docker）
pnpm run build:ios:dev:localAndroid:
iOS:
.ipa 文件启动开发服务器
cd apps/app-rn-ts
pnpm start打开开发构建应用
exp://192.168.x.x:8081）验证连接
开发构建 vs Expo Go：
| 特性 | Expo Go | 开发构建 |
|---|---|---|
| 安装方式 | App Store/Play Store | 手动安装 |
| 原生模块支持 | 有限（仅 Expo SDK 模块） | 完整支持（包括自定义原生模块） |
| 自定义配置 | 不支持 | 支持 |
| 调试功能 | 基础 | 完整 |
| 适用场景 | 快速开发、学习 | 测试原生功能、接近生产环境 |
| 构建时间 | 无需构建 | 需要构建（10-30 分钟） |
| 更新方式 | 自动更新 | 需要重新构建 |
真机上无法访问 localhost，因为 localhost 指向设备本身，而不是开发电脑。
macOS/Linux:
ifconfig | grep "inet " | grep -v 127.0.0.1
# 或
ipconfig getifaddr en0 # macOSWindows:
ipconfig
# 查找 IPv4 地址，通常是 192.168.x.x编辑 apps/app-rn-ts/src/config/api.config.ts：
const API_CONFIGS = {
development: {
// 将 localhost 改为你的电脑 IP
baseURL: "http://192.168.1.100:8888", // 替换为你的实际 IP
timeout: 10000,
},
production: {
baseURL: "https://admin.liyq666.top", // 生产环境
timeout: 10000,
},
};当前项目配置：
项目已配置开发环境 API 地址为 http://192.168.10.2:8888，你需要根据实际情况修改：
baseURL 为你的实际 IP注意：
EXPO_PUBLIC_ENV 环境变量自动切换 API 地址确保后端服务监听 0.0.0.0 而不是 127.0.0.1：
Node.js Express 示例：
app.listen(8888, "0.0.0.0", () => {
console.log("Server running on http://0.0.0.0:8888");
});确保防火墙允许端口 8888 的入站连接：
macOS:
# 检查防火墙状态
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
# 如果需要，允许 Node.js 通过防火墙
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/node
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /usr/local/bin/nodeWindows:
在终端查看：
pnpm start
# 日志会直接显示在终端在设备上查看：
安装 React Native Debugger：
# macOS
brew install --cask react-native-debugger
# 或下载
# https://github.com/jhen0409/react-native-debugger/releases使用：
http://localhost:8081/debugger-uiF12 打开开发者工具启动开发服务器：
cd apps/app-rn-ts
# 标准模式
pnpm start
# 清除缓存启动（解决缓存问题）
pnpm start --clear
# Tunnel 模式（适用于不同网络，如手机和电脑不在同一 Wi-Fi）
pnpm start --tunnel
# LAN 模式（仅局域网，更快）
pnpm start --lan
# 指定端口
pnpm start --port 8081设备操作快捷键（在终端中按）：
r - 重新加载应用（Reload）m - 切换开发者菜单（Menu）j - 打开调试器（Debugger）i - 在 iOS 模拟器中打开a - 在 Android 模拟器中打开w - 在 Web 浏览器中打开c - 清除缓存并重新加载d - 显示开发者菜单查看构建历史：
# 查看所有构建
eas build:list
# 查看特定平台的构建
eas build:list --platform ios
eas build:list --platform android
# 查看构建详情
eas build:view [build-id]查看构建日志：
# 查看构建日志（JSON 格式）
eas build:view [build-id] --json
# 查看构建状态
eas build:view [build-id] --status症状： 应用显示 "Unable to connect to Metro"
解决方案：
--tunnel 模式：
pnpm start --tunnel症状： 网络请求返回错误或超时
解决方案：
0.0.0.0 而不是 127.0.0.1http://192.168.x.x:8888/api/xxx症状： 修改代码后应用不更新
解决方案：
r 重新加载# 停止当前服务器 (Ctrl+C)
pnpm start --clear症状： 运行 pnpm run build:android:apk:local 时出现错误：
Error resolving plugin [id: 'com.facebook.react.settings']
> No Java compiler found, please ensure you are running Gradle with a JDK原因：
JAVA_HOME 环境变量未设置或指向错误解决方案：
步骤 1：安装 Java 17 或更高版本
macOS（使用 Homebrew）：
# 安装 Java 17（LTS 版本）
brew install openjdk@17
# 或者安装 Java 21（最新 LTS）
brew install openjdk@21macOS（手动安装）：
步骤 2：设置 JAVA_HOME 环境变量
临时设置（当前终端会话）：
# 查找 Java 17 安装路径
/usr/libexec/java_home -V
# 设置 JAVA_HOME（替换为实际路径）
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
# 或
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
# 验证设置
echo $JAVA_HOME
java -version永久设置（推荐）：
在 ~/.zshrc（如果使用 zsh）或 ~/.bash_profile（如果使用 bash）中添加：
# 设置 Java 17
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
# 或设置 Java 21
# export JAVA_HOME=$(/usr/libexec/java_home -v 21)
# 添加到 PATH
export PATH=$JAVA_HOME/bin:$PATH然后重新加载配置：
source ~/.zshrc
# 或
source ~/.bash_profile步骤 3：验证 Java 环境
# 检查 Java 版本（应该是 17 或更高）
java -version
# 检查 JAVA_HOME
echo $JAVA_HOME
# 检查 javac（Java 编译器）
javac -version步骤 4：重新运行构建
cd /Volumes/Work/Template/project_root/apps/app-rn-ts
pnpm run build:android:apk:local注意事项：
JAVA_HOME 指向 JDK（不是 JRE）症状： iOS 构建时出现证书或配置文件错误
解决方案：
检查 Apple Developer 账号
重新配置证书
手动管理证书（高级）
查看构建日志
# 查看构建列表
eas build:list
# 查看特定构建的详细信息
eas build:view [build-id]
# 查看构建日志
eas build:view [build-id] --json | jq '.logs'常见证书错误
app.json 中的 bundleIdentifier症状： iOS 本地构建时出现 Xcode 版本错误
解决方案：
检查 Xcode 版本
xcodebuild -version更新 Xcode
检查命令行工具
xcode-select --print-path
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer症状： EAS Build 失败
解决方案：
检查网络连接（如果是云端构建）
检查配置文件
eas.json 配置是否正确app.json 配置是否正确package.json 中的脚本命令查看构建日志
# 查看所有构建
eas build:list
# 查看特定构建的详细信息
eas build:view [build-id]
# 查看构建日志（JSON 格式）
eas build:view [build-id] --json检查依赖问题
node_modules 已正确安装cd apps/app-rn-ts
rm -rf node_modules
pnpm install检查环境问题
重新构建
--clear-cache 标志重新构建eas build --platform ios --profile development --clear-cache症状： 扫码功能无法使用
解决方案：
app.json 中是否配置了相机权限：
{
"expo": {
"android": {
"permissions": ["CAMERA"]
},
"ios": {
"infoPlist": {
"NSCameraUsageDescription": "需要访问相机来拍摄头像"
}
}
}
}src/config/api.config.ts）0.0.0.0eas.json 配置正确app.json 中的包名和版本号正确eas.json 配置正确app.json 中的 Bundle Identifier 和版本号正确| 场景 | Android | iOS |
|---|---|---|
| 快速开发测试 | Expo Go | Expo Go |
| 测试原生功能 | 开发构建 APK | 开发构建 IPA |
| 预览测试 | 预览版 APK | 预览版 IPA |
| 生产构建 | 生产版 AAB | 生产版 IPA |
推荐顺序：
云端构建（EAS Build）：最简单，无需本地环境
本地构建（EAS Local Build）：更快，需要 Docker
完全本地构建：最灵活，需要完整开发环境