直到这周之前，我知道 我们的应用崩了的唯一途径，是有人来告诉我。大多数人不会说。他们重新打开应用，如果又崩了，就不再打开了。API 那边是有覆盖的（所有 ERROR 日志都会发到团队聊天的一个频道），但手机上的一次崩溃，在我能看到的地方不留任何痕迹。

其实应用里已经有一个上报机制。应用每次把错误信息展示给用户时，都会把这条信息 POST 到 API 上的一个小接口，服务端以 ERROR 级别记录，所以同样会进聊天频道。加这个是因为有一次删除操作其实 成功了 ，可那一行还留在列表里，再点一下就弹出 “No Item matches the given query”。服务端只记了两条普通的 404，什么也没说。它覆盖的是应用捕获并展示出来的错误。崩溃不一样：本该发送报告的那段 JavaScript，恰恰就是刚刚死掉的那个。

最直接的办法是用 Sentry。我很喜欢 Sentry 的 SDK，React Native 上的崩溃上报之所以算是已解决的问题，靠的就是它。我不想要的是：又多一家供应商持有用户数据，隐私政策里又多一行，又多一张账单，而以我们的规模，这东西一天顶多几条报告。所以我留下 SDK，换掉服务：应用的 DSN 指向我们自己的 API，由那边 Django 应用里的一小块代码负责接收、分组、报警和保存。

这篇文章讲它是怎么工作的，以及我怎么确认一次真实的原生崩溃确实能送到。

DSN 的小把戏

#

Sentry 的 DSN 长这样：https://<public-key>@<host>/<project-id>。SDK 会把它变成一个发往 https://<host>/api/<project-id>/envelope/ 的 POST 请求，key 放在 X-Sentry-Auth 头里。这里面没有任何东西是 sentry.io 专属的。所以打包进应用的 DSN 是：

https://<CRASH_REPORT_KEY>@api.example.com/1

Django 里加一条路由，正好匹配 SDK 会调用的地址：

path("api/<int:project_id>/envelope/", crash_envelope, name="crash_envelope"),

这个 key 存在于每一个安装包里，所以它不是秘密。它的作用是：万一这个接口开始招来垃圾请求，我可以换掉它；另外服务端没配置 key 时会拒绝一切请求，而不是来者不拒：

def crash_envelope(request, project_id):
    expected = settings.CRASH_REPORT_KEY
    if not expected:
        return Response({"detail": "Crash reporting is not configured"}, status=503)
    if not hmac.compare_digest(_key(request).encode(), expected.encode()):
        return Response({"detail": "Unknown key"}, status=401)
    ...

_key 从 X-Sentry-Auth 头里读出 sentry_key=，读不到就退回到查询字符串，有些 SDK 是放在那里的。

SDK 发的是什么：envelope

#

Sentry 的传输格式叫 envelope：先是一行 JSON 头，后面跟任意多个 item，每个 item 是一行 JSON 头加一段 payload。如果 item 头里有 length，payload 就恰好是这么多字节；否则一直读到下一个换行符。

{"event_id":"9ec79c33...","dsn":"https://...@api.example.com/1"}
{"type":"event","length":4123}
{ ...the event JSON, 4123 bytes... }
{"type":"client_report"}
{"timestamp":1791400000.5,"discarded_events":[]}

有两个细节让我栽了跟头：

• 原生 SDK 会 gzip 请求体，JavaScript 的不会。 @sentry/react-native 捕获的 JS 错误是明文发来的，而 sentry-cocoa 或 sentry-android 发来的原生崩溃带着 Content-Encoding: gzip。解码器能处理 gzip、zlib 包装的 deflate 和裸 deflate，解压到 1MB 就停，因为一个崩溃事件只有几 KB，再大就不是崩溃事件了。
• 带长度前缀的 payload 里可以有换行符。 如果按 \n 切分，原生 SDK 发来的每个事件都会被切坏。有 length 的时候必须按它来读。

解析器很短。它只保留 event 类型的 item；session、transaction、附件和 client report 照单全收，然后丢弃。

用 SDK 听得懂的方式回应

#

这一点比我预想的重要。SDK 在磁盘上维护一个队列，凡是不确定送达的都会重试，所以服务端怎么回应，决定了它会不会一直重试下去：

• 存好了，或者是故意丢弃的，都回 200。如果我对 session item 回一个 4xx，SDK 就会留着它，永远重试。
• 被限流时回 429 加 Retry-After。这个接口按 IP 限流（每小时 120 次），因为陷入崩溃循环的手机每次启动都会发一条报告，而 SDK 收到 429 会像你期望的那样退避。
• envelope 格式不对回 400，记成 warning 而不是 error：一份坏掉的报告只说明某个客户端坏了，下一份正常的报告会告诉我崩在哪。

SDK 如果不确定第一次是否送达，还会重发同一个事件，所以 event_id 上有唯一约束，重复的就悄悄跳过。

没有 source map 时怎么分组

#

自己写接收端，就得做一个 Sentry 替你做了的选择。Sentry 按堆栈给崩溃分组。但 release 版的 Hermes bundle 是压缩过的，函数名都是单个字母，行列号每次构建都会变。按堆栈帧分组，同一个 bug 每次发版都会开一个新 issue。

没有 source map（文末再说），JavaScript 错误里最稳定的就是它的类型和信息。所以指纹由异常类型加信息组成，并把每次出现都不一样的部分遮掉：

_MASKS = [
    (re.compile(r"0x[0-9a-fA-F]+"), "<addr>"),
    (re.compile(r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b"), "<uuid>"),
    (re.compile(r"\b[0-9a-fA-F]{16,}\b"), "<hex>"),
    (re.compile(r"\d+"), "<n>"),
]

Cannot read property 'title' of undefined (reading index 3) 和 (reading index 17) 会归为同一个 issue。如果 SDK 自己带了 fingerprint 且其中没有 {{ default }}，就以它为准，这样默认分组不对时我可以从客户端强制指定。没有异常的事件退而使用遮罩后的日志信息，两者都没有就用最上面的应用内堆栈帧。原生信号崩溃的信息大概是 Signal 6, Code 0，所以这类崩溃按信号分组，粒度很粗，但在有符号化之前，这样是诚实的。

报警，但不刷屏

#

每个指纹对应一个 issue，每份报告作为一个事件存在它下面。issue 只在以下几种情况下以 ERROR 级别记录（聊天报警监听的就是这个级别）：

• 新出现的 issue
• 已解决的 issue 又出现，此时会重新打开它
• 第 10、100、1,000、10,000 次出现

普通的重复只会让计数器加一。标记为 忽略 的 issue 照样计数，但从不报警。再加上聊天 handler 自己的限流，坏版本上的崩溃循环在频道里只是几条消息，而不是一面墙。

存储也一样有上限：每个 issue 保留 最近 50 条 事件，新的进来就删掉旧的。这让第一版图表出了问题，因为 50 条事件说不出上周某件事发生了多少次。所以每个 issue 还另外记着 90 天的每日计数，和计数器加一放在同一个事务里更新。图表从这些计数取数；事件只用来阅读。

如果你也自己做一个，有两个小的竞态值得处理。一个全新的崩溃同时打到几台手机上时，两份报告可能都想创建这个 issue，所以给指纹加唯一约束，让输的那个重新读取已有的那一行。另外，90 天的窗口要从服务器的"今天"算起，而不是从最新一份报告算起，因为时钟设错的手机可能把报告的日期标成任何一天，包括明年。

payload 上限是 128KB。超出的事件先丢 breadcrumbs 和调试元数据；还超，就只保留异常、信息、版本和平台，并做个标记，让我知道它被截过。

脱敏

#

SDK 开着 sendDefaultPii: false，所以理论上不会发送 IP 地址、cookie 或请求体。服务端并不依赖这一点：存储之前，user 里只留 id 和 username，request 整个删掉，以防以后某个 SDK 版本或设置开始发送这些东西。

用真机测试又发现了两样需要去掉的东西：

• breadcrumbs 记录的是完整 URL，包括查询字符串。 应用的搜索请求会把搜索词放在查询字符串里，所以搜索之后紧跟着的一次崩溃，会把用户搜了什么存下来。现在服务端会把每个 breadcrumb 的 URL 在 ? 处截断。
• console 类 breadcrumb 带着传给 console.log 的原始参数，可能是应用恰好打印出来的任何对象。消息文本保留（它有用），参数丢掉。

这两样都是看了一份真实报告才发现的，这也是下一节存在的主要理由。

客户端

#

应用里所有相关代码都走一个小模块，原因和我把 OTA 更新 SDK 包一层一样：OTA bundle 也会跑在原生模块还不存在时构建的安装包上。在没有 RNSentry 的安装包上，顶层写 import * as Sentry from "@sentry/react-native" 会在导入时就抛异常，结果就是白屏。所以 SDK 是延迟 require 的，而且要先确认原生模块真的存在：

import { NativeModules, Platform, TurboModuleRegistry } from "react-native";
import Constants from "expo-constants";

const DSN = process.env.EXPO_PUBLIC_CRASH_DSN;

function nativeModulePresent(): boolean {
  try {
    return Boolean(TurboModuleRegistry.get("RNSentry") ?? NativeModules.RNSentry);
  } catch {
    return false;
  }
}

export function initCrashReporting(): boolean {
  if (!DSN || Platform.OS === "web" || !nativeModulePresent()) return false;
  const Sentry = require("@sentry/react-native");
  Sentry.init({
    dsn: DSN,
    release: Constants.expoConfig?.version ?? "unknown",
    sendDefaultPii: false,
    tracesSampleRate: 0,
    enableAutoSessionTracking: false,
    // ...turn off the other tracing options the same way
    maxBreadcrumbs: 50,
    beforeSend(event) { /* tag the OTA bundle */ return event; },
  });
  return true;
}

只上报错误。服务端不存 trace、session、profile 或 replay，所以这些一个都没开。没有 DSN（开发环境、E2E 构建）时 SDK 根本不会启动。构建 profile 会设置 DSN 和环境（staging 或 production），两类构建上报到同一个接口，又能区分开。登录用户用账号 ID 标识，绝不用名字或邮箱。

错误边界需要显式调用。Expo Router 的根 ErrorBoundary 会捕获渲染错误并显示自己的界面，所以这个错误根本到不了 SDK 挂钩的全局处理器。解决办法是一个小包装组件：在 useEffect 里调用 captureException，然后照旧渲染路由自带的 boundary，根 boundary 和每个路由的 boundary 都用它。放在 effect 里而不是渲染过程中，是为了只上报一次，而不是每次重新渲染都报。根组件还用 Sentry.wrap 包了一层，如果这一步抛异常，就退回到原始组件。

Web 端有一个 .web.ts 版本的模块，所有函数都是空操作。Metro 会选平台专属的文件，所以 SDK 根本不会进入 web bundle。Web 应用也没有原生模块可以运行它。

证明原生崩溃能送到

#

单元测试 POST 的是手写的 envelope，只能证明解析器能处理我 以为 SDK 会发的东西。发布两天后，生产环境一份崩溃报告都没有。当时只有三个人更新了，所以零是说得通的，但从服务端看，“没人崩溃"和"崩溃送不到"长得一模一样。我想亲眼看到一份真的。

于是我构建了一个 Release 版的模拟器包，把 DSN 指向本地 8000 端口上的 Django，用一个临时 key：

EXPO_PUBLIC_CRASH_DSN=http://localcrashtestkey0000@localhost:8000/1 \
EXPO_PUBLIC_CRASH_ENVIRONMENT=local-verify \
xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Release \
  -destination 'platform=iOS Simulator,id=<udid>' -derivedDataPath /tmp/iosbuild

（用 Release 而不是 Debug：Debug 构建会链接 dev launcher，行为不一样，而用户跑的是 Release。）然后安装、启动，等几秒钟，再像真实故障那样把它杀掉：

xcrun simctl install booted /tmp/iosbuild/Build/Products/Release-iphonesimulator/MyApp.app
xcrun simctl launch booted com.example.myapp      # prints the pid
kill -ABRT <pid>

模拟器里的应用就是普通的 macOS 进程，所以信号到达 SentryCrash 处理器的方式和真机上完全一样。处理器把报告写到磁盘；进程临死时什么都不发送。下次启动时 SDK 找到它并发出去。我重新启动应用，一秒后模拟器的网络日志里就出现了一条到 :8000 的连接。

然后 Django 日志里什么都没有，这让我愣了一会儿：在我设的日志级别下，开发服务器只记录非 2xx 的响应。数据库里是有的：

SIGABRT: Signal 6, Code 0 | cocoa 1.4.0 iOS 27.1 iPhone19,4 handled=False
received 09:19:53, crashed 09:19:38
contexts: app, device, os, ota_updates, trace · 24 breadcrumbs

从崩溃到入库十五秒，大部分时间花在我手动重启上。而看真实的 payload，教会了我测试教不了的东西：

• 用户 ID 不是账号 ID。 测试包并没有真正登录，所以 sentry-cocoa 退而使用它自己的按安装生成的 ID。这一点值得知道，也值得写进隐私说明：登录时报告带的是账号 ID，未登录时是一个随机的安装 ID。
• 没有时区。 我原以为 culture context 会有。device context 里有 locale、内存、屏幕尺寸、低电量模式和内核版本，就是没有时区。
• 原生崩溃不经过 beforeSend。 我在 JS 的 beforeSend 里加了一个 ota 标签，标明正在运行的 OTA bundle，但原生崩溃是下次启动时由原生 SDK 组装的，根本不经过 JS 钩子。要给原生崩溃打标签，得在 bundle 确定后用 setTag 设到 scope 上，这样它才会同步到原生层。
• breadcrumbs 暴露了应用在做什么。 console 警告、view controller 生命周期，还有 HTTP 请求，其中包括分析 SDK 自己发往它的数据收集接口的请求，这也提醒了我应用还在跟谁通信。而且这些 URL 带着查询字符串，前面说的搜索词问题就是这么发现的。

怎么看这些报告

#

报告在 Django 后台里看，页面大致仿照 Sentry 的 issue 页：顶部是计数和 Resolve / Ignore / Reopen 按钮，然后是每日柱状图、按版本、系统、设备和 OTA bundle 的分布，再往下一次展示一个事件，包括异常、堆栈帧（应用帧高亮，库的帧折叠起来）、breadcrumbs 和设备信息。不需要任何新依赖。

做这个页面时顺手修了一个问题：原生崩溃的"culprit"帧原本是二进制文件在设备上的路径，里面带着每次安装都不同的 UUID，结果同一个崩溃在每台手机上看起来都不一样。现在只显示地址和二进制名，比如 0x1000a1b2c (MyApp)。

隐私政策，整份重写

#

崩溃报告差不多就是个人信息：一个账号 ID、一个手机型号，以及某人在应用崩溃前一分钟做了什么。所以隐私政策需要加一段。要写好，就得准确说明一份报告里有什么，于是我照着刚看过的 payload 列了出来：错误本身、应用版本和 OTA 更新、手机型号、系统和语言、可用内存和屏幕尺寸、最近几十步操作（打开的页面、去掉 ? 之后部分的网址、应用自己的日志），以及账号 ID 或随机的安装 ID。政策里也写明了报告直接发到我们自己的服务器，不会发给 Sentry 或任何其他崩溃上报公司。保存期限在表格里单独占一行：每个问题最近 50 份报告，外加 90 天的每日计数。

一旦开始拿代码核对其中一段，就很难不去核对其余部分。原来的政策经不起核对。删除账号页面写着：关闭账号时，推送通知的 token 和 passkey 会立即删除，服务器日志会在 90 天内清除。这些都不是真的。关闭账号会解除登录方式的绑定，并把资料匿名化，但推送 token 和 passkey 会一直留着，直到有人手动删除；日志归档目前也没有过期时间。所以整份政策根据代码实际做了什么的清单重写了一遍，那几行现在写的是"暂未自动删除，请发邮件给我们”。听起来没那么让人安心，但它是准确的。

现在代码仓库里有一条规则：政策描述的是代码做了什么，而不是我们打算做什么；任何在新地方收集、发送或保存个人数据的改动，都要在同一个 commit 里更新它。这包括应用里的摘要页面、删除账号页面，以及只存在于商店后台的应用商店隐私表单。正是崩溃上报这个改动，让我把这条规则写了下来。

还缺什么

#

符号化。 这是真正的缺口，也是 sentry.io 能做而我还没替代的那件事。JavaScript 的堆栈是压缩过的，原生代码的堆栈没有符号化：

• JavaScript： 堆栈帧指向 Hermes bundle 内部。要解决，就得为每个商店构建和每个 OTA bundle 保留合成后的 Hermes source map，按版本和 bundle 索引，在页面渲染时套用到 JS 帧上。这是下一步要做的，因为我们的崩溃大部分会是 JavaScript 的。
• iOS 原生： 指令地址需要该次构建的 dSYM。
• Android： 开启压缩时 Java 帧会被 R8 混淆（需要 mapping.txt），C++ 帧需要 NDK 符号。

前面还发现了一个小一点的缺口：原生崩溃目前还不带 OTA 标签，因为它只在 beforeSend 里设置。在运行中的 bundle 确认之后把它设到 scope 上，只要几行代码，我还没写。

目前，一个 issue 能告诉我 什么 崩了、在哪个版本、哪个 OTA bundle、哪台设备上，以及用户崩溃前在做什么。它没法告诉我崩在源码的 哪里 。对一个一周发几次版的小应用来说，到目前为止，异常类型、信息和 breadcrumbs 已经足够找到问题了。

接收端、后台页面和测试加起来代码量不大，在原本就在运行的 API 之外不额外花一分钱。难的部分由 SDK 完成：在手机上捕获崩溃，并在下次启动时把报告送出来。

声明。 这次迁移和这篇文章是 Codemagic 付费委托的。他们只对事实准确性做了一轮审阅，不涉及语气，文中没有任何内容是应他们要求修改的。凡是我遇到问题并反馈了的地方，我都会说明；如果你读到这里时问题已经修复，文中会写成已修复。

2026 年 9 月 23 日更新。 我反馈的问题，Codemagic 的开发者都逐一处理了。大部分已经修复，包括 iOS 版本检测的 bug、重复计数的安装、首次运行时的静默，以及那条吵闹的调试命令；文档现在也写到了已提交的原生工程和崩溃回滚的额度。下文中每个问题出现的地方我都标注了，仍未解决的那几个保持原样。

2026 年 10 月 16 日更新。 迁到 Patch 之后的第一次原生升级（Expo SDK 58）构建出了一个完全不含 Patch 配置的 Android release，而且没有任何地方报错。来龙去脉和只改一个文件的修复写在 第一次原生升级。

二月我写过一篇自己搭 Expo 更新服务器的文章。它现在还在跑。我运营的社区应用 maru 从那以后每一次 OTA 修复都走它，两个平台都是，每月大约一美元。

这也意味着每一块都归我管：几张数据库表、一个 API 接口、一条管理命令、一个发布脚本、一个共享密钥，还有一堆坑，每个坑都是靠一次坏掉的更新学来的。坐下来做规划时我才发现，那个脚本从我写它的第一天起，每次生产发布之后都会打印 “Sent 0 push notifications”，读的是一个这台服务器从未返回过的字段。没人注意到，最没注意到的就是我。自己维护一套东西，大概就会变成这样。

所以当 Codemagic 问我要不要试试 Patch，他们那套开源、可自托管的 CodePush 替代品，我答应了，只有一个条件：要用真实的应用，而不是 demo。真实的签名、真实的发布流程、已经提交进仓库并且手改过的原生工程，全套。大多数打算离开 EAS Update 的人，要迁的都是这样的应用，不是刚生成的模板。

下面就是整个过程，毛边都留着。

Patch 是什么

#

Patch 是一台你自己跑的服务器，加一个放进应用里的 SDK。服务端包括一个 API、一个后台 worker、Postgres、S3 兼容的对象存储和一个 Web 面板，打包成一套 Docker Compose 栈。客户端是 @codemagic/react-native-patch，一个支持 iOS 和 Android 的 TurboModule，附带 Expo 配置插件，再加一个 CLI，cmpatch，负责打包 JavaScript 并发布。

读完源码之后，有两个设计决定让我印象深刻。

第一，应用从不向 API 询问有没有更新。发布一个 release 时，worker 会把纯 JSON 的清单写进对象存储，应用只是去取那些文件。一次更新检查就是对存储或 CDN 的两个静态 GET，API 只接收指标。我原来的接口站在每一次应用启动的请求路径上；这一套想站也站不上去。

第二，每个 release 都精确地写明它面向哪个二进制版本，CLI 会对你的原生工程算一个指纹，拒绝把 JavaScript 发到原生代码对不上的二进制上。我的服务器只有一个版本字符串，剩下的全靠祈祷。

先在自己笔记本上试

#

文档一上来让你搭的是本地评估栈，从这里开始是对的。

npm install -g @codemagic/patch-cli
cmpatch selfhost local-eval up

CLI 两秒就装好了。整套栈第一次起来花了 3 分 14 秒，大部分时间在本地构建服务器和面板的镜像，而且在非交互模式下，这期间它什么都不打印，看起来和挂死一模一样。（现已修复：它现在每一步会打印一行进度。）然后四个健康的容器就出现了，全部绑定在 localhost：面板在 8080，API 在 3000，Postgres，还有 MinIO 在 9100。它很懂事地避开了我自己那套栈已经占用的端口。

这个模式下登录是关掉的，每个页面上都有一条警告，叫你别把它暴露出去。

localhost:8080

栈自带一个叫 Example Data 的种子应用，在你发布任何东西之前值得先看一眼，因为它展示了面板是用来干什么的。接下来两张截图里的数字都是种子数据，不是真实用户。

localhost:8080

localhost:8080

作为对比，我的面板就是后台里的一张更新列表，带一个“启用”复选框。到底有多少台手机真的装了更新，我完全不知道。

CLI 登录是一套正经的浏览器流程，带 PKCE 和 localhost 回调，批准页面会告诉你是哪个账号在请求，以及授权码大约一分钟后过期。

localhost:8080

对准一个真实应用

#

Patch 要求每个平台一个应用，每个应用会自动建好 Staging 和 Production 两个 deployment。我在面板里建了 maru-ios，又用 cmpatch app create 建了 maru-android，主要是两种方式都看看。建完应用后弹出的对话框是整个产品里对迁移最有用的一屏：两个 deployment key、SDK 需要的两个 URL，还有一句说明：deployment key 不是机密。

localhost:8080

两件小事。cmpatch init 当时是把项目关联到已经存在的应用上，所以不管迁移指南怎么暗示，它都不可能是第一条命令。这一点后来修好了：在交互模式下，它现在会自己给每个平台建一个应用。另外，对话框给的 API URL 是 http://localhost:8080，而文档和 CLI 说的是 3000。两个都能用，因为两个端口都同时提供这两种服务，但你会犯嘀咕。

接着我对着还没动过的应用跑了 cmpatch doctor，三秒钟它就找出了一个真问题。它报告 iOS 二进制版本是 2.0.0。应用其实是 2.5.1。

CLI 会找出 ios/ 下所有的 Info.plist，如果没有一个路径里带 “test”，就按字母顺序取第一个。maru 有一个 WidgetKit 扩展，它的目录按字母排在应用本身的目录前面，于是 CLI 拿到的是扩展的 Info.plist。这个 plist 还停在 2.0.0，这是我的 bug，但后果很难看：自动检测会把每一个 iOS release 都对准一个没有任何手机在跑的版本，而且不会报任何错。更新只是永远不会到，正是我在自建服务器那篇里警告过的那种故障。Android 读 versionName 是对的。绕过的办法是传 --target-binary-version 或 --plist-file，我的发布脚本现在会先检查 app.config.js 和两个原生工程的版本一致，然后显式传入版本。后来同一个 bug 又让 doctor 自己的清单检查在一个运行正常的 deployment 上失败，因为它跑去找 2.0.0 版本的清单了。修好过期的 plist 之后，doctor 的 24 项检查全部通过。

Codemagic 后来修复了这个问题。CLI 现在读取的是应用 target 的 Info.plist，而不是扩展的；如果有不止一个 target 可能是应用，cmpatch 会问你是哪一个。

JavaScript 这一侧

#

去掉 expo-updates、加上 SDK，是两行的改动。把应用原来围绕更新做的那些事换过来，要多想一想。

maru 在启动时和每次回到前台时检查更新，最多每十五分钟一次。发现更新就下载，然后提议重启；你说不，它就在下一次冷启动时应用。设置页里还有一个手动检查，显示当前跑的是哪个 bundle，错误上报器也会给每份报告打上它来自哪个更新的标签。

从 SDK 源码里学到的第一件事是，它在 import 时就用 TurboModuleRegistry.getEnforcing 查找原生模块，模块不存在就直接抛错。maru 还有一个 Web 构建，顶层 import 会把 Web 应用整个搞挂。所以一切都走一个懒加载 SDK 的小模块，配一个什么都不返回的 .web.ts 孪生文件，这样还能把 SDK 彻底挡在 Web bundle 之外。

// ota.ts (ota.web.ts exports a patchSdk() that always returns null)
import { Platform } from "react-native";

type PatchSdk = typeof import("@codemagic/react-native-patch");
let sdk: PatchSdk | null | undefined;

export function patchSdk(): PatchSdk | null {
  if (sdk !== undefined) return sdk;
  if (Platform.OS === "web") return (sdk = null);
  try {
    sdk = require("@codemagic/react-native-patch") as PatchSdk;
  } catch {
    sdk = null;
  }
  return sdk;
}

自动检查本身主要就是 sync()，它从不抛错，而是 resolve 成一个状态：

const status = await patch.sync({
  installMode: "ON_NEXT_RESTART",
  mandatoryInstallMode: "ON_NEXT_RESUME",
});
if (status === "update-installed") offerRestart();

SDK 对强制 release 的默认值是 IMMEDIATE，不管用户正在干什么都会直接重载 JavaScript。我改成了下次从后台回来时再应用，因为弄丢一篇写了一半的帖子，这个 bug 比大多数修复带来的好处都要糟。当时 InstallMode 是字符串联合类型，不是文档示例里暗示的那种枚举对象；现在它导出为一个常量对象，所以 InstallMode.ON_NEXT_RESTART 可以照文档那样用了。

原生这一侧，当 ios/ 和 android/ 已经提交进仓库

#

迁移指南说，加完配置插件后跑 npx expo prebuild --clean。我在另一个 checkout 里跑了，它删掉了随包的图片、我的 Android 网络安全配置、iOS 隐私清单和 Podfile.lock，还把 build.gradle 里一个给测试工具做的修复连同 Info.plist 里的几百行一起回退了。不加 --clean，Expo 照样把两个目录清空。

这不怪 Patch。maru 一开始是托管的 Expo 应用，后来长出了原生定制，所以 ios/ 和 android/ 是提交进仓库的，EAS 拿它们原样构建。但长这样的应用多得很，指南当时没有提醒。现在有了：Expo 迁移指南分成两条路径，生成原生工程的走 prebuild，已提交原生工程的则列出需要手动应用的具体改动。

插件实际改的东西，其实少到可以手动完成。iOS 上，AppDelegate.swift 里一个 import 加一行：

return CodemagicPatch.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")

Android 上，MainApplication.kt 里一个 import 加一个参数（这是 React Native 0.82+ 的写法；更早的版本是改写 getJSBundleFile()）：

ExpoReactHostFactory.getDefaultReactHost(
  jsBundleFilePath = CodemagicPatch.getJSBundleFile(applicationContext),
  // ...

再加上每个平台三个配置值，以及删掉旧的 expo-updates 设置：两个工程加起来新增 13 行、删除 20 行。

插件会在 prebuild 时把那些配置值写成字面量，对于提交了原生工程的项目，这意味着每次构建都只能有一个写死的 deployment。我想让 preview 构建走 Staging、商店构建走 Production，用的还是同一个工程，所以这些值改成从构建环境来。Info.plist 里，Xcode 会展开构建设置：

<key>CodemagicPatchDeploymentKey</key>
<string>$(PATCH_IOS_DEPLOYMENT_KEY)</string>

android/app/build.gradle 里：

def patchEnv = { name -> System.getenv(name) ?: (findProperty(name) ?: "") }
resValue "string", "CodemagicPatchDeploymentKey", patchEnv("PATCH_ANDROID_DEPLOYMENT_KEY")

这些 key 于是和 EXPO_PUBLIC_ 那些值一起放在 eas.json 的各个构建 profile 里。值为空时 SDK 会安静地什么都不做，本地构建没关系，商店构建就是灾难，所以 app.config.js 现在会在 preview 或 production 的 EAS 构建缺了这些值、或者还指向 localhost 时直接抛错。

第一次更新

#

第一个 release 我改的是引导页的大标题，不用登录就能看到，然后发布：

./scripts/publish-update.sh ios --notes "Onboarding headline over the air"

耗时 30 秒，大部分是 Metro 和 Hermes。上传完成 0.6 秒后，服务器的 worker 就发布了清单。这个更新是一个 7.3 MB 的压缩 tarball，而我旧的导出流程产出的是 11 MB 的 Hermes bundle 加资源。

这里有一件事要做对：JavaScript bundle 在构建时会把 EXPO_PUBLIC_ 那些值内联进去，所以一次更新必须用和它要落上去的那个二进制相同的值来构建，否则你发出去的 JavaScript 会连到错误的后端。我的脚本从构建那个二进制的同一个 eas.json profile 里加载它们。Patch 的 CI 文档现在也把这一点写清楚了，还说明了 release-react 本身不会读取 EAS profile。

然后我重新启动应用。设备日志显示整个更新检查就是对对象存储的两次请求，meta.json 和 2.5.1/manifest.json。启动三秒后 SDK 写下了一条 Downloaded 事件，把更新暂存好，应用弹出了重启提示。

bug 是我的

#

然后我看了看面板。一台模拟器装了 release v1，面板却显示两次成功安装、两个活跃用户。

localhost:8080

SDK 把自己的状态和待发送的指标事件以文件形式存在应用容器里，追起来很方便。里面有两条 Success 事件，时间戳完全相同，id 不同。我的 hook 在挂载时用 notifyAppReady() 确认当前 bundle，紧接着就调用 sync()，而 sync() 自己也会调用 notifyAppReady()。两次调用重叠了，各自都看到这个 release 处于待确认状态，各自都记了事件。服务器按事件 id 去重，但这两条 id 不同，所以都算数了，而且这些重复是永久的。

我这边的修复是每次启动只做一次共享的确认，其他所有东西都等它。SDK 自己也可以防一下重叠调用，这一点我提了建议。现在它确实这么做了：重叠的 notifyAppReady() 调用，包括 sync() 内部那一次，会共用同一次确认，所以每次安装只记一次。SDK 参考文档现在也写明了 sync() 会自己确认就绪，用它的应用不需要再单独调用 notifyAppReady()。

舒服的地方在于发修复。这是纯 JavaScript 的改动，所以作为 release v2 发了出去，而且因为可以给 v1 上的设备发二进制差分，v2 下载下来是一个 543 KB 的 patch，而不是 7.3 MB 的 bundle，大约是原来的 7%。重启之后：一次下载、一次安装、一次成功、一台活跃设备。

localhost:8080

故意弄坏它

#

回滚是我最在意的功能，因为旧方案在设备端什么都没有。一个坏更新会让每次启动都崩溃，直到我注意到并把复选框取消勾选。

所以我发了一个 v3，在第一次渲染之前就抛错，也就是它永远没机会调用 notifyAppReady()。应用下载了它，提示重启，然后死回了主屏幕。

下一次启动又跑了 v3，又崩了，这让我很意外，因为文档说在 notifyAppReady() 之前崩溃的 bundle 会被回滚。源码解释了原因：SDK 允许三次未确认的启动，之后才判定为崩溃，因为一次未确认的启动也可能只是 iOS 在任何 JavaScript 跑起来之前就杀掉了一个健康的进程。第四次启动回到了 v2。

然后设备自己上报了这次失败，类型是 crash_rollback，面板把它记在了 v3 名下。这个设计合理，但有必要把它的含义说白：一个坏 release 会让每个用户崩三次启动才能恢复，而当时文档没有提这个数字。现在提了，而且这个额度可以配置，原生侧用 CodemagicPatchMaxLaunchAttempts，或者用 Expo 插件的 maxLaunchAttempts。这正是先发 Staging、再小比例发 Production 的理由。

替其他所有人叫停一个坏 release 是一条命令，不到一秒：

cmpatch release rollback --app maru-ios --deployment Staging

它不改写历史。它把上一个 release 重新发布成一个新的（v4，标记为 v2 的回滚），所以崩溃的那个 release 连同它的失败计数一起留在列表里，这是诚实的记录。面板上通过一个对话框做同样的事。

localhost:8080

Android

#

Android 有两个意外，都不是 Patch 的问题。我给 SDK 加的 R8 keep 规则放在 app.config.js 里，而它只能通过 prebuild 才能到达原生工程，所以我第一个 release 构建等于无意中测试了 SDK 在没有 keep 规则的情况下能不能扛住 R8。能：R8 把它所有的类都重命名了，更新照样下载、安装、回滚，一切正常。另外，刚冷启动的模拟器加上还占着内存的 Gradle，慢到我的第一次测试在 SDK 完成那个早已开始的下载之前 45 秒就放弃了。

Release v1 应用成功，一次成功、一台活跃设备，一个会崩的 v2 在同样的三次启动额度之后回滚了。

顺利路径之外

#

更新能到、能回滚是核心，但一个团队天天用的是其他那些功能，所以我一个一个过了一遍。

灰度发布是确定性的，这点我喜欢。md5(deviceId + "-" + releaseLabel) 的前八位十六进制数字对 100 取模，小于灰度百分比的设备就在圈内，所以同一台手机对某个 release 要么一直在、要么一直不在。我算出模拟器在下一个 release 里落在 91 号桶，按 25% 发布，模拟器果然什么都没收到。用 cmpatch release patch 提到 95%，不到一秒，下次启动它就更新了。

接着我的下一个 release 失败了，返回 409：“deployment has an active rollout below 100 percent”。每个 deployment 同时只允许一个部分灰度，所以你得先把金丝雀发完、禁用或者回滚，才能发别的。这合理，也有文档，但一条每次合并都发布的流水线会在金丝雀进行到一半时撞上它。我反馈之后，CLI 在这里会把话说清楚了：如果是一个进行中的部分灰度挡住了你，它会告诉你等也没用，以及怎么把灰度发完或禁用；如果是另一个发布任务还在跑，它会让你用 release inspect --wait 等着。文档现在也有一节专门讲按顺序进行的发布变更。

强制 release 用的是 SDK 的 mandatoryInstallMode。我设的是下次回到前台时应用，应用下载了更新并弹出提示，我无视提示，把应用切到后台再切回来，新版本就直接在那里了。

禁用一个 release 做的不只是停止提供它。我一禁用最新的那个，清单就立刻指向了仍然启用的最新 release，禁用版本上的设备会被推一个回到它的 patch。把某个二进制版本的 release 全部禁用，清单的目标就变成 null，SDK 会把应用退回到它随二进制自带的 bundle。我的更新 hook 起初没有对这种情况弹提示，现在有了。

从 Staging 提升到 Production 不到一秒，而且复用的正是测试过的那个包，同样的哈希和备注，不会重新构建。它还接受一个灰度百分比，所以“提升到 Production 的 10%”就是一条命令。

构建和发布也可以拆成两步。cmpatch bundle 产出一个 .cmpatch 产物，面板的 “Bundle upload” 选项会在上传前读取它：平台、目标版本、指纹、签名状态、大小和打包器。这适合 CI 构建产物、再由别人决定什么时候发布的场景。

也是在这里，我真正撞上了指纹保护。修好过期的 widget plist 之后，服务器以 409 拒绝了我的下一个 release，因为原生工程的指纹和它为 2.5.1 记录的那个对不上了。Android 上，改一下 app.config.js 里的注释就够触发了，因为 Expo 把应用配置也算进指纹。面板把同样的检查显示成一条警告，带两个指纹和一个 “Upload anyway” 按钮。这两次已安装的二进制上都没有任何原生的东西变过，所以覆盖是对的。但在真实使用里，诚实的答案几乎总是升版本号、重新做一次商店构建，我的发布脚本现在遇到这种情况就会这么说。

代码签名用的是 RS256：CLI 用 RSA 私钥给包的哈希签名，SDK 用编译进二进制的公钥校验。公钥以一行 base64 的形式放进去，正好契合我走构建设置的做法，两个平台我都测了。应用里带了公钥之后，未签名的 release 在下载前就被拒了。给应用打开 “require code signing” 后，服务器拒绝了未签名的发布，错误信息里写明了修法并链接到指南。签名的 release 正常安装，SDK 记录签名为已验证。当我禁用签名的那个 release、服务器退回到一个更早的未签名 release 时，SDK 也把它拒了。要注意的是，公钥必须在你发出的第一个二进制里就带上，因为更新没法把它加进去。

localhost:8080

团队和 CI 也都覆盖到了。成员会拿到四种团队级角色之一（owner、admin、developer、viewer），邀请会一直等到对方第一次登录。个人访问 token 在空的 home 目录下也能用，通过 --token 或环境变量传入都行，token 列表会显示每一个上次使用的时间。我还写了一个手动触发的 CI workflow，在 Linux runner 上跑同一个发布脚本，签名密钥来自 secret，不过还没跑过，因为它需要托管的服务器。

有一个工具当时我会跳过，cmpatch debug ios。它按 “OTA” 不区分大小写过滤系统日志流，而这会匹配到 “Rotation”，于是一次二十秒的应用启动产出了满屏的 SpringBoard 消息，应用自己的一条都没有。这已经修好了：它现在只显示带 SDK 标记的行。SDK 本身日志不多，主要是错误和开发构建下的警告，所以输出会很安静。你可能看到的那条 getpwuid_r 警告来自 xcrun simctl，不是 Patch。

到底有多难

#

Codemagic 想听我的看法，那就尽量说得直白。

试用很容易。两条命令、几分钟，你就有了真正的服务器、一个带演示数据的面板，和一个可以对准自己应用的 CLI。我会说这是头一个小时里最好的部分。

集成 SDK 是中等工作量，而且难点大多在你自己的项目里，不在 Patch。在一个原生目录是生成出来的新 Expo 应用上，确实就是插件加几行替换 expo-updates 调用的代码。在 maru 这样的应用上，原生工程已提交、有 widget 扩展、有 Web 构建、有 R8 和构建 profile，活儿都在边边角角。我得手动应用原生改动来避开 prebuild，把配置改成构建时注入好让 Staging 和 Production 构建能不一样，还要把 SDK 挡在 Web 之外。我还得保证更新里的 JavaScript 和二进制用同样的环境构建。搞明白之后没有一件是难的。我做的时候，这些大多不在文档里，不过已提交原生工程的路径和 bundle 构建时的环境，现在都写进去了。

日常使用很好。发布是一条命令，半分钟左右。灰度、提升、禁用和回滚，从 CLI 或面板操作都不到一秒，错误信息会说出了什么问题、该怎么办。服务器的那些保护（指纹检查、同时只能一个金丝雀、签名）严格得不止一次拦住我做错事。

在生产环境跑它是更大的承诺。它是一套带 Postgres 和对象存储的 Docker Compose 栈，你得托管、备份、升级，还需要两个域名和一个 OAuth 应用。对已经在跑服务器的团队，这是一个安静的下午。对那些正因为不想碰服务器才用 EAS 的团队，这才是切换的真实成本，比 SDK 那部分工作更大。

按挂钟时间算，我 12:29 装好 CLI，13:34 第一个更新在模拟器上应用成功，其中半小时是一次 Xcode 构建卡住了，原因和 Patch 无关。这篇文章里的所有东西，两个平台，都在下午过半之前做完了，托管服务器不算在内。

最耗我时间的几件事，按顺序：expo prebuild --clean 抹掉了我提交的原生工程，然后是研究怎么手动接好一切；iOS 版本检测的 bug，它会把更新发给一个没人在跑的版本；重复计数的安装，虽然是我自己造成的，但任何人都很容易重蹈，因为 sync() 自己会调 notifyAppReady()；还有没写进文档的三次启动崩溃额度，在一次测试进行到一半时把我吓了一跳。再往后是一些本身正确、但需要规划的事：无害的原生相关改动触发指纹保护，每个 deployment 同时只能一个金丝雀，以及不能重叠的生命周期任务，一旦脚本要连着做几件事，这就很要紧。剩下的都是小事：首次运行时静默的搭建过程、一条吵闹的调试命令，还有几个当时和代码对不上的文档示例。

这些我都连同细节一起写给了 Codemagic，到 9 月 23 日，大部分已经修复：版本检测、重叠的确认、prebuild 的提醒、崩溃额度、静默的搭建过程、调试命令、InstallMode 的示例，以及发布任务或金丝雀挡路时给出的报错。还没解决的都是小事：面板显示 API 在 :8080，而其他地方都说 :3000；SDK 在 Web 和 Jest 里一 import 就抛错；以及文档里的几处空白。

上生产

#

上面的一切都是在评估栈上跑的。生产就是同一个应用、同一套脚本对准一台真实的服务器，下面是 maru 的计划。

官方支持的服务器部署方式是 Docker Compose 安装：一台开放 80 和 443 端口的 Linux 机器、两个域名（一个给 API 和面板，一个给下载），以及一个用于登录的 GitHub OAuth 应用，没有它服务器不会启动。安装器负责剩下的事，包括 TLS：

scripts/selfhost/install.sh \
  --api-domain updates.example.com \
  --storage-domain storage.updates.example.com \
  --email you@example.com \
  --github-oauth-client-id <id> --github-oauth-client-secret <secret>

它会写一个 .env.selfhost，里面是数据库和存储的密钥，应该放进你的密码管理器。

不过你不一定要用自带的数据库和存储，这正是它能嵌进我这种栈的原因。maru 的 API 已经跑在 Fly.io 上，文件放在 Tigris，Patch 在两者上都能工作。Compose 文件底下，服务器就是一个以 MODE=all（API 和 release worker 一起）运行的容器，需要一个 Postgres 数据库、S3 兼容存储，和一个供文件访问的公开 HTTPS URL。也就是一个用仓库的 Dockerfile 构建的 Fly 应用（目前还没有发布的镜像，所以由 fly deploy 来构建）、一个 Fly Postgres 数据库，和一个 Tigris 桶：

MODE=all
DATABASE_URL=postgresql://…            # Fly Postgres
STORAGE_ADAPTER=s3
S3_ENDPOINT=https://fly.storage.tigris.dev
S3_REGION=auto
S3_BUCKET=myapp-patch
S3_FORCE_PATH_STYLE=true
PUBLIC_BASE_URL=https://myapp-patch.fly.storage.tigris.dev/codemagic-patch

两点提醒。在 Compose 之外运行，仓库里的文档把它定位为参考材料，而不是这个首个开源版本里受支持的路径，所以在 Fly 上，升级和备份得靠你自己。我也还没这样部署过；这是计划，不是报告。另外，如果你读过我写 Fly 缩容到零的那篇，记得至少留一台机器在跑。手机做更新检查时从不等 API，因为清单直接来自存储，但不然的话，每一次指标上传和每一个 release 任务都会从一次冷启动开始。

Tigris 是我最期待的部分。maru 的文件本来就在那儿，而且它在每次应用启动都要访问的那个 URL 前面放了一层 CDN。这么做的话要留意清单的缓存：用普通的 base-URL 分发适配器时，Patch 会把清单以 no-cache 提供，因为它没法清 CDN，而一份按自己 TTL 缓存的清单会一直提供你刚刚回滚掉的那个 release。配置参考现在在 MANIFEST_CACHE_CONTROL 下写明了这一点，文档站也讲到了 S3 兼容存储。

在托管服务器上，重新建一遍应用，把新的 key 放进 eas.json 的 preview 和 production profile（分别是 Staging 的 key 和 Production 的 key），再创建一个用于发布的 token：

cmpatch token create --name ci

想要代码签名的话，现在就定：生成生产环境的密钥对，私钥作为 CI secret 保管，公钥放进构建 profile，然后给两个应用都打开 “require code signing”。第一个 Patch 二进制还需要一个新版本号，因为商店里已有的二进制跑的是 expo-updates。先用 preview profile 构建给 TestFlight 和 Play 内部测试，交给任何人之前，先确认 key 真的进了构建出来的 Info.plist 和 Android 资源。这是我本地测试唯一没有覆盖到的一环，因为环境变量是我手动导出的。然后发到 Staging，确认每个测试者一次下载、一次成功，之后才构建商店版本。

生产 release 从小开始，逐步放大：

./scripts/publish-update.sh ios --production --rollout 10
cmpatch release patch --app maru-ios --deployment Production --label v1 --rollout-percentage 100

旧服务器这期间继续开着。所有还没更新的 2.5.1 副本仍然在向它检查，给它们的热修复也仍然走旧脚本。等日志显示那些请求停了，旧服务器连同它的发布脚本和密钥就可以全部删掉。

第一次原生升级

#

2026 年 10 月 16 日补充。

从 10 月初开始，maru 的生产更新就交给 Patch 来发了。那之后的第一次原生发布是升级到 Expo SDK 58：React Native 0.88，Android 上还有 Gradle 插件的一个新大版本。原生改动没法 OTA，所以这是一个新的二进制 2.6.0，而我的发布脚本在这个二进制存在之前会拒绝发 2.6.0 的更新。两个平台第一次就都干净地构建成功了。

上面的生产部分说过，交给任何人之前，先确认 key 真的进了构建出来的 Info.plist 和 Android 资源。这次我真的查了，而这一节正是因为这次检查才有的。iOS 构建里四个 Patch 设置都在。Android 构建里一个都没有：

bundletool dump resources --bundle=build.aab --values | grep -A1 "string/Codemagic"

这条命令对 2.5.11 的构建打印出四个 key，对 2.6.0 什么都没打印。问题不在环境变量：Gradle 的 generateReleaseResValues 四个都写了。它们是之后被 release 构建的资源缩减器（resource shrinker）删掉的，而它在 Android Gradle Plugin 9 里激进了很多。同一个应用的资源从 9,240 个降到了 7,116 个。SDK 用 getIdentifier 按名字读取配置，缩减器看不到这种用法，于是把这四个字符串当成没用的删掉了。缺失的字符串读出来是空的，而空意味着"没有更新"。什么都不会失败。Android 2.6.0 会正常安装、正常运行，却永远收不到更新，唯一的迹象是面板上一台 Android 2.6.0 设备都没有。

修复是一个资源文件，告诉缩减器保留这四个字符串：

<!-- android/app/src/main/res/raw/codemagic_patch_keep.xml -->
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@string/CodemagicPatch*" />

别把它叫做 keep.xml：React Native 的 bundle 任务已经会为你的 JavaScript 资源生成一个 raw/keep.xml（图片和字体能幸存就是因为它），两个文件会冲突。这条规则更合适的位置是 SDK 本身，因为库的 keep 文件会自动合并进应用；而 release 构建在没有 deployment key 的情况下启动时，只要有一条警告，就能把这种悄无声息的情况变成看得见的。这和前面 iOS 版本检测的 bug 是同一类失败：什么都不报错，更新就是永远不来。

同一次检查还发现了第二个问题，跟 Patch 无关，但出于另一个原因值得知道。Android 的 release 构建一启动就崩溃，而且崩了两次，原因是 Expo 自己模块里的两个不同问题。第一个是 Expo 的 widget 模块没能注册它的原生类，所以应用在任何 JavaScript 运行之前就挂了。修好之后，应用能走到启动 JavaScript 这一步，然后就停住了，因为有三个已经迁到 Expo 新模块系统的模块从来没被注册。这两种情况 Patch 的崩溃回滚都帮不上忙，因为根本没有可以回滚的更新。它保护你不受坏更新的影响，而不是坏二进制。不管用不用 Patch，原生升级在上商店之前都得在真机或模拟器上装好、打开一次。

同一轮测试还带出了一件小事。sync() 失败时会返回 "error"，除非应用跑在开发模式下，否则不会告诉你原因，所以 release 构建只能在日志里记一句出错了。现在我的 hook 在 sync 失败后会调用一次 checkForUpdate()，把它抛出的错误记下来，我就是这样发现问题不是服务器坏了，而是一个本地模拟器构建的 Patch URL 是空的（unsupported URL）。如果最后一次的错误在 release 构建里也能读到，会有帮助。

我的原生发布检查清单现在多了以前没有的三行：从构建出来的 .ipa 和 .aab 里导出 Patch 设置，把 deployment key 和构建 profile 对一遍，以及在提交前启动 release 构建本身，而不是 debug 构建。

想对正在付 Expo 账单的人说的话

#

如果你付费用 EAS Update 是因为搭服务器看起来太费事，Patch 是一个实在的答案：你确实要跑一台服务器，但那是一套 Compose 栈和一个安装器，不是你要维护的代码。和我自己搭的那套相比，你会得到灰度发布、每个 release 的安装和失败数字、二进制 patch、指纹保护、代码签名、设备端的崩溃回滚，和一个回滚按钮。这些我一个都没做过。

代价是：在任何人收到 Patch 更新之前先要发一个新二进制，因为 SDK 得进到应用里；一台要持续升级和备份的服务器；release 坏得够彻底时每个用户三次崩溃启动（默认值）；以及原生工程已提交的话，一些手工活。它也还年轻。这是 0.3.0 版本，我碰到了一个版本检测 bug、一条吵闹的调试命令和文档里的几处空白，还自己造了一个 SDK 本可以防住的 bug。版本检测和调试命令后来都修好了，文档的空白大多补上了，SDK 现在也能防住我犯的那个错。这些都没有挡住迁移，而且全都看得见，在 CLI 里、在面板里、或者在设备上 SDK 自己的文件里，这一点我的旧方案可说不上。

我做的这个集市应用是用 React Native Web 写的单页应用。在 JavaScript 跑起来之前，每一个商品页都只是一个 script 标签加一个空 div。这对人没问题，对搜索却是致命的：Google 有时能执行那段 JS，Bing 不会，而对一个商品几乎全是韩语的站点最要紧的 Naver 爬虫，肯定不会。

这篇讲的是我怎么让这些页面被看见，以及之后那条以我没预料到的方式把成果抵消掉的缓存规则。

动态渲染，不是伪装

#

办法很老，而且 Google 认可：识别爬虫，给它返回一份服务端渲染的 HTML，内容和 SPA 本该画出来的一样。不是不同的内容，是同样的内容，只是更早。

于是像 /listings/view?id=... 这样的商品 URL 分叉了。浏览器拿到 SPA 外壳。爬虫拿到一份真正的文档：一个标题，商品的关键信息，每张照片一张带 alt 的图，一段正文摘录，以及通往几个相关商品的链接，好让这页不至于成为孤儿。

最后那点比我预想的重要得多。在这些内链存在之前，大约一千个商品页没有任何东西指向它们，Search Console 里能看到抓取一路沉到每天 7 到 11 次请求。找不到你页面的爬虫，不会在乎那些页面有多好。

陷阱：厂商的名字不是它家爬虫的名字

#

爬虫识别是 user-agent 匹配，问题就出在这里。

韩国平台用的爬虫名字和公司名一点都不像。Naver 的爬虫叫 Yeti，Daum 的叫 Daumoa，Kakao 的链接抓取器叫 kakaotalk-scrap。三个都不是厂商名。

与此同时，同样这几家还发布带内嵌浏览器的 App，那些浏览器发送的是真实浏览器 UA，后面缀上 App 的名字。KakaoTalk 的内置浏览器说自己是 KAKAOTALK/10.5.1，Kakao 的抓取器说自己是 kakaotalk-scrap/1.0。

用 kakao 去匹配，两个都会中。我当初正是这么干的，结果每一个打开链接的 KakaoTalk、Naver App、Daum App 用户，拿到的都是爬虫页：没有 JavaScript，没有导航，没有登录。一份挑不出毛病的文档，对人却毫无用处。

修复靠的是判断顺序，这一点值得明确写成规则：

import re

# 内嵌浏览器会在普通浏览器 UA 后面附上应用名。
INAPP_BROWSER_RE = re.compile(r"kakaotalk/|naver\(inapp|daumapps", re.I)

# 认机器人名，不认厂商名：Naver 用 Yeti，Daum 用 Daumoa，
# Kakao 的链接预览抓取器用 kakaotalk-scrap。
CRAWLER_RE = re.compile(r"googlebot|bingbot|yeti/|daumoa|kakaotalk-scrap", re.I)


def is_crawler(user_agent: str) -> bool:
    # 内嵌浏览器永远不是爬虫，所以这个判断放在最前面。
    if not user_agent or INAPP_BROWSER_RE.search(user_agent):
        return False
    return bool(CRAWLER_RE.search(user_agent))

内嵌浏览器先判断，而且它赢。并且每一个爬虫匹配词都必须指向一个机器人，而不是一个厂商。

然后我在前面放了 Cloudflare

#

源站是悉尼的一台共享 CPU 机器，能撑住每秒二三十个请求。Googlebot 要走大约 995 个 URL，而它们全都打到了悉尼，因为每一个 URL 的 cf-cache-status 都是 DYNAMIC：除非有规则明说，Cloudflare 不缓存 HTML。 整个站点大约 16% 的内容被缓存，而真正要紧的那部分一个也不在里面。

那就给爬虫页加一条缓存规则。很简单。除了一点：一个商品 URL 并不只有一个响应体，它有三个。

• 要 HTML 的爬虫拿到服务端渲染页。
• 人拿到 SPA 外壳。
• 发送 Accept: text/markdown 的 agent 拿到 Markdown，从数据库拼出来的，因为把一个空的 HTML 外壳转换一遍只会得到一份空文档。

源站会发 Vary: Accept，而对 user-agent 做 Vary 本来也没什么指望。然后就是我不知道的这件事：

Cloudflare 在 HTML 上忽略 Vary。 三个响应体共用一个缓存键。

哪个先到，哪个就占住这个 URL，对该边缘节点之后的所有访客生效，持续源站 s-maxage 允许的一小时，再加上一天的 stale-while-revalidate。

我在生产环境两个方向都亲眼见到了：

• 一个 Naver App 用户用爬虫页预热了某个商品 URL，随后普通的 iPhone Safari 就在一次 HIT 上拿到了那个页面。一个人盯着一份没有 JavaScript 的文档。
• 一个人用 SPA 外壳预热了某个 URL，Googlebot 拿到了空外壳。整套 SEO 工作要防的正是这个失败，如今它更快了，还是从边缘发出来的。

靠收窄来修复的规则

#

你没法让 Cloudflare 在 HTML 上尊重 Vary。你能做的，是确保三个响应体里只有一个有资格进缓存：

(starts_with(http.request.uri.path, "/listings/")
 and not any(http.request.headers["accept"][*] contains "text/markdown")
 and (lower(http.user_agent) contains "googlebot" or ...)
 and not (lower(http.user_agent) contains "kakaotalk/" or ...))

只匹配爬虫 UA，并排除 Markdown 请求。现在人的请求不匹配任何规则，于是读到 DYNAMIC 并像以前一样回源。只有爬虫请求读写缓存，而能进到缓存里的响应体只有爬虫那一个。

边缘 TTL 用 respect_origin，于是有效期仍归渲染这个页面的代码所有，而不是被钉死在控制台里。

一个容易漏掉的运维细节：收窄规则并不会驱逐已经在缓存里的东西。 得手动清一次缓存，否则那些刚刚已不再生成的污染条目还会继续被发出去。

两份清单，以及它们的错误为何不对称

#

这条规则需要一份爬虫 UA 清单，而 Django 里已经有一份。同一份知识在两个系统里存两份通常是坏味道，但这里有意思的是它们漂移时会发生什么，因为并不对称：

• Cloudflare 里的机器人清单必须始终是 Django 那份的子集。 一个 Cloudflare 认为是机器人而 Django 不认的匹配词，会把 SPA 外壳缓存到爬虫专用键下，然后发给真正的爬虫。
• 内嵌浏览器的排除清单必须是 Django 那份的超集。 排除得太多，代价只是少几次缓存命中。

任何一边朝安全方向错，你只是少缓存一点。第一条朝另一个方向错，你就又在给 Googlebot 发空页面了。顺带一提，这种不对称也正是这些清单用 contains 而不是正则的原因：matches 需要 Business 套餐，而对一份允许在已知安全方向上粗糙的清单，contains 够用了。

一条让构建失败、而不是让页面失败的不变式

#

爬虫页里嵌着有效期七天的预签名图片 URL。页面本身在边缘缓存一小时，外加一天的 stale-while-revalidate。

这两个数字是相关的，一旦缓存寿命超过图片寿命，边缘就会开始发出每张照片都 403 的页面。不会有任何告警，因为 HTML 本身没问题。

所以定义这些数值的代码，在关系被破坏时会拒绝导入：

CRAWLER_IMAGE_TTL = 7 * 24 * 3600  # 预签名图片 URL
EDGE_S_MAXAGE = 3600
EDGE_STALE_WHILE_REVALIDATE = 24 * 3600

# 边缘缓存可能比图片 URL 活得更久时，在 import 时就失败。
if EDGE_S_MAXAGE + EDGE_STALE_WHILE_REVALIDATE >= CRAWLER_IMAGE_TTL:
    raise RuntimeError("edge cache lifetime must stay below the image URL lifetime")

两个分处不同文件的常量之间的约束，在代码评审里看不见，在进程启动时却一目了然。把它放在进程启动的地方。

Cloudflare 做的两件、我不得不撤销的事

#

Vary: Origin 把打包产物挡在了缓存之外。 django-cors-headers 会在它经手的每个响应上打 Vary: Origin，而 Cloudflare 拒绝缓存任何在 Accept-Encoding 之外还有 vary 的响应。这就悄悄把关键路径上最大的那个 1.6 MB JavaScript 包整个排除在边缘之外。修法是把一个中间件放在列表最前面，让它在出站方向最后执行，重写静态资源路径上的 Vary。

边缘压缩比源站压缩更差。 让 Cloudflare 现场做 Brotli 得到 2,041,742 字节，而源站自己的 gzip 是 1,658,115 字节。为了不用动脑，代价是大了 23%。即时压缩优化的是 CPU，不是压缩率；源站预压缩的资源会赢。

不等抓取就告诉搜索引擎

#

两个协议，加在一起覆盖面也令人失望。

IndexNow 接受一次 ping，覆盖 Bing、Yandex 和 Seznam。Google 和 Naver 不参与。每次保存商品时，我在后台带着很短的超时发一次 ping，已售出和已关闭的条目直接跳过。网络失败只记一条警告，绝不让触发它的那次保存失败——这是一个尽力而为的旁路通道唯一可以接受的行为。

Google 的 Indexing API 只接受两种结构化数据类型，其中之一正是我有的 JobPosting。在招的职位发 URL_UPDATED，关闭的发 URL_DELETED。那条删除通知之所以诚实，是因为关闭的条目同时输出了 noindex，代码里也这么写着——好让日后拿掉 noindex 的人知道自己还顺手破坏了什么。

这里有两处让我耗了不少时间。配额是每天 200 个 URL，而批量导入一次商品就会触发几百次，所以导入进来的条目会被跳过，否则一次导入就把当天预算全花光。另外端点是带冒号的 urlNotifications:publish。用斜杠的话，Google 返回一个普通的 HTML 404，看起来和 API 没启用一模一样。

结构化数据教给我的

#

三条规则，每一条都是被 Search Console 数落出来的：

1. 解析不了的就别输出。 薪资是自由文本。我以前把原始字符串当作 baseSalary.value 输出，那是无效的，还让每一条职位都被标记缺少单位。现在解析不了的薪资干脆不出现。
2. 别为了满足结构化数据的要求而编造字段。 招聘广告很少带街道地址。人会很想给 PostalAddress 填个看着像样的东西。招聘广告上编造的地址比不完整的地址更糟，所以只放城市和国家。
3. 有效期不是可选项。 Google 会丢掉没有 validThrough 的 JobPosting，所以要推导一个，并加上下限，免得一条旧条目声称自己昨天就过期了。

还有关于站点地图的第四条：别给所有条目都声称 changefreq: daily。 要求 Googlebot 每天重新抓取一千个条目，会被读成一台过载的主机，而它的回应是降低整站的抓取速率。从这东西实际上多久变一次来推导。

站点地图还有一道质量下限：标题加正文合计四十个字符。Search Console 曾把大约一千条报成"已抓取 – 尚未编入索引"，其中某个二手页面的全部独有内容，是一个单词的标题加一个电话号码。四十这个数字是故意定低的，因为 484 条里有 471 条是韩语，而韩语单位字符承载的信息更多；按英语调的阈值会砍掉这个市场的一半。内容单薄的条目仍然通过索引页保持可抓取，一旦有人编辑就会自动重新进入站点地图。

我会从中带走的

#

• 在一个 URL 上返回不同的响应体，首先是一个缓存键问题。 弄清楚你的 CDN 用什么做键，并且在你于那个确切的内容类型上验证之前，就假定它忽略 Vary。
• 当两个系统必须就一份清单达成一致时，先弄清哪个方向的错误是安全的，然后把它写在两份副本旁边。“它们可以漂移，而且只允许朝这个方向漂”，胜过假装它们不会漂。
• 按机器人名字匹配机器人，永远别按厂商名字。 尤其在英语世界之外，那个厂商同时还做着你用户手里的那个浏览器。
• 把相距遥远的常量之间的不变式，放在会大声失败的地方。 import 时机是免费的，而且没人能跳过。

我目前以独立开发者的身份运营着两个产品：一个是面向上门报价的手艺人的现场估价应用，另一个是带有信息发布和实时消息的集市兼社区应用。

产品完全不同，用户完全不同，但技术栈几乎一模一样——而且两者都只跑在 Fly.io 最便宜的档位 shared-cpu-1x 机器上。这个约束是刻意为之的。与其按峰值负载来配置服务器，我选择把一台小机器的性能榨到极限，精确测出它在哪里崩溃，然后让 Fly 的自动扩缩容器围绕这个实测极限来增减机器。这篇文章讲的就是让这一切成为可能的优化、阈值背后的压测数据，以及 Fly.io 上扩容和缩容到底是怎么运作的。

理念：先测准一台机器，再做乘法

#

两个应用的扩缩容策略都是同样的三步：

1. 把一台小机器在合理范围内做到尽可能快。
2. 压测到它崩溃为止，记下延迟塌陷时的并发水平。
3. 配置 Fly 的自动扩缩容器，在临界点之前启动第二台机器，并在流量回落时停掉空闲机器。

这样容量就随机器数量近似线性增长，而基线成本是每个应用一台小虚拟机。下面的所有内容，都是为这三步中的某一步服务的。

让一台小机器变快

#

Granian：API 走 WSGI，WebSocket 走 uvloop ASGI

#

两个后端都是 Django 6 + Django REST Framework。API 由基于 Rust 的服务器 Granian 提供服务，但跑的是 带阻塞线程池的 WSGI，而不是 ASGI：

granian --interface wsgi myapp.wsgi:application \
    --workers 1 --blocking-threads 16 \
    --workers-max-rss 1400 \
    --workers-kill-timeout 15 --respawn-failed-workers

我最初用的是 --interface asgi --loop uvloop，事后看是选错了。这些应用里的每个 HTTP 视图都是同步（sync）的，而 Django 的 ASGI 处理器会以 thread_sensitive 方式跑同步视图——每个 worker（工作进程）一次只跑一个。于是 ASGI 把每个 worker 的并发请求实质压到约 1 个，却还把整套 asyncio/uvloop/Channels 栈白白装进内存。带 --blocking-threads 的 WSGI 则把这些同步视图放进一个真正的线程池：1 个 worker × 16 个线程 = 16 个并发的 I/O 密集型请求（数据库读取、S3 预签名），而常驻内存比异步栈更低。

为什么只用一个 worker？因为这台 VM 是 shared-cpu-1x——只有一个核。第二个 worker 在单核上没法并行跑 Python（GIL + 单核），却要白白多占一整个常驻的 Django 进程；Granian 会直接就此发出警告。一个 worker 配 16 个线程，就是单 vCPU 机器在 I/O 密集型工作上诚实的上限。--workers-max-rss 1400 会在 worker 越过内存上限时重启它，于是失控的 PDF 或图片任务会被回收，而不是把机器一路拖向 OOM。

WebSocket 被拆到了它自己的 Granian 进程里——一个用 uvloop 和 --ws 的 ASGI 应用，为长连接跑 1 个 worker。同步 API 完全不需要 ASGI 路径：当某个视图想往 socket 推送时，它会经由 Redis 调用 async_to_sync(channel_layer.group_send)，消息照样会跨进程送到 WebSocket 应用。两台服务器，各自跑自己真正擅长的接口。本地 Docker 也跑同样的 WSGI 线程池，因此测试时我的笔记本约等于一台生产机器。

热路径交给 Rust

#

只要 Python 热路径上存在 Rust 实现的替代品，我就用它：

• orjson（通过 drf-orjson-renderer）——所有 API 响应都经由 Rust 序列化，而不是标准库的 JSON 编码器。
• blurhash-rs——在上传时计算图片占位符。
• uuid-utils——Rust 实现的 UUID 生成。
• psycopg 3 (binary)——C 加速的 Postgres 驱动。

这些都不改变架构，只是抬高了一颗 vCPU 在需要第二台机器之前所能承受的上限。

消灭隐藏的延迟税

#

两个代码库里最大的一次性能提升不是算法，而是连接复用。在 Granian 的线程池下，每个新线程都会重新构建一个 boto3 的 S3 客户端，而每个返回照片或 PDF 的接口都在支付这笔开销。我写了一个小小的自定义存储类，改为按进程缓存客户端之后：

新线程上生成签名 URL 的耗时从 约 150ms 降到约 1ms。

同样的教训也适用于数据库：Fly 的 Postgres 位于 PgBouncer 之后，所以应用设置 conn_max_age=0，把连接复用交给连接池，并用 5 秒的 connect_timeout 快速失败，避免 worker 挂在失效的 SSL 连接上。

把缓存放在真正的瓶颈前面

#

压测社区市集时发现了一个值得记住的事实：天花板是 Postgres 连接数，而不是 CPU。浏览流量绝大多数是匿名的、用户之间完全相同，而在高负载下，这些相同的列表查询会在 CPU 闲置的同时把连接池打满。

解决办法是给匿名列表页加一层 Redis 缓存，用按命名空间的版本计数器做失效——一次写操作只需把一个计数器加一（O(1)，无需管理任何键），该资源的所有缓存页面立即失效。再用一个短 TTL 兜底。让浏览页面直接从 Redis 出去，真正的瓶颈就消失了，小机器可以把连接留给已登录的流量。

不要消息代理的后台任务

#

两个应用都用 django-tasks-db——Django 的数据库后端任务框架——而不是 Celery。一个独立的 db_worker 进程轮询数据库来处理任务：图片处理、PDF 生成、机器翻译、提醒推送。没有消息代理，没有需要额外估算容量和监控的服务，API 进程也永远不会被重活阻塞。这个 worker 甚至绕过 PgBouncer 直连 Postgres，因为长时间运行的任务和事务级连接池合不来。

内存：jemalloc 和交换空间缓冲

#

图片和 PDF 处理造成的内存尖峰，是按稳态估算内存时无法预测的。两个便宜的缓解手段：在 Docker 镜像里预加载 jemalloc 来减少内存碎片，以及给每台机器都配交换空间（API 机器 2GB，WebSocket 机器 1GB），这样尖峰来临时进程会把内存换出到磁盘，而不是被 OOM 杀掉。交换空间不是性能特性——它是一份保险，让我能把内存配置一直保持在小规格。

Django 压力测试：找到拐点

#

阈值只有在被实测过之后才站得住脚。每个项目都有自己的压测工具：

• 估价应用有一个小的 Python 压测脚本，扫描各个并发级别并报告 RPS、p50/p95/p99 和错误率；它跑在预先生成的几百条样例数据上，让列表接口在接近真实的数据量下被查询。
• 社区市集用 Locust 以 30 秒为步长从 50 爬升到 500 用户来寻找饱和点，接口权重按真实的浏览为主的流量设定；另有一套更小的独立测试，以 p95 < 2 秒为阈值，对生产环境从 5 爬升到 50 个虚拟用户。

估价应用扫描的代表性数据（1 个 Granian worker × 16 个阻塞线程，开发机上的 Docker）：

而决定其他一切的那个数字，来自在单台 shared-cpu-1x 机器上对社区市集的压测。在旧的 ASGI 构建里，这曾是一堵硬墙：同步视图被实质串行化到大约3 个可用槽位，于是 p95 在约 5 个并发请求以内保持在 300ms 以下，随后当一切都排在 thread_sensitive 锁后面时，超过约 8–10 个并发就塌陷。把拐点往外推的，正是把 API 迁到 WSGI 线程池这件事——每台机器的真实并发槽位从约 3 个变成了 16 个，而这个新的上限就是整个自动扩缩容配置的依据。

Fly.io 上的扩缩容是怎么运作的

#

Fly 的模型很简单：你的应用是代理后面的一组相同机器，代理统计每台机器的负载。你只需要声明两个数字：

[http_service.concurrency]
  type = 'requests'
  soft_limit = 12   # 超过就启动另一台机器
  hard_limit = 24   # 超过就直接卸载负载而不是排队

auto_stop_machines = 'stop'
auto_start_machines = true
min_machines_running = 1

**扩容：**当一台机器上的在途（in-flight）请求超过软上限（soft limit），代理会启动一台停止中的机器，并把新流量路由过去。WSGI 线程池让每台机器有 16 个真实并发槽位，所以软上限设为 12——约为池子的 75%，于是第二台机器会在线程还有余量时启动，而不是等用户已经在承受数秒延迟之后。硬上限 24（池子的 1.5 倍）是熔断器：短促的突发会在线程上排队，超过它，代理宁可卸载负载，也不让一台机器被压垮。（旧的 ASGI 构建只有约 3 个真实槽位，用的是 8/20；正是把池子拓宽，才让这两个数字都能往上调。）

**缩容：**流量回落时，Fly 自动停掉空闲机器，最低降到 min_machines_running = 1。停止的机器不产生计算费用，只收 rootfs 存储费，所以每个应用的基线成本就是字面意义上的一台小虚拟机，而突发容量随时待命。

我原本在这里写着，停止的机器"冷启动不到一秒"。这是错的，而且错得很贵。当我不再假设、真正去测量之后，一次冷启动要 25 到 33 秒，落到一台还在启动的机器上的请求，就得把这段时间整个等完。我一开始把 CDN 面板上 22% 的失败率归咎于这些冷启动，当时健康检查一直是绿的。后来才发现，那个数字是 CDN 自己的 Early Hints 探测请求在源站失败造成的，真实客户端一个 504 都没收到。不过冷启动本身确实存在。

解法不在上面的伸缩数字里，那些数字没问题。解法在于机器启动过程中做了什么，以及让 Fly 挂起机器而不是停止它们——那样唤醒就变成大约 3 秒的内存恢复。我单独写了一篇：缩容到零，于是每次重启都是一次 30 秒的故障 讲了诊断过程和该改什么。如果你在 Fly 上跑着任何用了 auto_stop_machines 的东西，先读那篇，再来相信这一段。

一个微妙之处：并发类型是 requests 而不是 connections。现代客户端会一直保持 keep-alive 连接，所以按连接数统计时数字在真实负载下几乎不动，自动扩缩容永远不会触发。统计在途请求，才能追踪真实的工作量。

WebSocket 在另一条轴上扩缩

#

社区市集把 WebSocket 服务器拆成了第二个 Fly 应用，与 API 共享同一个 Docker 镜像。API 应用用 WSGI 跑 1 个 worker × 16 个阻塞线程，按请求计数（软上限 12）；WebSocket 应用在一台 512MB 的机器上用 ASGI 配 uvloop 跑 1 个 worker，按连接计数：

[http_service.concurrency]
  type = 'connections'
  soft_limit = 1500
  hard_limit = 2000

一条长连接维持起来几乎零成本，却会占用一个槽位好几个小时；而一个 HTTP 请求只占用槽位几毫秒——同一个扩缩容信号无法同时服务两者。拆开之后，每个机群都按对自己诚实的指标扩缩，而空闲的 WebSocket 容量只花 512MB，不是 2GB。在 Channels 这一侧，Redis 层以 capacity: 1500、消息 60 秒过期运行，并每 30 秒发送 socket keepalive——因为 Fly 的 Redis 代理会把 Channels 赖以工作的长时间 BRPOP 连接当作空闲连接掐掉。

把计算卸载到边缘和客户端

#

最便宜的服务器工作，是服务器根本不用做的工作：

• 静态文件和媒体放在 Fly 的 S3 兼容对象存储上，私有媒体通过签名 URL 走 CDN 分发——图片的每一个字节都不经过 Django 机器。
• **AI 推理跑在用户的手机上。**两个应用都内嵌了一个小型本地 LLM（量化的 4B 模型，约 2.7GB），直接在设备上运行。服务端推理成本为零，而且离线也能用。
• 离线优先的移动端（设备上的 SQLite 加带重试的同步队列）意味着应用会把写操作攒批、容忍信号盲区，而不是每敲一个键就向 API 发一次琐碎请求。

其余的技术栈，简单说

#

认证用托管的身份服务加 WebAuthn 通行密钥（passkey），WebSocket 连接在协议升级完成前就完成认证。生产用 Postgres，开发用 SQLite。后台管理和审计记录用了几个现成的 Django 包。移动端是基于 Expo 的 React Native 和 TypeScript，配 Expo Router 和 Tailwind，OTA 更新由自托管的 Expo Updates 服务器下发，应用内订阅交给一个订阅管理服务。质量关卡：后端 pytest 和 mypy，客户端单元测试和端到端测试。

值得你拿走的东西

#

可迁移的想法不是某个具体的库，而是这个循环本身：把一台便宜机器做到真正的快（Rust 热路径、连接复用、在真正的瓶颈前面加缓存、能卸给 CDN 和客户端的都卸掉）；压测到找出它到底在哪个并发数崩溃；把自动扩缩容的软上限设在那个拐点上，让空闲机器停机，把最小机群保持在 1。两个生产应用、实时功能、AI 助手——而平时的账单，只是这个平台上最便宜的几台虚拟机。

我正在做的报价 App 有一条硬性要求：没信号也得能用。报价都是上门时在现场做的，而现场经常是毛坯房或者地下室，信号根本靠不住。正是这条约束，逼着我认真回答一个大多数 React 项目都含糊对付的问题：每种状态到底该放在哪里？

最常见的翻车方式，是把所有东西塞进同一个 store。API 缓存、用户偏好、表单状态、认证令牌，全搅在同一个 Redux 大泥球里。可这些状态的性质和生命周期各不相同，各有各的合适工具。Zustand、React Query、AsyncStorage 每个都恰好把一个问题解决得很好。边界画清楚了，架构基本就自己理顺了。

状态分三种

#

聊库之前，先弄清楚自己到底在管理什么。

客户端状态只存在于应用运行时：UI 开关、选中的标签页、表单输入、弹窗开没开。上游没有谁拥有它，进程一结束它就没了。

服务器状态不一样。它的主人是服务器，应用手里只有一份本地副本。用户资料、商品列表、通知、动态流。你的副本会过期，需要重新拉取，而且此刻别的客户端可能正看着另一个版本。

持久化状态是那些必须扛过重启的数据：认证令牌、引导完成标记、缓存的偏好、离线数据。它存在设备本身上。

大多数应用三种都有。大多数烂摊子，都是拿一个工具硬管三种状态造成的。

Zustand：管客户端状态

#

Zustand 是个没什么仪式感的小状态库。没有 provider，没有模板代码，没有一层套一层的 context。建个 store，组件里直接用，要学的基本就这些。

它适合的场景：多个组件共享同一份 UI 状态（侧边栏开关、当前筛选条件、选中的项目）；不来自 API 的应用级状态（主题、语言、启动时读的功能开关）；以及真正的客户端逻辑，比如购物车计算或多步表单向导。凡是需要同步、可预测地更新的，基本都归它。

一个基础的 store：

import { create } from 'zustand'

interface AppState {
  theme: 'light' | 'dark'
  sidebarOpen: boolean
  selectedFilters: string[]
  setTheme: (theme: 'light' | 'dark') => void
  toggleSidebar: () => void
  setFilters: (filters: string[]) => void
}

const useAppStore = create<AppState>((set) => ({
  theme: 'light',
  sidebarOpen: false,
  selectedFilters: [],
  setTheme: (theme) => set({ theme }),
  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
  setFilters: (filters) => set({ selectedFilters: filters }),
}))

组件里这样用：

function Sidebar() {
  const { sidebarOpen, toggleSidebar } = useAppStore()

  if (!sidebarOpen) return null

  return (
    <div className="sidebar">
      <button onClick={toggleSidebar}>Close</button>
      {/* sidebar content */}
    </div>
  )
}

我不往 Zustand 里放的东西

#

首先是 API 响应。我见过这样的项目：每次 API 调用都写进 Zustand store，组件不查询接口，改从 store 里读。结局就是自己手搓缓存失效、加载状态、错误处理、重新拉取和分页，而这些恰恰是 React Query 白送的。

其次是需要扛过重启的数据。Zustand 的状态在内存里，应用一关就没了。persist 中间件可以搭桥到 AsyncStorage（后面会讲），但那应该是想清楚之后的决定，而不是顺手为之。

React Query：管服务器状态

#

React Query（现在叫 TanStack Query）管理远程数据的整个生命周期：拉取、缓存、同步、更新、垃圾回收。关键的观念转变，是把服务器数据当成一份要保持新鲜的缓存，而不是你拥有的状态。数据的主人是服务器，你只是暂存了一份副本。

只要是 API 来的数据，我一律交给它。多个组件用同一个接口的数据（请求会自动去重）、分页和无限滚动、用户回到应用时需要后台刷新的数据、先改 UI 被服务器拒绝再回滚的乐观更新，全在它的射程之内。

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

function useUser(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(res => res.json()),
    staleTime: 5 * 60 * 1000, // 5 分钟内视为新鲜
  })
}

function useUpdateUser() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (data: { id: string; name: string }) =>
      fetch(`/api/users/${data.id}`, {
        method: 'PATCH',
        body: JSON.stringify(data),
      }),
    onSuccess: (_, variables) => {
      queryClient.invalidateQueries({ queryKey: ['user', variables.id] })
    },
  })
}

组件里：

function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, error } = useUser(userId)
  const updateUser = useUpdateUser()

  if (isLoading) return <Spinner />
  if (error) return <ErrorMessage error={error} />

  return (
    <div>
      <h1>{user.name}</h1>
      <button
        onClick={() => updateUser.mutate({ id: userId, name: 'New Name' })}
        disabled={updateUser.isPending}
      >
        Update Name
      </button>
    </div>
  )
}

不用自己写的那些东西

#

我坚持把服务器数据放这儿，就是因为白送的机制实在太多。五个组件请求同一个用户，网络请求只发一次。窗口重新聚焦或网络重连时自动重新拉取。过期缓存自动垃圾回收。每个查询都带着 isLoading、isError、data，加载和错误 UI 不用每次现做。失败的请求按指数退避自动重试。带回滚的乐观更新是内置模式，不用花一下午自己接管道。

它不适合干什么

#

纯客户端状态。数据压根不经过服务器的话，React Query 只会平添仪式感。弹窗的开关状态不需要缓存失效，也不需要重新拉取间隔。

它也不是持久化层。缓存在内存里，重启就清空、全部重拉。缓存可以持久化（React Native 上也确实应该做，见下面的离线部分），但数据的真实来源永远是服务器。

AsyncStorage：管扛过重启的数据

#

AsyncStorage 是 React Native 的键值存储。Web 上对应的是 localStorage（同步）或 IndexedDB（异步、能力更强）。思路都一样：写到设备上，让数据活得比进程久。

各平台底下是什么

#

用 @react-native-async-storage/async-storage 的话 API 只有一套，但底下的实现每个平台差别不小。

Android 上是走 RKStorage 的 SQLite，数据库放在应用内部存储目录里。快、可靠、有沙盒隔离，别的应用碰不到。不过要留意下表里的默认容量上限。

iOS 上，小值走 NSUserDefaults，大值走序列化文件，同样被沙盒在应用容器里。Apple 没给 NSUserDefaults 定硬上限，但单个值控制在几百 KB 以内是共识。真有那么大的值，八成该直接上 WatermelonDB 或 Realm 这种正经数据库了。

Web 上（React Native Web / Expo Web）会退回 localStorage，上限看浏览器，大概 5-10 MB。纯 Web 的 React 应用直接用 localStorage 就行，数据大了就通过 idb-keyval 这类封装用 IndexedDB。

我放进去的东西

#

认证令牌和会话数据、需要留下来的用户偏好（语言、主题、通知设置）、引导完成标记、离线用的缓存数据。一句话概括：需要扛过重启的小型键值数据，这个类别就这么大。

API 大概是存储方案里最朴素的样子：

import AsyncStorage from '@react-native-async-storage/async-storage'

// 存储一个值
await AsyncStorage.setItem('auth_token', token)

// 读取一个值
const token = await AsyncStorage.getItem('auth_token')

// 存储一个对象（需要序列化）
await AsyncStorage.setItem('user_preferences', JSON.stringify({
  theme: 'dark',
  language: 'en',
  notifications: true,
}))

// 读取一个对象
const prefs = JSON.parse(await AsyncStorage.getItem('user_preferences') ?? '{}')

// 删除一个值
await AsyncStorage.removeItem('auth_token')

// 清空所有数据（慎用）
await AsyncStorage.clear()

Web 上怎么办

#

纯 Web 的 React 应用完全不需要 AsyncStorage。简单键值对用 localStorage：

// 同步的 - 会阻塞主线程，但对于小数据没问题
localStorage.setItem('theme', 'dark')
const theme = localStorage.getItem('theme')

// 结构化数据
localStorage.setItem('user', JSON.stringify({ name: 'Jared', role: 'admin' }))
const user = JSON.parse(localStorage.getItem('user') ?? '{}')

数据集大了用 IndexedDB：

import { get, set, del } from 'idb-keyval'

await set('large-dataset', hugeArray)
const data = await get('large-dataset')
await del('large-dataset')

它不适合干什么

#

它是键值存储，不是数据库。关系型数据、几千上万条的数组、需要索引和查询的东西，归 SQLite（走 expo-sqlite）、WatermelonDB 或 Realm 管。

它也不是安全存储。设备一旦被 root 或越狱，AsyncStorage 里的内容就是明着放的。敏感令牌请放 expo-secure-store 或 react-native-keychain。

三个怎么搭配着用

#

真实的应用里三个是一起上的。几个我常用的搭配。

认证流程

#

// 1. AsyncStorage: 持久化认证令牌
import AsyncStorage from '@react-native-async-storage/async-storage'

async function saveToken(token: string) {
  await AsyncStorage.setItem('auth_token', token)
}

async function getToken(): Promise<string | null> {
  return AsyncStorage.getItem('auth_token')
}

// 2. Zustand: 在内存中跟踪认证状态
import { create } from 'zustand'

interface AuthState {
  isAuthenticated: boolean
  token: string | null
  setAuth: (token: string) => void
  clearAuth: () => void
}

const useAuthStore = create<AuthState>((set) => ({
  isAuthenticated: false,
  token: null,
  setAuth: (token) => set({ isAuthenticated: true, token }),
  clearAuth: () => set({ isAuthenticated: false, token: null }),
}))

// 3. React Query: 使用令牌获取用户资料
function useCurrentUser() {
  const token = useAuthStore((s) => s.token)

  return useQuery({
    queryKey: ['currentUser'],
    queryFn: () =>
      fetch('/api/me', {
        headers: { Authorization: `Bearer ${token}` },
      }).then(res => res.json()),
    enabled: !!token, // 只在有令牌时才发请求
  })
}

启动时：

// 应用初始化
async function initializeApp() {
  const token = await getToken() // 从 AsyncStorage 读取
  if (token) {
    useAuthStore.getState().setAuth(token) // 放入 Zustand 以便快速访问
    // React Query 会自动拉取用户资料
  }
}

AsyncStorage 负责让令牌扛过重启，Zustand 让它在任何地方都能低成本读到，React Query 则在令牌一就位时去拉用户资料。每个工具只干自己最擅长的那件事。

重启后还在的主题设置

#

import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
import AsyncStorage from '@react-native-async-storage/async-storage'

// Zustand 的持久化中间件在两者之间搭建了桥梁
const useThemeStore = create(
  persist(
    (set) => ({
      theme: 'light' as 'light' | 'dark',
      toggleTheme: () =>
        set((state) => ({
          theme: state.theme === 'light' ? 'dark' : 'light',
        })),
    }),
    {
      name: 'theme-storage',
      storage: createJSONStorage(() => AsyncStorage), // React Native
      // storage: createJSONStorage(() => localStorage), // Web
    }
  )
)

运行时状态归 Zustand 管，persist 中间件在背后同步到 AsyncStorage（Web 上是 localStorage）。组件既不知道也不需要知道持久化层的存在。

离线优先的读取

#

import { useQuery } from '@tanstack/react-query'
import AsyncStorage from '@react-native-async-storage/async-storage'

function useProducts() {
  return useQuery({
    queryKey: ['products'],
    queryFn: async () => {
      try {
        const res = await fetch('/api/products')
        const data = await res.json()

        // 缓存到 AsyncStorage 以供离线使用
        await AsyncStorage.setItem('cached_products', JSON.stringify(data))

        return data
      } catch (error) {
        // 网络请求失败 - 尝试使用缓存数据
        const cached = await AsyncStorage.getItem('cached_products')
        if (cached) return JSON.parse(cached)
        throw error
      }
    },
    staleTime: 10 * 60 * 1000,
  })
}

拉取和内存缓存归 React Query，断网时的兜底归 AsyncStorage，分工就这么简单。

离线模式，一步一步来

#

这部分才是我真正关心的。通常的说法是用户会在地铁、电梯、飞机上打开应用，这没错。但我的情况更直接：报价就是在现场写的，而现场有没有信号全看运气。地下室里转圈的加载动画，意味着丢掉一单报价。

好消息是，就靠这三个库，不用上重型框架也能搭出相当扎实的离线方案。

第一步：知道自己断网了

#

设备得把网络状态告诉应用，应用得有个地方存这个答案。事件由 @react-native-community/netinfo 提供，再用一个小小的 Zustand store 让全应用都能读到。

import { create } from 'zustand'
import NetInfo from '@react-native-community/netinfo'

interface NetworkState {
  isOnline: boolean
  setOnline: (online: boolean) => void
}

const useNetworkStore = create<NetworkState>((set) => ({
  isOnline: true,
  setOnline: (online) => set({ isOnline: online }),
}))

// 应用启动时订阅一次
NetInfo.addEventListener((state) => {
  useNetworkStore.getState().setOnline(state.isConnected ?? false)
})

之后任何组件都能通过 useNetworkStore((s) => s.isOnline) 来显示离线横幅、禁用提交按钮，或者提示“联网后会自动同步”。

第二步：把离线告诉 React Query

#

React Query 内置了 networkMode，控制断网时查询和变更的行为。

import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      networkMode: 'offlineFirst',
      // 先返回缓存数据，联网后在后台重新拉取
      staleTime: 5 * 60 * 1000,
      gcTime: 24 * 60 * 60 * 1000, // 缓存保留 24 小时
      retry: (failureCount, error) => {
        // 离线时不要重试 - 反正也会失败
        if (!useNetworkStore.getState().isOnline) return false
        return failureCount < 3
      },
    },
    mutations: {
      networkMode: 'offlineFirst',
    },
  },
})

三种模式：

大多数移动应用选 offlineFirst 就对了：缓存数据立刻出现，新数据等网络允许时再来。

第三步：持久化查询缓存

#

默认缓存只在内存里，一重启就满屏转圈。要做离线模式，得把缓存持久化到 AsyncStorage：

import { QueryClient } from '@tanstack/react-query'
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
import AsyncStorage from '@react-native-async-storage/async-storage'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 24 * 60 * 60 * 1000, // 24 小时 - 必须 >= maxAge
    },
  },
})

const asyncStoragePersister = createAsyncStoragePersister({
  storage: AsyncStorage,
  key: 'react-query-cache',
})

// 在你的 App 组件中
function App() {
  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{
        persister: asyncStoragePersister,
        maxAge: 24 * 60 * 60 * 1000, // 不恢复超过 24 小时的数据
        dehydrateOptions: {
          shouldDehydrateQuery: (query) => {
            // 只持久化成功的查询
            return query.state.status === 'success'
          },
        },
      }}
    >
      <YourApp />
    </PersistQueryClientProvider>
  )
}

这样在没信号的地方打开应用，看到的是上次拉取的数据而不是白屏；网络一恢复，React Query 就在后台悄悄重拉。

第四步：离线时把写操作排进队列

#

读是容易的那一半。有意思的是写：用户断网时发了评论、提交了订单、改了资料，这些变更得排队存好，等网络回来再重放。

React Query 的答案是 useMutation 加上 onMutate 里的乐观更新：

import { useMutation, useQueryClient } from '@tanstack/react-query'
import AsyncStorage from '@react-native-async-storage/async-storage'

interface Comment {
  id: string
  text: string
  postId: string
  createdAt: string
  pending?: boolean
}

function useAddComment(postId: string) {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: async (text: string) => {
      const res = await fetch(`/api/posts/${postId}/comments`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text }),
      })
      return res.json()
    },

    // 乐观更新 - 立即显示评论
    onMutate: async (text) => {
      await queryClient.cancelQueries({ queryKey: ['comments', postId] })

      const previous = queryClient.getQueryData<Comment[]>(['comments', postId])

      const optimisticComment: Comment = {
        id: `temp-${Date.now()}`,
        text,
        postId,
        createdAt: new Date().toISOString(),
        pending: true, // 在 UI 中显示"发送中..."的标识
      }

      queryClient.setQueryData<Comment[]>(
        ['comments', postId],
        (old) => [...(old ?? []), optimisticComment]
      )

      return { previous }
    },

    // 失败时回滚
    onError: (err, text, context) => {
      if (context?.previous) {
        queryClient.setQueryData(['comments', postId], context.previous)
      }
    },

    // 重新拉取以获取服务器的真实数据
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['comments', postId] })
    },
  })
}

给变更设置了 networkMode: 'offlineFirst' 之后，mutationFn 会暂停到网络恢复为止。乐观更新让评论立刻出现在屏幕上，真正的 API 调用在重连时才发出去。

如果需要更正经的队列，比如几十个待处理变更必须按顺序重放，还可以把变更队列本身也持久化：

import { MutationCache } from '@tanstack/react-query'

// 将待处理的变更保存到 AsyncStorage
const mutationCache = new MutationCache({
  onError: async (error, variables, context, mutation) => {
    // 记录失败的变更以便调试
    const pending = JSON.parse(
      await AsyncStorage.getItem('pending_mutations') ?? '[]'
    )
    pending.push({
      key: mutation.options.mutationKey,
      variables,
      timestamp: Date.now(),
    })
    await AsyncStorage.setItem('pending_mutations', JSON.stringify(pending))
  },
})

第五步：网络回来后对齐状态

#

重连的活儿 React Query 基本自己包了：暂停的变更恢复执行，过期的查询重新拉取。你要做的只是把它的管理器接到 React Native 的事件上。

import NetInfo from '@react-native-community/netinfo'
import { onlineManager, focusManager } from '@tanstack/react-query'
import { AppState } from 'react-native'

// 告诉 React Query 网络状态的变化
onlineManager.setEventListener((setOnline) => {
  return NetInfo.addEventListener((state) => {
    setOnline(!!state.isConnected)
  })
})

// 应用回到前台时重新拉取
focusManager.setEventListener((setFocused) => {
  const subscription = AppState.addEventListener('change', (status) => {
    setFocused(status === 'active')
  })
  return () => subscription.remove()
})

用户把应用切后台一小时再回来，focusManager 会触发重拉，让他们看到新数据；走出隧道信号恢复时，onlineManager 会把暂停的操作重新跑起来。

第六步：在 UI 上说清楚

#

无论如何，别把网络错误默默咽下去。要告诉用户现在离线了、哪些更改还在等待同步。

import { useNetworkStore } from './stores/network'

function OfflineBanner() {
  const isOnline = useNetworkStore((s) => s.isOnline)

  if (isOnline) return null

  return (
    <View style={styles.banner}>
      <Text>You're offline. Changes will sync when you reconnect.</Text>
    </View>
  )
}

function CommentItem({ comment }: { comment: Comment }) {
  return (
    <View style={[styles.comment, comment.pending && styles.pending]}>
      <Text>{comment.text}</Text>
      {comment.pending && (
        <Text style={styles.pendingLabel}>Sending...</Text>
      )}
    </View>
  )
}

整体架构

#

┌─────────────────────────────────────────────────┐
│                   Components                     │
│  useQuery() for reads    useMutation() for writes│
└──────────┬──────────────────────┬────────────────┘
           │                      │
     ┌─────▼──────┐        ┌─────▼──────┐
     │ React Query │        │ React Query │
     │   Cache     │        │  Mutation   │
     │ (in-memory) │        │   Queue     │
     └─────┬──────┘        └─────┬──────┘
           │                      │
     ┌─────▼──────────────────────▼──────┐
     │     AsyncStorage Persister         │
     │  (survives app restart)            │
     └─────┬──────────────────────┬──────┘
           │                      │
     ┌─────▼──────┐        ┌─────▼──────┐
     │   Zustand   │        │   Network  │
     │ (isOnline,  │◄───────│   NetInfo  │
     │  UI state)  │        │            │
     └────────────┘        └────────────┘

什么时候需要真正的同步引擎

#

上面这套的前提是：服务器是数据的真实来源，离线只是暂时状态。如果你要的是带冲突解决的真·离线优先，比如两台设备离线编辑同一篇笔记，这套就不够了，得上专门的同步引擎。WatermelonDB 专为 React Native 打造，底层是 SQLite，自带解决冲突的同步协议。Realm 配上 Atlas Device Sync，就是一个通过 MongoDB Atlas 自动解决冲突的完整离线优先数据库。PowerSync 是基于 SQLite 的同步层，能直接对接你现有的 Postgres 后端。要完全的控制权，也可以 Expo SQLite 加自己写同步逻辑。

Zustand + React Query + AsyncStorage 能覆盖大约 80% 的移动应用。剩下的 20%，也就是协同编辑、多设备同步、重度离线的工作流，需要专门的同步数据库。

拿不准放哪时

#

我拿不准的时候，会按这个顺序问自己：

常见场景

#

各平台安装

#

React Native (Android + iOS)

#

三个一起装：

npm install zustand @tanstack/react-query @react-native-async-storage/async-storage

敏感数据再加上安全存储：

npx expo install expo-secure-store
# 或者
npm install react-native-keychain

Expo

#

AsyncStorage 在 Expo 里开箱即用，不需要原生链接。

npx expo install @react-native-async-storage/async-storage

纯 Web React

#

跳过 AsyncStorage，直接用 localStorage 或 IndexedDB。

npm install zustand @tanstack/react-query
# 可选，用于 IndexedDB
npm install idb-keyval

Zustand 的 persist 中间件在 Web 上默认就用 localStorage：

persist(storeConfig, {
  name: 'my-store',
  // localStorage 在 Web 端是默认的 - 不需要额外配置
})

我反复见到的错误

#

把 API 数据塞进 Zustand。如果你的 action 里出现了 setUsers(apiResponse.users)，先停一下。那是 React Query 的活，再往前走一步，就是把缓存失效重新发明一遍，而且发明得不会太好。

用 React Query 管客户端状态。queryFn 里没有网络请求？工具用错了。

把 AsyncStorage 当数据库。往键值存储里序列化一万条记录的数组，结局不会体面。用数据库。

令牌不加密。AsyncStorage 不是安全存储。认证令牌、API 密钥、用户凭证，请放 expo-secure-store 或平台的 keychain。

手搓持久化。如果你在挂载时手动读 AsyncStorage、每次状态一变就手动写回去，Zustand 的 persist 中间件早就把这些连同水合、序列化一起做好了，代码更少，坑也更少。

服务器数据走 React Query。客户端状态放 Zustand。要扛过重启的进 AsyncStorage，敏感的进安全存储。

我经手过的最糟的架构，无一例外都是所有东西流经一个巨型 store。好的架构里，服务器状态、客户端状态、需要持久化的东西之间有清清楚楚的线。这些线画得越早，后面的一切就越省事。

2026 年 9 月 13 日更新。 这篇发出之后，Codemagic 发布了 Patch，一个 CodePush 路线的开源、可自托管 OTA 服务器。如果你是因为不想自己写服务器才找到这里的，它现在是一个实在的选项：我已经把一个应用从下面这套方案迁到了 Patch，并把过程写了下来，写在最后一节里也有一段简短说明。声明：那次迁移和那篇文章是 Codemagic 付费委托的，他们也希望在这里提一句。正文里的代码后来已精简为简短的示例。

我做的报价应用，bug 修复都是通过 OTA 推送的：JavaScript 改动不用等 App Store 审核，直接下发到用户手机上。Expo 官方的 EAS Update 本来就能做这件事，但我还是用 Django REST Framework 和 Tigris S3 自己搭了一套。从那以后，iOS 和 Android 的更新全都走这台服务器。

Expo 的 OTA 更新（也就是大家常说的热更新）是这样运作的：应用里的 expo-updates 库向更新服务器请求一份清单，请求头里带着自己的平台和运行时版本。服务器返回最新的兼容更新，以及这次更新的 JavaScript bundle 和资源文件的地址，应用把它们下载下来，下次启动时就跑新的 bundle。EAS Update 是 Expo 官方托管的一种实现，但任何实现了这套协议的服务器都能用，我自己搭的就是这样一台。

这篇文章把整个方案过一遍：数据模型、清单（manifest）接口、发布流水线，还有那些只有真正跑起来才会踩到的坑。

为什么要自己搭

#

对我来说主要是钱的问题。EAS Update 按用量计费，用户多了、更新频繁了，账单就跟着涨；而 Tigris 这类 S3 兼容存储几乎不要钱。当然还有别的理由：有些行业要求应用资产必须留在自己的基础设施里；服务器在自己手上，整个更新流程就都可控，想按用户群灰度、想做 bundle 的 A/B 测试都行。另外，更新链路也不再受 Expo 服务可用性或下一次调价的影响。

整体架构

#

一共四个部分：Django 后端负责下发更新清单、保存元数据；Tigris 存放 bundle 和资源文件本体；一个发布脚本负责导出、上传、登记更新；再加上移动应用本身，把更新地址指向我的服务器而不是 Expo 的。

┌─────────────────┐
│   Mobile App    │
│  (expo-updates) │
└────────┬────────┘
         │ 1. Request manifest
         │    (with headers: platform, runtime-version)
         ↓
┌─────────────────┐
│  Django Server  │
│  /api/expo-     │◄─── 2. Query DB for latest update
│   updates/      │
│   manifest/     │
└────────┬────────┘
         │ 3. Generate presigned URLs
         │
         ↓
┌─────────────────┐
│   Tigris S3     │
│  (Asset Files)  │◄─── 4. App downloads bundles directly
└─────────────────┘

具体实现

#

两个模型

#

一切都建立在 ExpoUpdate 和 ExpoUpdateAsset 之上。前者保存每次更新的元数据：

class ExpoUpdate(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    runtime_version = models.CharField(max_length=50, db_index=True)
    platform = models.CharField(
        max_length=10,
        choices=[("ios", "iOS"), ("android", "Android")],
        db_index=True
    )
    is_active = models.BooleanField(default=True, db_index=True)
    manifest_data = models.JSONField()
    description = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        indexes = [
            models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
        ]

这里有几个刻意的设计。runtime_version 对应 app.json 里的 runtimeVersion，客户端只会下载和自己运行时版本一致的更新，所以这个字段很关键。iOS 和 Android 的 bundle 不一样，所以分开存。is_active 是回滚开关：把有问题的更新停用，客户端就会退回上一个版本。manifest_data 直接把完整的 Expo Updates v1 协议清单存成 JSON，下发的时候取出来就行。

ExpoUpdateAsset 记录每个文件：

class ExpoUpdateAsset(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE, related_name="assets")
    hash = models.CharField(max_length=255, db_index=True)
    key = models.CharField(max_length=255)
    content_type = models.CharField(max_length=100)
    file_extension = models.CharField(max_length=10)
    file_path = models.CharField(max_length=500)
    file_size = models.IntegerField(default=0)

资源用 SHA-256 哈希来引用，天然不可变、好缓存，同一个资源可以被多次更新复用。

清单接口

#

应用和服务器真正打交道的地方是 /api/expo-updates/manifest/，实现的是 Expo Updates v1 协议：

@action(detail=False, methods=["get"], url_path="manifest")
def manifest(self, request):
    # Extract required headers
    protocol_version = request.META.get("HTTP_EXPO_PROTOCOL_VERSION")
    platform = request.META.get("HTTP_EXPO_PLATFORM")
    runtime_version = request.META.get("HTTP_EXPO_RUNTIME_VERSION")

    # Validate protocol version
    if protocol_version != "1":
        return Response(
            {"error": f"Unsupported protocol version: {protocol_version}"},
            status=400
        )

    # Find latest active update for this runtime + platform
    update = ExpoUpdate.objects.filter(
        runtime_version=runtime_version,
        platform=platform,
        is_active=True,
    ).order_by("-created_at").first()

    # No update available - client uses embedded bundle
    if not update:
        response = Response(status=204)
        response["expo-protocol-version"] = "1"
        return response

    # Generate presigned URLs for all assets
    manifest_data = build_manifest(update)  # fills in presigned asset URLs

    return Response(manifest_data, status=200)

有三个细节值得注意。没有更新时返回 204，应用会继续用内置的 bundle。清单里的资源地址是预签名 URL，应用直接从 Tigris 的 CDN 下载，不用整个流经 Django。响应头里的 expo-protocol-version 不能省，客户端真的会检查。

发布更新

#

发布靠一条 Django 管理命令，外面再包一层 shell 脚本。管理命令负责读取 expo export 的输出、给每个资源算 SHA-256 哈希、把 bundle 和资源并行传到 Tigris、写数据库记录，需要的话还会往桶里放一份用于生产同步的导入 JSON。精简到关键部分大致是这样：

from concurrent.futures import ThreadPoolExecutor

from django.db import transaction


def publish(platform, runtime_version, manifest, files):
    # Upload the bundle and assets in parallel (keys are content hashes)
    with ThreadPoolExecutor(max_workers=10) as executor:
        list(executor.map(upload_asset, files))

    # Swap the active update in one transaction
    with transaction.atomic():
        ExpoUpdate.objects.filter(
            runtime_version=runtime_version,
            platform=platform,
            is_active=True,
        ).update(is_active=False)

        return ExpoUpdate.objects.create(
            runtime_version=runtime_version,
            platform=platform,
            manifest_data=manifest,
        )

平时真正敲的是外面这层脚本：

# Publish to local environment
./publish.sh ios

# Publish to production
./publish.sh ios --production

# Dry run to validate
./publish.sh --dry-run

它会在导出前加载生产环境变量，平台可以只发一个也可以两个都发，还顺带处理下一节要讲的生产同步。

同步到生产环境

#

我不想把生产环境的凭证放在自己笔记本上，所以生产发布分两步：先在本地发布（资源传到 Tigris，同时生成一份元数据的 JSON 快照），再带着 S3 路径调用生产环境的 API，让服务器自己把元数据导进去：

@action(detail=False, methods=["post"], url_path="import-update")
def import_update(self, request):
    # Authenticate via Bearer token
    token = request.META.get("HTTP_AUTHORIZATION", "").removeprefix("Bearer ")
    if not hmac.compare_digest(token, settings.IMPORT_TOKEN):
        return Response({"error": "Invalid token"}, status=401)

    # Download the import JSON from the bucket
    s3_key = request.data.get("s3_key")
    obj = s3_client.get_object(Bucket=bucket_name, Key=s3_key)
    data = json.loads(obj["Body"].read())

    # Import into the production database
    with transaction.atomic():
        update, _ = ExpoUpdate.objects.update_or_create(id=data["id"], defaults={...})
        for asset_data in data["assets"]:
            ExpoUpdateAsset.objects.update_or_create(...)

    # Clean up the import JSON
    s3_client.delete_object(Bucket=bucket_name, Key=s3_key)
    return Response({"update_id": str(update.id)})

让应用指向自己的服务器

#

在 app.json 里配置更新地址和运行时版本：

{
  "expo": {
    "runtimeVersion": "1.0.0",
    "updates": {
      "url": "https://api.example.com/api/expo-updates/manifest/"
    }
  }
}

runtimeVersion 必须在应用和服务器之间严格对齐。改了原生代码或者升级了 Expo SDK，就把运行时版本加一，然后针对新版本重新发布更新。

Tigris 存储

#

Tigris 是 S3 兼容的对象存储，比 AWS S3 便宜得多，还自带全球边缘缓存。考虑到用户要下载好几 MB 的 bundle，这一点很实在。Django 侧的配置：

# settings.py
BUCKET_NAME = os.getenv("BUCKET_NAME")
AWS_ENDPOINT_URL_S3 = os.getenv("AWS_ENDPOINT_URL_S3")
AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
AWS_REGION = os.getenv("AWS_REGION", "auto")

客户端就是普通的 boto3：

import boto3

def create_s3_client(endpoint_url, region, access_key, secret_key):
    return boto3.client(
        "s3",
        endpoint_url=endpoint_url,
        region_name=region,
        aws_access_key_id=access_key,
        aws_secret_access_key=secret_key,
    )

下载走预签名 URL，应用直接从 CDN 拉取：

presigned_url = s3_client.generate_presigned_url(
    "get_object",
    Params={"Bucket": bucket_name, "Key": asset.file_path},
    ExpiresIn=3600,  # 1 hour
)

安全

#

清单接口是故意不做鉴权的，因为应用在用户登录之前就需要拿更新。导入接口则完全不同：它能写生产数据库，所以要求共享密钥，并用常数时间比较来防时序攻击：

IMPORT_TOKEN = os.getenv("IMPORT_TOKEN")

# Constant-time comparison prevents timing attacks
if not hmac.compare_digest(token, IMPORT_TOKEN):
    return Response({"error": "Invalid token"}, status=401)

资源完整性是这套设计白送的：所有资源都按 SHA-256 哈希校验，被篡改的资源直接失败。预签名 URL 一小时过期，bundle 也就不会被长期盗链。

性能

#

(runtime_version, platform, is_active, -created_at) 这个联合索引保证清单查询不会随着更新数量增长变慢：

class Meta:
    indexes = [
        models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
    ]

发布脚本用线程池并行上传资源：

with ThreadPoolExecutor(max_workers=10) as executor:
    futures = {executor.submit(upload_asset, asset): asset for asset in assets}
    for future in as_completed(futures):
        # Track progress

以一次 50 个资源左右的典型更新为例，发布时间从大约 2 分钟缩到了 15 秒。分发这边什么都不用做，Tigris 会自动把资源缓存到离用户近的边缘节点。

日常流程

#

开发时

#

# 1. Make code changes in the app
git commit -am "Fix bug"

# 2. Publish OTA update to local environment
./publish.sh ios

# 3. Test on device
# App automatically downloads and applies update

发布到生产

#

# 1. Publish to production
./publish.sh ios --production

# 2. Monitor
# Check Django admin for update records
# Verify assets in Tigris dashboard

回滚

#

# Mark problematic update as inactive in Django admin
# or via management shell:
python manage.py shell

>>> from updates.models import ExpoUpdate
>>> bad_update = ExpoUpdate.objects.get(id="uuid-here")
>>> bad_update.is_active = False
>>> bad_update.save()

# Clients will now receive the previous active update

成本

#

这个应用大约有 500 个活跃用户。Tigris 上，约 200 MB 的历史更新每月大概 0.02 美元，更新下载带来的每月约 50 GB 流出流量大概 1 美元。Django 这边跑在原本就承载 API 的服务器上，没有额外成本。加起来每月一美元左右。同样的用量放到 EAS Update 上，一年大概要 300 到 500 美元，所以这套东西基本上立刻就回本了。

监控与调试

#

没什么花哨的。ViewSet 会把每个清单请求记进日志：

logger.info(f"Manifest request: platform={platform}, runtime={runtime_version}")

Django admin 就是事实上的控制台，把模型注册进去，查看、筛选都很方便：

@admin.register(ExpoUpdate)
class ExpoUpdateAdmin(admin.ModelAdmin):
    list_display = ["platform", "runtime_version", "is_active", "created_at"]
    list_filter = ["platform", "is_active", "runtime_version"]
    search_fields = ["description"]

客户端这边，expo-updates 会告诉你它看到了什么：

import * as Updates from 'expo-updates';

Updates.checkForUpdateAsync().then(update => {
  console.log('Update available:', update.isAvailable);
  console.log('Manifest:', update.manifest);
});

踩过的坑

#

运行时版本不匹配

#

最常见的故障也最安静：客户端只下载和自己运行时版本一致的更新。装机版本还在 1.0.0，你却按 1.0.1 发布，那就什么都收不到，也没有任何报错。运行时版本要和构建保持同步，只在原生代码变化时才递增。

createdAt 时间戳

#

expo-updates 客户端会拿清单的 createdAt 和内置 bundle 的 commitTime 比较，只有 createdAt 更新的才会被应用。ViewSet 里用数据库时间戳覆盖它：

manifest_data["createdAt"] = update.created_at.strftime("%Y-%m-%dT%H:%M:%S.%fZ")

本地开发时，如果你在发布 OTA 之后又构建了二进制包，就重新发布一次 OTA，保证时间戳更新。

清单里的资源 key

#

清单中每个资源的 key 字段是 expo-updates 用来做缓存的，它必须是确定性哈希（比如文件名的 MD5），不能是随机 UUID 或随便一个字符串。搞错了，客户端可能无法正确缓存和读取资源，更新会在第一次成功加载之后悄悄失效。感谢读者 Raphael Mutschler 指出这个问题。在找到原因之前，他的更新恰好只成功过一次。

expoClient 里的应用配置

#

如果应用用到 Linking、Constants 或其他在运行时读取应用配置的东西，清单的 extra.expoClient 字段里就必须带上应用配置。少了它，应用第一次可能启动正常，关掉之后再打开就崩溃或干脆打不开。原因是 expo-updates 会用 OTA 的清单替换内置清单，expoClient 一缺，这些 API 依赖的配置就没了。这个坑也是 Raphael Mutschler 发现的。

清理旧资源

#

旧更新会在 Tigris 里越积越多。目前我还是手动清理：

# Delete updates older than 30 days
from datetime import timedelta
from django.utils import timezone

cutoff = timezone.now() - timedelta(days=30)
old_updates = ExpoUpdate.objects.filter(created_at__lt=cutoff, is_active=False)

for update in old_updates:
    # Delete assets from S3
    for asset in update.assets.all():
        s3_client.delete_object(Bucket=bucket_name, Key=asset.file_path)
    # Delete DB records
    update.delete()

按理说应该放进定时任务，我还没顾上。

接下来想加的

#

（2026 年 9 月：这三样 Patch 现在都有了，还不止，见迁移记录。）

灰度发布

#

加一个 rollout_percentage 字段，就能先放量给一部分用户：

rollout_percentage = models.IntegerField(default=100)

# In the manifest view:
if update.rollout_percentage < 100:
    # Hash user ID and check if they're in rollout group
    user_hash = int(hashlib.sha256(user_id.encode()).hexdigest(), 16)
    if (user_hash % 100) >= update.rollout_percentage:
        return Response(status=204)  # No update

区分预发环境

#

加一个 environment 字段，预发构建和生产就能收到不同的更新：

environment = models.CharField(max_length=20, default="production")

# Client sends environment in custom header
environment = request.META.get("HTTP_X_UPDATE_ENVIRONMENT", "production")
update = ExpoUpdate.objects.filter(environment=environment, ...).first()

下载统计

#

再加一个小模型，就能认真回答“这次更新到底有没有人收到”：

class ExpoUpdateDownload(models.Model):
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE)
    user_id = models.CharField(max_length=255, null=True)
    platform = models.CharField(max_length=10)
    downloaded_at = models.DateTimeField(auto_now_add=True)

写在最后

#

整套系统就是两个 Django 模型、几个视图、一个发布脚本，外加每月一美元的基础设施。比我动手前预想的要小，而且从那以后一直安安静静地支撑着这个应用的两个平台。

上面的代码是从那个生产应用简化出来的示例，按自己的项目改改就能用。读者 Raphael Mutschler 还发布了一个独立实现 expo-ota-server，想从能直接跑的代码开始的话可以去看看。

如果你不想自己写服务器

#

这篇写完之后出现了两样东西，不用 Django 也能覆盖同样的地盘。第一个是上面提到的 Raphael 的 expo-ota-server。第二个是 Codemagic Patch：开源，通过 Docker Compose 安装跑在你自己的机器上，走的是 CodePush 协议而不是 Expo Updates 协议，所以你要把 expo-updates 换成它的 SDK，把 eas update 换成 cmpatch release-react。它能用 S3 兼容存储，所以本文这样的 Tigris 桶也照样能用。

它开箱就带着我在“接下来想加的”里列出来、却一直没做的那些：Staging 和 Production 两套 deployment、按百分比灰度、每个 release 的下载和安装数字、强制更新、二进制 patch、代码签名，以及新 bundle 在应用报告就绪之前崩溃时设备端的回滚。代价是，在任何人收到 Patch 更新之前先要发一个新的原生二进制，因为 SDK 得进到应用里；还有一台要跑的服务器，取代了一条管理命令。

我把自己的一个应用，连同已提交的原生工程和真实的发布流水线，从本文这套方案迁到了 Patch。那篇记录写了哪些顺利、哪些不顺，以及到底有多难。Codemagic 赞助了那项工作，并对它做了一轮事实审阅，不是编辑审阅。

完整规范见 Expo Updates Protocol Specification。

这篇文章讲讲我是怎么用 llama.rn（llama.cpp 的 React Native 绑定）和 Qwen 1.7B 把它做出来的。这个尺寸的模型，能干的活比我预想的多得多。

简单来说：装上 llama.rn，应用第一次打开时下载一个 4 位量化的 GGUF 模型（1 GB 左右），用 initLlama 加载，然后流式生成就行。在 iPhone 14 Pro 上，完全不联网也能跑到每秒 15 个 token 左右。这篇剩下的内容，讲的是让它真正派上用场花了哪些功夫：选模型，让它稳定地吐出工具调用，还有把内存控制住。

📝 更新： 现在的实现已经换成 Qwen3.5-2B-GGUF，替代了最初的 Qwen3-1.7B。另外我也不再用 /no_think 消息这种土办法，改用 chat_template_kwargs 参数正式关闭思考模式：

chat_response = client.chat.completions.create(
    model="Qwen/Qwen3.5-27B",
    messages=messages,
    max_tokens=32768,
    temperature=0.7,
    top_p=0.8,
    presence_penalty=1.5,
    extra_body={
        "top_k": 20,
        "chat_template_kwargs": {"enable_thinking": False},
    },
)

比在提示词里塞开关干净多了。

我为什么不想用云端 AI

#

移动应用里的 AI 功能，套路基本一样：用户输入消息，应用发给云端的模型服务商，响应回来，账单往上涨。

但这是一个施工商家拿来做生意的应用。照这个套路走，客户的姓名、地址、电话就交给了第三方，项目细节、报价、备注躺在别人的服务器上，还得操心 GDPR 和数据驻留这些我根本不想碰的问题。API 账单也随着用户数一路上涨。

另一条路是把模型直接放到用户手机上跑。我选了这条。

为什么现在做得成了

#

放在一年前我不会碰这个，但有三件事几乎同时起了变化。一是量化模型变小了：Q4_K_M 量化后的 Qwen 1.7B 只有 1.1 GB，比大多数游戏还小，下载一次就常驻应用存储。二是手机 GPU 够快了：llama.cpp 在 iOS 上走 Metal，在搭载较新高通 GPU 的 Android 手机上走 OpenCL，iPhone 14 Pro 能跑到每秒 15 个 token 左右，实时流式输出绰绰有余。三是小模型真的能用了：Qwen 1.7B 能遵循结构化指令、解析 JSON、串起多步推理。业务逻辑要的正是这些能力，又没人指望它写诗。

选模型

#

定下 Qwen3-1.7B 之前，我试了四个小模型。

TinyLlama 1.1B（637 MB）最快，但结构化输出始终不稳，动不动就编造客户 ID、漏掉必填字段。Phi-3-mini（1.8 GB）推理不错，可惜话太多，20 个字能说清的事非要写 200 字的小作文。Gemma-2B（1.2 GB）做分类又快又准，但函数调用不行，我的工具系统需要的 <action> 标签它输出不稳定。Qwen3-1.7B（1.1 GB）正好卡在甜点位：结构化输出可靠，指令遵循精确，还支持用 <think> 标签做思维链。

Q4_K_M 是 llama.cpp 的 k-quant 量化格式之一：权重按块存成 4 位数值，每一块带着自己的缩放系数，M 这一档还会把少数几个敏感的张量保留在 6 位。这样文件比 16 位权重小约 70%，质量只损失一点点。

配置 llama.rn

#

llama.rn 把 llama.cpp 封装给 React Native 用，安装是整件事里最简单的部分：

npm install llama.rn
cd ios && pod install

用 Expo 的话，llama.rn 是原生模块，在 Expo Go 里跑不起来。要加上它的 config plugin，改用 development build：

// app.config.js
export default {
  expo: {
    plugins: ["llama.rn"],
  },
};

npx expo install llama.rn
npx expo run:ios

打生产包时，这个插件还会顺手加上 llama.rn 为大模型推荐的两项 iOS entitlement（Extended Virtual Addressing 和 Increased Memory Limit，也就是扩展虚拟寻址和提高内存上限）。

模型本体在首次使用时下载：

const MODEL_URL = "https://huggingface.co/unsloth/Qwen3-1.7B-GGUF/resolve/main/Qwen3-1.7B-Q4_K_M.gguf";
const MODEL_PATH = FileSystem.documentDirectory + "llama-models/Qwen3-1.7B-Q4_K_M.gguf";

const downloadModel = async () => {
  const downloadResumable = FileSystem.createDownloadResumable(
    MODEL_URL,
    MODEL_PATH,
    {},
    (progress) => {
      const pct = progress.totalBytesWritten / progress.totalBytesExpectedToWrite;
      setDownloadProgress(pct);
    }
  );

  await downloadResumable.downloadAsync();
};

WiFi 下两三分钟，LTE 大概五到八分钟。下载完成后，开着 GPU 加速加载：

const ctx = await initLlama({
  model: MODEL_PATH,
  n_ctx: 8192,      // 8K context window
  n_gpu_layers: 99, // Use GPU for all layers
});

n_gpu_layers: 99 千万别省。把计算从 CPU 挪到 Metal 或 OpenCL 上，速度能提 5 倍左右。

流式推理

#

没人愿意盯着加载动画看十秒钟，所以响应按 token 逐个流出：

let fullResponse = "";

await llamaContext.completion(
  {
    messages: [
      { role: "system", content: systemPrompt },
      { role: "user", content: "Create a job for John Smith" }
    ],
    n_predict: 512,
    temperature: 0.7,
    top_p: 0.8,
  },
  (data) => {
    // Called for each token
    fullResponse += data.token;
    setStreamingText(fullResponse);
  }
);

在近几年的手机上，首个 token 约 200ms（这是提示词处理的时间），之后每个 token 50-80ms。跟走网络的 API 一比，体感就是即时的。

小模型也玩得转的函数调用

#

大型云端模型那套函数调用靠 JSON schema，小模型在这里会栽跟头：JSON 格式坏掉、必填字段丢失。所以我用了个更简单的 XML 协议：

const systemPrompt = `You are an AI assistant. When you need to take an action, output:
<action>{"type":"search_customers","query":"Smith"}</action>

Available actions:
- search_customers: {"type":"search_customers","query":"John"}
- create_job: {"type":"create_job","customer_id":5,"alias":"Living Room"}
- update_job: {"type":"update_job","job_id":"J-0042","status":"quoting"}

Rules:
1. ONE action tag per response, at the very end
2. When searching/creating → end with <action>
3. When just chatting → no action tag
`;

选 XML 标签的理由都很朴素：<action> 和 </action> 的起止毫不含糊，解析只要一条正则，提示词里的示例本身就是格式说明，而且就算模型在标签前后多说几句废话也不影响。

解析代码简单到不好意思展示：

function parseAction(text: string): Action | null {
  const match = text.match(/<action>([\s\S]*?)<\/action>/);
  if (!match) return null;

  try {
    return JSON.parse(match[1].trim());
  } catch {
    return null;
  }
}

解析出 action 就执行，再把结果塞回对话里：

const action = parseAction(modelResponse);
if (action) {
  const result = await executeAction(action);

  // Inject result as a system message
  conversationHistory.push({
    role: "user",
    content: `[TOOL_RESULT] ${result.message}\n\n→ NEXT: Tell the user what happened.`
  });

  // Continue generation
  await generateNextResponse();
}

就这么点东西，多步工作流已经能顺畅跑起来了：

用户：“Create a job for Smith”

1. 模型：<action>{"type":"search_customers","query":"Smith"}</action>
2. 系统：[TOOL_RESULT] Found: Jane Smith (id:42), Bob Smith (id:89)
3. 模型：“找到两位 Smith：Jane 和 Bob。您要哪一位？”
4. 用户：“Jane”
5. 模型：<action>{"type":"create_job","customer_id":42}</action>
6. 系统：[TOOL_RESULT] Job J-0073 created
7. 模型：“完成！已为 Jane Smith 创建工作单 J-0073。”

用 <think> 标签做思维链

#

让小模型把推理"说出来"，稳定性会肉眼可见地提高。Qwen 自带思考模式：

const systemPrompt = `Before each response, wrap your reasoning in <think> tags:

<think>
INTENT: what does the user want?
HAVE: what data do I already have?
NEED: what's still missing?
DECISION: call tool | ask user | just respond
</think>

Then output your actual response.`;

模型内部大概是这样运转的：

<think>
INTENT: create a job
HAVE: customer query "Smith"
NEED: exact customer_id
DECISION: search first
</think>
<action>{"type":"search_customers","query":"Smith"}</action>

<think> 标签在进 UI 之前会被剥掉，开发阶段我会留着它们调试。效果非常明显：模型会先把逻辑捋顺，再决定动手。

把长对话塞进 8K 上下文

#

工具结果一多，8K 上下文窗口比想象中满得快。我这边大约 30 轮就顶到上限了。

我的办法是对话压缩，让模型自己总结自己：

const compactPrompt = `Summarize this conversation in under 200 words.
Include: user's goal, customers/jobs created (with IDs), and any unfinished tasks.

${conversationHistory.map(m => `${m.role}: ${m.content}`).join('\n\n')}`;

const summary = await chat([{ role: "user", content: compactPrompt }]);

// Replace history with summary
conversationHistory = [
  { role: "user", content: `[CONTEXT SUMMARY]\n${summary}\n[END SUMMARY]` }
];

50 条消息的对话能压到 150 个 token 左右，模型接着聊，也不会忘记之前建了哪些工作单、客户 ID 是多少。

会话保存

#

聊天会话也会存到应用的后端。值得借鉴的一点是：每条助手消息存两份，一份清理过、用于显示，一份保留 <think> 和 <action> 标签的原文。这样聊天记录在界面上回放时干干净净，恢复会话时又能拿回包含 action 在内的完整上下文。用户可以像用一般的聊天应用那样，在历史下拉菜单里切换对话。

生产环境的性能数据

#

iPhone 14 Pro（A16 Bionic，6GB RAM）：

• 模型加载：约 3 秒
• 首个 token：180-220ms
• 流式输出：14-16 tokens/秒
• 内存：约 1.8 GB

Samsung Galaxy S23（Snapdragon 8 Gen 2，8GB RAM）：

• 模型加载：约 4 秒
• 首个 token：250-300ms
• 流式输出：10-12 tokens/秒
• 内存：约 2.1 GB

iPhone 11（A13，4GB RAM）：

• 模型加载：约 6 秒
• 首个 token：400-500ms
• 流式输出：6-8 tokens/秒
• 内存：约 2.2 GB（内存吃紧时偶尔崩溃）

我的经验值：想用得顺畅，RAM 至少 6GB。4GB 也能跑，但应用退到后台时多半得把模型卸载掉。

内存管理

#

应用占着太多内存，iOS 会毫不客气地把它杀掉，所以一离开前台我就释放模型：

useEffect(() => {
  const subscription = AppState.addEventListener("change", (nextAppState) => {
    if (nextAppState === "background") {
      llamaContext?.release(); // Free ~2 GB
    } else if (nextAppState === "active") {
      loadModel(); // Reload when foregrounded
    }
  });

  return () => subscription.remove();
}, []);