跳到主要内容

在 React Native 中接入 CloudBase AI(DeepSeek / 混元)

一句话定义:RN 0.74+ 移动端走「前端 fetch + 后端代理」两段式:后端 Route Handler(Next.js / 云函数 / 云托管任选)用 @cloudbase/node-sdk 的 app.ai().createModel('cloudbase').streamText({model: 'deepseek-v4-flash'}) 返回 text/plain 流式 Response;RN 前端用 fetch + body.getReader()(或 react-native-fetch-api polyfill / XHR onprogress fallback)读流,FlatList 逐字渲染。SecretId / SecretKey 绝不能写进 JS bundle——RN 打包后 bundle 是明文,任意 App 反编译都能拿到密钥。

预计耗时:45 分钟 | 难度:进阶

适用场景​

  • 做 RN 跨平台 App(iOS + Android 一套代码),要接 AI 做对话 / 摘要 / 翻译 / 文案生成
  • 已有 iOS / Android 原生 App,想统一用 RN 重做 AI 层,共用 Web 端那套 CloudBase AI 后端代理
  • 已经用 add-ai-nextjs 跑通了 Web 端,现在要把同一套 Route Handler 给 RN App 复用——后端完全不动,只补 RN 前端流式读取

不适用:

  • Expo Go 环境(Expo 官方预编译的 Go App,锁了原生模块,无法安装 react-native-fetch-api 这类需要 link 的 polyfill)——必须改用 Expo dev build 或裸 RN 工程
  • 微信小程序场景——小程序自带 wx.cloud 身份,直接走 add-ai-wechat-miniprogram,不需要后端代理
  • 纯 Web / H5 场景——走 add-ai-nextjs,@cloudbase/js-sdk + signInAnonymously 那套只在浏览器 demo 里有意义,RN 也不能用
  • 想直接在 RN 里 import tcb from '@cloudbase/node-sdk'——Node SDK 依赖 fs / http / crypto 等 Node 内置模块,RN(Hermes / JSC)都跑不起来

为什么 RN 必须走后端代理​

跟 Web 一样,RN 客户端没有受信凭证持有方:

  • RN 打包出来的 JS bundle 是明文(release 模式 Hermes bytecode 也能 反编译回 JS),把 SecretId / SecretKey 写在代码里 = 直接公开发密钥
  • @cloudbase/js-sdk 的 signInAnonymously() 在 RN 里能跑,但它的匿名身份默认会被严格限频(详见 Web SDK 安全策略),只适合 demo,生产请求会被风控拦
  • 小程序之所以能直连 wx.cloud.extend.AI,是因为 wx.cloud 调用本身就带了用户的微信登录态——RN 没有这种平台身份注入机制

所以 RN 接 CloudBase AI 的标准姿势是:

RN App (fetch) ──HTTPS──▶ 后端 Route Handler (持 SecretKey) ──▶ CloudBase AI streamText ──▶ 流式响应回 RN

后端 Route Handler 跟 add-ai-nextjs 第三步一模一样,本篇不再重复造轮子,只补 RN 前端怎么读流。

环境要求​

依赖版本
React Native0.74+(New Architecture / Fabric 稳定,默认 Hermes,fetch 大部分场景已支持 body.getReader())
Node.js(开发机)≥ 20
Xcode(iOS)≥ 15.0,iOS 部署目标 ≥ 13.4
Android Studio≥ 2024.1,Android minSdkVersion ≥ 24
@cloudbase/node-sdk(后端用)≥ 3.16.0(AI 模块要求)
react-native-fetch-api(可选 polyfill)≥ 3.0.0(RN 老版本或 fetch 行为异常时装)
CloudBase 环境已开通,且控制台已开通「AI+」能力

工程模板推荐:

  • 新项目:npx @react-native-community/cli@latest init MyApp 走裸 RN 0.76+,默认就是 New Architecture
  • 跨平台 + 想用 EAS Build:走 Expo dev build(npx create-expo-app + npx expo run:ios),不要用 Expo Go

想偷懒在客户端直接 import tcb from '@cloudbase/node-sdk' 不行——Node SDK 依赖 fs / http / crypto,RN bundler(Metro)打不进去,即使打进去 Hermes 也跑不起来。服务端必须是真正的 Node 环境(Next.js Route Handler、云函数、云托管)。

第一步:控制台开通 AI 能力 + 选模型​

跟 add-ai-nextjs 第一步完全一样:

  1. 进 CloudBase 控制台 → 选你的环境 → AI+ → 快速接入
  2. 第一次进点「立即开通」,自动给环境注入 AI 调用权限。开通免费,调用按 token 计费
  3. 「模型管理」里能看到当前环境可用的模型列表。CloudBase 通过 Token 资源包统一接入 DeepSeek、MiniMax、混元、Kimi、GLM 等主流模型,官方主推 deepseek-v4-flash(性价比 + 通用对话默认),完整列表见 接入大模型

下文示例统一用 deepseek-v4-flash。

第二步:后端 Route Handler(跟 Next.js 那篇一样,直接复用)​

后端代理可以部署到三个地方,任选一个,接口形态完全一样:

部署形态入口凭证注入方式
Next.js 部署到 Vercel / 自建机器app/api/chat/route.ts(App Router).env 配 TENCENTCLOUD_SECRETID/KEY
部署到 CloudBase 云托管任意 Node Web 框架(Express / Hono / Next.js)/api/chat 路由容器自动注入,无需手填密钥
部署到 CloudBase 云函数HTTP 触发器,函数代码内 tcb.init()同上,自动注入

代码以 Next.js Route Handler 为例(app/api/chat/route.ts):

import tcb from '@cloudbase/node-sdk';

export const runtime = 'nodejs'; // 关键:不能用 edge,SDK 依赖 Node API

let app: ReturnType<typeof tcb.init> | null = null;

function getAi() {
  if (!app) {
    // node-sdk 自动从 TENCENTCLOUD_SECRETID/SECRETKEY 读凭证
    // timeout 60s:AI 长输出场景默认 15s 会被击穿
    app = tcb.init({ env: process.env.CLOUDBASE_ENV!, timeout: 60000 });
  }
  return app.ai();
}

export async function POST(req: Request) {
  const { messages } = await req.json();
  const ai = getAi();
  const model = ai.createModel('cloudbase');

  const result = await model.streamText({
    model: 'deepseek-v4-flash',
    messages,
  });

  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      try {
        for await (const chunk of result.textStream) {
          controller.enqueue(encoder.encode(chunk));
        }
        controller.close();
      } catch (err) {
        controller.error(err);
      }
    },
  });

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/plain; charset=utf-8',
      // RN fetch 在 Android 上偶尔会因为 keep-alive 复用连接读不到完整流,显式 close 一下
      'Connection': 'close',
    },
  });
}

要点:

  • 服务端必须用 @cloudbase/node-sdk,不要用 @cloudbase/js-sdk + signInAnonymously() 那套 Web 端写法(原因见前面「为什么 RN 必须走后端代理」)
  • runtime = 'nodejs',不能 edge
  • tcb.init({ timeout: 60000 }) 显式拉到 60s,默认 15s 会被流式长输出击穿
  • 返回 text/plain 流式 Response;不要返回 SSE text/event-stream,RN 端没有原生 EventSource,要么走本篇的 fetch + reader,要么装 react-native-sse 单独处理协议
  • 部署到 CloudBase 云托管 / 云函数时,密钥自动注入,不要在代码里硬编码

如果后端跑在 CloudBase 云托管,前端调用 URL 形如 https://<service>-<envId>.ap-shanghai.app.tcloudbase.com/api/chat;部署到 Vercel 就是 https://<your-app>.vercel.app/api/chat;部署在自建机器要自己解 HTTPS + 域名。

域名必须是 HTTPS。iOS 默认 ATS(App Transport Security)直接拒 HTTP;Android 9+(API 28+)默认 cleartext traffic 也禁。本地调试用 HTTP 见第四步配置例外。

第三步:RN 前端 — 装依赖​

进 RN 项目根目录:

# 0.74+ Hermes 默认 fetch 大部分场景能用 body.getReader(),保险起见仍装 polyfill
npm install react-native-fetch-api react-native-polyfill-globals
# iOS 链接原生依赖
cd ios && pod install && cd ..

react-native-fetch-api 给 RN 装了一份能正确 await body.getReader().read() 的 fetch 实现(老版本 RN 的 fetch 是 XHR 包出来的,根本拿不到 ReadableStream;0.74+ 大部分 Engine 已支持,装 polyfill 是双保险)。

在 App 入口最早的位置打开 polyfill(index.js 第一行):

// index.js
import { polyfillGlobal } from 'react-native/Libraries/Utilities/PolyfillFunctions';
import { fetch, Headers, Request, Response } from 'react-native-fetch-api';

polyfillGlobal('fetch', () =>
  (...args) => fetch(args[0], { ...args[1], reactNative: { textStreaming: true } })
);
polyfillGlobal('Headers', () => Headers);
polyfillGlobal('Request', () => Request);
polyfillGlobal('Response', () => Response);

// 你原本的 RN 入口逻辑
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';

AppRegistry.registerComponent(appName, () => App);

reactNative: { textStreaming: true } 这个非标准选项是 react-native-fetch-api 用来打开「真流式」模式的开关,不加它,fetch 行为退化成「等响应体完整收完再 resolve」,UI 上看就是「憋一阵后整段冒出来」。

第四步:RN 前端 — iOS / Android 网络配置​

iOS(ios/MyApp/Info.plist)​

生产环境用 HTTPS 不需要改任何 ATS 配置。本地调试如果非要用 HTTP(例如连内网 http://192.168.x.x:3000),临时打个例外:

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSExceptionDomains</key>
  <dict>
    <key>192.168.1.100</key>
    <dict>
      <key>NSExceptionAllowsInsecureHTTPLoads</key>
      <true/>
    </dict>
  </dict>
</dict>

不要在生产开 NSAllowsArbitraryLoads,App Store 审核会卡。

Android​

android/app/src/main/AndroidManifest.xml 在 <application> 之外加权限,在 <application> 之内加 networkSecurityConfig 引用:

<uses-permission android:name="android.permission.INTERNET" />

<application
  android:networkSecurityConfig="@xml/network_security_config"
  ...>

Android 9+(API 28+)默认禁明文 HTTP。生产 HTTPS 不需要这个文件;本地调试 HTTP 时新建 android/app/src/main/res/xml/network_security_config.xml:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
  <domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="true">192.168.1.100</domain>
    <domain includeSubdomains="true">10.0.2.2</domain>
  </domain-config>
</network-security-config>

10.0.2.2 是 Android 模拟器访问宿主机的特殊地址。生产不要全局开 cleartextTrafficPermitted="true"。

第五步:RN 前端 — fetch + ReadableStream 消费流​

App.tsx:

import React, { useRef, useState } from 'react';
import {
  FlatList,
  KeyboardAvoidingView,
  Platform,
  SafeAreaView,
  StyleSheet,
  Text,
  TextInput,
  TouchableOpacity,
  View,
} from 'react-native';

// 后端 Route Handler 的 URL(部署到 CloudBase 云托管 / Vercel / 自建机器都行)
const API_URL = 'https://your-backend.example.com/api/chat';

type Message = { role: 'user' | 'assistant'; content: string };

export default function App() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [input, setInput] = useState('');
  const [loading, setLoading] = useState(false);
  const listRef = useRef<FlatList<Message>>(null);

  async function send() {
    const text = input.trim();
    if (!text || loading) return;

    const userMsg: Message = { role: 'user', content: text };
    const aiMsg: Message = { role: 'assistant', content: '' };
    const next = [...messages, userMsg, aiMsg];
    setMessages(next);
    setInput('');
    setLoading(true);

    try {
      const res = await fetch(API_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ messages: [...messages, userMsg] }),
        // @ts-ignore react-native-fetch-api 的扩展选项
        reactNative: { textStreaming: true },
      });

      if (!res.ok || !res.body) {
        throw new Error(`HTTP ${res.status}`);
      }

      const reader = res.body.getReader();
      const decoder = new TextDecoder();
      let acc = '';

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        // stream:true 必须加,否则跨 chunk 边界的中文会被劈成乱码 \uFFFD
        acc += decoder.decode(value, { stream: true });
        setMessages((prev) => {
          const copy = [...prev];
          copy[copy.length - 1] = { role: 'assistant', content: acc };
          return copy;
        });
        // FlatList 跟随滚动到底
        listRef.current?.scrollToEnd({ animated: false });
      }
    } catch (err) {
      console.error('[chat] fetch failed', err);
      setMessages((prev) => {
        const copy = [...prev];
        copy[copy.length - 1] = {
          role: 'assistant',
          content: `[出错] ${err instanceof Error ? err.message : String(err)}`,
        };
        return copy;
      });
    } finally {
      setLoading(false);
    }
  }

  return (
    <SafeAreaView style={styles.safe}>
      <KeyboardAvoidingView
        style={styles.container}
        behavior={Platform.OS === 'ios' ? 'padding' : undefined}
      >
        <FlatList
          ref={listRef}
          data={messages}
          keyExtractor={(_, i) => String(i)}
          contentContainerStyle={styles.list}
          renderItem={({ item }) => (
            <View
              style={[
                styles.bubble,
                item.role === 'user' ? styles.userBubble : styles.aiBubble,
              ]}
            >
              <Text style={styles.role}>{item.role}</Text>
              <Text style={styles.content}>{item.content}</Text>
            </View>
          )}
        />
        <View style={styles.inputBar}>
          <TextInput
            style={styles.input}
            value={input}
            onChangeText={setInput}
            placeholder="问点什么"
            editable={!loading}
            onSubmitEditing={send}
            returnKeyType="send"
          />
          <TouchableOpacity
            style={[styles.button, (loading || !input.trim()) && styles.buttonDisabled]}
            disabled={loading || !input.trim()}
            onPress={send}
          >
            <Text style={styles.buttonText}>{loading ? '生成中' : '发送'}</Text>
          </TouchableOpacity>
        </View>
      </KeyboardAvoidingView>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  safe: { flex: 1, backgroundColor: '#fff' },
  container: { flex: 1 },
  list: { padding: 12, gap: 8 },
  bubble: { padding: 10, borderRadius: 8 },
  userBubble: { backgroundColor: '#e6f0ff', alignSelf: 'flex-end', maxWidth: '80%' },
  aiBubble: { backgroundColor: '#f5f5f5', alignSelf: 'flex-start', maxWidth: '80%' },
  role: { fontSize: 11, color: '#888', marginBottom: 4 },
  content: { fontSize: 15, color: '#111', lineHeight: 22 },
  inputBar: {
    flexDirection: 'row',
    padding: 8,
    borderTopWidth: 1,
    borderTopColor: '#eee',
    gap: 8,
  },
  input: {
    flex: 1,
    paddingHorizontal: 12,
    paddingVertical: 8,
    borderRadius: 6,
    backgroundColor: '#f5f5f5',
    fontSize: 15,
  },
  button: {
    paddingHorizontal: 16,
    justifyContent: 'center',
    backgroundColor: '#1677ff',
    borderRadius: 6,
  },
  buttonDisabled: { backgroundColor: '#aaa' },
  buttonText: { color: '#fff', fontSize: 15 },
});

要点:

  • decoder.decode(value, { stream: true }) 的 stream: true 不能漏——中文一个字符 UTF-8 通常占 3 字节,流式 chunk 边界可能恰好把一个汉字劈成两半,不带 stream: true 那半个汉字会被解成 \uFFFD 替换字符
  • 给 assistant 消息预先 push 一条空 content,后续每次 setState 替换最后一条,UI 是「在原位增长」而不是「先空一会再整段冒出来」
  • FlatList 的 scrollToEnd({ animated: false }) 每 chunk 都调一次没事——FlatList 是虚拟化列表,只有可见区域 cell 重排,没有性能问题。真正要节流的不是 scroll 而是 setState:如果模型吐字超快(deepseek-v4-flash 这种 flash 系列一次几百字),可以加 80ms 节流(参考 add-ai-wechat-miniprogram 第三步的 lastFlushAt)

第六步:如果 fetch + ReadableStream 失败 — XHR onprogress fallback​

部分 RN 版本(尤其是 < 0.74)或某些设备上,即使装了 polyfill,body.getReader() 仍然拿不到流式数据。这时候用 XMLHttpRequest 的 onprogress 兜底——XHR 是 RN 一直稳定支持的网络底层:

function streamChatViaXHR(
  messages: Message[],
  onChunk: (acc: string) => void,
  onDone: () => void,
  onError: (err: Error) => void,
) {
  const xhr = new XMLHttpRequest();
  xhr.open('POST', API_URL, true);
  xhr.setRequestHeader('Content-Type', 'application/json');

  let lastIndex = 0;

  xhr.onprogress = () => {
    // xhr.responseText 是「到目前为止累积的所有响应文本」,每次切片新增部分
    const newChunk = xhr.responseText.substring(lastIndex);
    lastIndex = xhr.responseText.length;
    onChunk(xhr.responseText); // 把完整累积文本传给 UI(简单做法)
    // 想拿增量就传 newChunk
    void newChunk;
  };
  xhr.onerror = () => onError(new Error(`XHR error: ${xhr.statusText}`));
  xhr.onload = () => {
    if (xhr.status >= 200 && xhr.status < 300) onDone();
    else onError(new Error(`HTTP ${xhr.status}`));
  };

  xhr.send(JSON.stringify({ messages }));
}

XHR fallback 的限制:

  • 没有真正的「字节级流」,只有「文本累积视图」(xhr.responseText),所以 Content-Type 必须是文本类(text/plain),返回二进制会乱码
  • onprogress 触发频率取决于设备和网络栈,弱网下可能几秒才触发一次——不像 fetch reader 那样紧凑
  • 跨 chunk 中文乱码风险更高(XHR 内部按 UTF-8 buffer 解码,在切片边界仍可能产生 \uFFFD);可以在后端 streamText 那一层强制按 token 边界 flush(进阶,不展开)

建议生产路径:优先 fetch + getReader,失败再降级 XHR,代码里 try/catch 嵌套即可。

运行验证​

跑后端​

  • 部署到 CloudBase 云托管:tcb framework deploy 或控制台上传(参考 服务部署)
  • 部署到 Vercel:vercel --prod,记得在 Vercel 环境变量里配 TENCENTCLOUD_SECRETID/KEY/CLOUDBASE_ENV
  • 自建机器:npm run build && npm run start,反代加 HTTPS

curl 测一下后端确实在流式返回:

curl -N -X POST https://your-backend.example.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"用一句话介绍 CloudBase"}]}'

-N 是 --no-buffer,文字会一段段冒出来。如果是憋一段时间后一次性吐完,说明后端没真正流式(检查 Route Handler 那段 ReadableStream 是不是写对)。

跑 RN​

  1. iOS:npx react-native run-ios 或 Xcode 启动
  2. Android:npx react-native run-android 或 npx expo run:android
  3. App 起来后输入「用一句话介绍 CloudBase」,点发送
  4. 应该看到回复一段段冒出来,而不是憋几秒后整段出现
  5. 控制台 → AI+ → 调用记录,能看到刚才那次调用的 token 计数

iOS Console / Android logcat 不应该报 Network request failed / cleartext HTTP traffic not permitted / ATS blocked 类报错。

常见错误​

错误信息 / 现象原因修复
body.getReader is not a functionRN 默认 fetch 实现不支持 ReadableStream(0.74 之前的版本,或某些 Engine 不全)装 react-native-fetch-api 并在入口 polyfillGlobal('fetch', ...),见第三步
Network request failed 直接报错,没有详细原因iOS ATS 拒绝了 HTTP(本地调试 http://192.168.x.x)或 Android cleartext 被拒iOS 改 Info.plist 的 NSAppTransportSecurity 例外;Android 配 network_security_config.xml,见第四步。生产用 HTTPS
cleartext HTTP traffic to ... not permitted(Android 9+)Android 默认禁明文 HTTP同上,加 network_security_config.xml 白名单
fetch 不报错但前端「憋一阵后整段出现」没开 reactNative: { textStreaming: true },fetch 退化成等完整响应polyfill 入口 + fetch 调用处都加上 reactNative: { textStreaming: true }
流式中文显示 ��� 乱码TextDecoder.decode(value) 没加 { stream: true },跨 chunk 边界的多字节字符被劈成两半改成 decoder.decode(value, { stream: true }),见第五步
后端报 XMLHttpRequest is not defined 或 secretId or secretKey not found后端 Route Handler 用了 Edge Runtime,或者部署平台没配凭证后端必须 export const runtime = 'nodejs';部署到非 CloudBase 平台时显式配 TENCENTCLOUD_SECRETID/KEY,详见 add-ai-nextjs
后端报 timeout / 60s 左右挂死Node SDK 默认 timeout: 15000 太短tcb.init({ env, timeout: 60000 }) 拉到 60s 以上,见第二步代码
model not found / model xxx is not supported模型 ID 拼错,或环境里没上架控制台「模型管理」对照名字,不要照搬 OpenAI / Anthropic 命名,主推 deepseek-v4-flash,完整列表见 接入大模型
Expo Go 里直接报 polyfill 装不上 / pod install 报错Expo Go 锁了原生模块改用 Expo dev build 或裸 RN,Expo Go 不支持
release 包反编译能看到 SecretKey代码里把密钥写进了客户端客户端永远不能放密钥,只能放后端代理。Recipe 第一段强调过

错误码完整定义参考 https://docs.cloudbase.net/error-code/。

计费提示​

  • 新开通环境首月赠送 100 万 token 试用额度(具体以 控制台计费页面 当前披露为准)
  • 计费按「输入 token + 输出 token」分别计算,不同模型单价不同;流式调用跟非流式 token 计费一致
  • 后端 Route Handler 是公网端口,移动端 App 流量天然更难限制(不像浏览器有 same-origin),一定要做请求方鉴权:
    • 让 RN App 启动时拿一个用户身份 token(参考 add-auth-web-with-cloudbase-sdk 的服务端校验思路,RN 可用 @cloudbase/js-sdk 拿 JWT)
    • Route Handler 入口先 verify JWT,失败直接 401,再按 UID 限频
    • 也可以结合 CloudBase 安全管控 配域名 / Referer 白名单——但 RN 没有 Referer,这个对 Web 端管用,移动端必须用 token 鉴权
  • iOS App Store 不允许 App 内嵌「能让用户跟 AI 自由对话的功能」而不做内容审核——上架前在 Route Handler 内嵌 文本内容安全 校验,或者用 Agent 模式让平台帮你做敏感词过滤

相关文档​