【AI实战】React‑Native + AI 移动端 APP 完整实战全流程｜云端 / 本地大模型、Agent 集成、安装配置、避坑指南

梦想的颜色2026-09-02 10:30

2026 移动端 AI 开发分为两条路线：云端 API 调用 、设备端本地离线推理。

React‑Native（Expo）是跨平台移动端首选，一套代码同时输出 Android、iOS。很多同学踩坑：把 web 端 AI 逻辑直接搬到 RN，出现流式乱码、原生模块兼容、内存爆炸、模型体积过大等一系列问题。
本文完整记录从环境安装→项目初始化→AI 接入（云端大模型 / 本地端侧 LLM）→简单 Agent 工具调用→真机调试→打包发布全链路，同时对比两种架构优劣，给出工程化建议与高频踩坑清单，可直接作为简历项目。
重要区分：

  1. Expo Go：快速预览，但不支持带原生 C++ 推理库 ；本地大模型必须使用npx expo run:android / run:ios开发构建。
  2. 普通 React‑Native CLI：完全裸工程，自由度最高，配置成本更高。 本文优先使用 Expo 工作流，上手快，适合绝大多数 AI 移动端项目。

一、完整环境安装（Windows/macOS）

1. 基础依赖清单

依赖 版本要求 作用
Node.js 20 LTS ~ 22 LTS JS 运行时，不要使用 Node23+
JDK 17（强制） Android 编译，版本错直接构建失败
Android Studio 最新稳定版 Android SDK、模拟器、NDK
Xcode macOS，16+ 仅 macOS 可用，iOS 编译与模拟器
Watchman 最新 文件监听，macOS 推荐 brew 安装

Windows 用户：只能编译 Android；要做 iOS 必须 macOS。

2. macOS 安装命令

复制代码 
# Homebrew安装
brew install node watchman
# 确认node版本
node -v
# 全局安装expo cli
npm install -g expo

安装 Android Studio，在 SDK Manager 安装：

  • Android SDK Platform‑Tools
  • Android NDK（用于本地 AI 推理原生库编译）

3. Windows 安装要点

  1. 安装 Node20LTS
  2. 安装 JDK17，配置JAVA_HOME环境变量
  3. 安装 Android Studio，配置ANDROID_HOME
  4. Windows 不要用 WSL2 做 Expo 开发，会出现 adb 设备识别异常。

4. 校验环境

复制代码 
node -v
expo --version
adb devices

adb devices 能识别模拟器 / 真机，代表 Android 环境正常。

二、创建 Expo+Typescript AI 项目

复制代码 
# 创建TS模板项目
npx create‑expo‑app rn‑ai‑demo --template expo‑template‑typescript
cd rn‑ai‑demo

两种开发模式选择

方案 A：纯云端 AI（推荐新手，做聊天、移动端 Agent）

只调用远程大模型 API，无本地模型，Expo Go 可以直接运行，开发效率最高。 适用：移动端 AI 聊天 APP、AI 助手、移动端 Agent，对接 DeepSeek、GLM、OpenAI 兼容接口。

方案 B：端侧本地大模型（离线 AI，硬件要求高）

设备本地跑 LLM，隐私优先，不需要网络；不能用 Expo Go，必须执行原生构建。

硬件门槛：Android 至少 8G 内存；iOS A17 及以上芯片体验流畅；只能跑 7B 及以下量化模型 (GGUF/LiteRT)GitHub。

三、方案 A：云端大模型接入实战（最常用）

1. 安装依赖

复制代码 
# AI SDK，兼容OpenAI协议，支持流式输出
npm install openai
# 本地存储对话历史
npx expo install @react‑async‑storage/async‑storage
# 语音输入可选
npx expo install expo‑audio expo‑speech‑recognition

2. .env 环境变量配置

新建.env文件，不要硬编码 API Key 到前端代码！生产环境必须中转后端代理。

复制代码 
EXPO_PUBLIC_AI_BASE_URL=https://api.deepseek.com/v1
# 开发调试临时用；正式打包前端严禁直接存放key
EXPO_PUBLIC_AI_API_KEY=sk‑xxx

⚠️ 安全红线： RN 前端打包后代码完全可被逆向，直接把 API Key 写前端，会被窃取盗刷。生产必须自建后端做 API 中转，移动端只请求自己后端服务。

3. 核心流式聊天极简示例代码

app/(tabs)/chat.tsx

bash 复制代码 
import { View, Text, TextInput, Button, ScrollView } from 'react‑native';
import AsyncStorage from '@react‑async‑storage/async‑storage';
import OpenAI from 'openai';
import { useState, useEffect } from 'react';

const openai = new OpenAI({
  baseURL: process.env.EXPO_PUBLIC_AI_BASE_URL,
  apiKey: process.env.EXPO_PUBLIC_AI_API_KEY,
  dangerouslyAllowBrowser: true
});

type MsgItem = {role:"user"|"assistant",content:string}

export default function ChatPage(){
  const [msgList,setMsgList] = useState<MsgItem[]>([]);
  const [inputText,setInputText] = useState("");

  // 读取本地历史对话
  useEffect(()=>{
    (async ()=>{
      const raw = await AsyncStorage.getItem("chat_history");
      if(raw) setMsgList(JSON.parse(raw));
    })()
  },[])

  const sendMessage = async ()=>{
    if(!inputText.trim()) return;
    const newMsgs:MsgItem = {role:"user",content:inputText.trim()};
    const all = [...msgList,newMsgs];
    setMsgList(all);
    setInputText("");

    const stream = await openai.chat.completions.create({
      model:"deepseek‑chat",
      messages:all,
      stream:true
    });

    let fullResp = "";
    for await(const chunk of stream){
      const delta = chunk.choices[0]?.delta?.content || "";
      fullResp += delta;
      setMsgList([...all,{role:"assistant",content:fullResp}])
    }
    //持久化存储对话
    await AsyncStorage.setItem("chat_history",JSON.stringify([...all,{role:"assistant",content:fullResp}]))
  }

  return (
    <View style={{flex:1,padding:16}}>
      <ScrollView style={{flex:1}}>
        {msgList.map((m,i)=>(
          <Text key={i} style={{marginVertical:4}}>
            {m.role==="user"?"用户：":"AI："}{m.content}
          </Text>
        ))}
      </ScrollView>
      <TextInput value={inputText} onChangeText={setInputText} style={{borderWidth:1,padding:8}}/>
      <Button title="发送" onPress={sendMessage}/>
    </View>
  )
}

4. 移动端 Agent 扩展：MCP 工具调用

移动端原生不支持 STDIO 传输的 MCP Server，必须走HTTP/SSE/WebSocket 桥接模式：

  1. 后端部署 MCP‑Bridge 服务；
  2. RN 前端通过 WebSocket 连接桥接服务，发现工具列表；
  3. 大模型输出工具调用，经由后端桥接执行 MCP 工具，结果回传给移动端 APP。

移动端 Agent 架构要点： 移动端只做 UI 与会话管理；Agent Loop 循环、MCP 执行全部放在后端，移动端不要在前端实现复杂 Agent 循环。前端做 Agent 会出现上下文溢出、内存爆炸、工具执行权限不可控。

四、方案 B：React‑Native 本地端侧大模型（离线推理）

适合隐私需求、无网络场景；硬件门槛高，只适合 7B 以内量化模型。

主流库选型

  1. react‑native‑executorch：Meta ExecuTorch，支持 LLaMA 系列，Expo 兼容
  2. local‑llm‑rn：跨平台 GPU 加速，GGUF 模型，iOS Metal / Android VulkanGitHub
  3. @dr33m/react‑native‑litert‑lm：Android LiteRT，适合 Gemma 系列端侧模型

安装示例（executorch）

复制代码 
npx expo install react‑native‑executorch @react‑native‑executorch/expo‑resource‑fetcher expo‑file‑system expo‑asset

注意：不能使用 Expo Go 预览，必须原生构建

复制代码 
# Android
npx expo run:android
# iOS(macOS)
npx expo run:ios

核心问题：模型文件体积巨大，7B 量化模型 4‑6GB，不建议打包进 APK/IPA，APP 运行后在线下载模型文件存储本地。

端侧 AI 工程痛点

  1. 内存占用高，手机后台容易被系统杀进程；
  2. token 生成速度受手机芯片差异巨大，中低端手机速度极慢；
  3. 模型版本更新困难，无法简单热更新，需要整包更新 APP。

实战建议：绝大多数商业 APP 采用混合架构：有网络走云端大模型；无网络降级使用设备端小模型。

五、项目完整工程架构（AI 移动端 APP 标准分层）

复制代码 
rn‑ai‑demo
├── app                   # Expo Router页面
│   ├── chat.tsx          # AI聊天界面
│   └── agent‑page.tsx    # Agent功能页面
├── lib
│   ├── ai‑client.ts      # 云端大模型请求封装
│   ├── local‑llm.ts      # 本地端侧推理封装
│   └── mcp‑client.ts     # MCP桥接客户端（WebSocket）
├── store
│   └── chat‑store.ts    # 对话状态管理
├── hooks
│   ├── use‑stream‑chat.ts # 流式输出自定义Hook
│   └── use‑local‑model.ts #本地模型加载Hook
├── .env                  #环境变量
└── app.json

职责边界（非常重要，面试高频考点）

  1. 移动端前端：UI 渲染、对话展示、本地会话持久化、音频采集、图片采集
  2. 后端服务层：API Key 保管、Agent Loop 循环、MCP 工具调度、鉴权、限流、中转大模型请求
  3. 端侧推理模块：仅在离线模式启用，本地轻量模型推理

❌错误做法：在 RN 前端完整实现 Agent 的 Plan‑and‑Execute 循环，会造成内存失控、上下文无法管控。

六、真机调试与打包发布

1. 真机调试 Android

  1. 手机开启开发者选项，打开 USB 调试；USB 连接电脑

    adb devices
    npx expo run:android

2. iOS 真机（macOS）

Xcode 配置 Apple 开发者账号，连接手机执行：

复制代码 
npx expo run:ios --device

3. 打包 APK/AAB/ IPA

使用 EAS Build（Expo 官方云构建，不用本地搭完整编译环境）

复制代码 
npm install -g eas‑cli
eas build ‑p android ‑‑profile preview

本地打包 Android 需要完整 Android SDK、NDK；iOS 本地打包必须 macOS。

七、高频踩坑清单（实战避坑）

  1. API Key 前端泄露：逆向可拿到，生产环境必须后端中转。
  2. Expo Go 不能跑本地 AI 推理库：原生 C++ 模块需要 run:android/run:ios 构建，Expo Go 不支持第三方原生库。
  3. JDK 版本不对：Android 编译必须 JDK17，JDK11/21 直接报错。
  4. 流式输出乱码、丢 token ：openai sdk 开启dangerouslyAllowBrowser:true，RN Hermes 引擎版本尽量更新最新。
  5. 内存持续上涨：大模型流式会话，必须做上下文截断、滚动窗口，不要无限追加消息列表。
  6. pod install 超时 ：iOS，执行pod cache clean --all，更换国内 cocoa‑pod 源。
  7. 本地模型体积过大：不要内置模型包，APP 运行后下载量化 GGUF/LiteRT 模型文件。
  8. 移动端 MCP 不能直接调用 STDIO 服务：必须后端做桥接 WebSocket/SSE。

八、作为秋招简历项目，怎么写，面试会问什么

简历描述参考

基于 React‑Native (Expo+TS) 开发跨平台移动端 AI 助手 APP，Android/iOS 一套代码；采用云端 + 端侧混合 AI 架构；后端实现 Agent 循环与 MCP 桥接服务；移动端完成流式对话渲染、会话本地持久化、语音采集；针对移动端做上下文滚动窗口优化，解决内存溢出；实现离线降级能力。

面试官高频追问

  1. 为什么不在前端直接实现 Agent 循环？放在后端有什么好处？
  2. API Key 为什么不能直接写在 RN 前端，有什么风险，如何解决？
  3. 云端大模型与本地端侧模型分别适合什么场景，混合架构怎么设计？
  4. 移动端长对话上下文爆炸，你做了哪些优化手段？
  5. MCP 在移动端有什么限制？STDIO Transport 为什么不能直接在手机端使用？
  6. 本地端侧 LLM 遇到内存被系统杀死，你会怎么处理？

九、总结

  1. 普通 AI 聊天、移动端 Agent 项目优先选择 Expo + 云端 API 架构，开发速度最快，适合简历项目；
  2. 端侧本地大模型适合隐私离线场景，硬件门槛高，不要盲目优先选用；
  3. 移动端不适合完整跑 Agent Loop、STDIO 类型 MCP 服务，Agent 核心逻辑尽量下沉后端；
  4. 安全第一，前端严禁直接保存大模型密钥，必须后端中转；
  5. 移动端 AI 项目重点考察：内存治理、上下文策略、分层架构、云端‑端侧混合设计，而不是简单调用 API。
相关推荐
Csvn16 分钟前
第 13 章 反思 Reflection
人工智能·aigc·agent
烬羽38 分钟前
为 Agent 管好一张“上下文预算”：从数条数到数 token
架构·langchain·agent
烬羽43 分钟前
把 Agent 的记忆写进文件：内存 vs 文件，两把钥匙搞定多会话
架构·langchain·agent
武子康1 小时前
RoboLab 解读：机器人策略评测为什么不能只看二元成功率
人工智能·llm·agent
the局外人1 小时前
别让 Codex 一口气写完整个前端：5 组 Skills，把页面、逻辑、测试和构建拆清楚
前端·人工智能·agent
程序员于老七2 小时前
漫话大模型：先画轮廓再画细节——从 Flow Matching 看生成模型的“殊途同归“
深度学习·大模型·ai编程·diffusion·flowmatching
像风一样自由20202 小时前
17.Milvus如何完成一次向量相似度检索
人工智能·postgresql·大模型·milvus·rag·智能体
ZGG0033 小时前
真题拆解 05：ReAct 还是 Plan-and-Execute——规划范式怎么选
python·agent·react
苏灿烤鱼3 小时前
从“生成内容”到“生成可执行对象”：我把 OpenMAIC 源码翻了一遍，发现 AI Agent 正在变成应用操作系统
开源·agent·ai编程
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点03ZCode 周末送额度活动开启：3 亿 Token 免费领取04蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接052026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？06历年考研数学一、数学二、数学三真题试卷及答案PDF07微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路09Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费10VSCode+CodeX扩展，无法启动