<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Mobile Development · 仁才德</title>
    <link>https://jared.lynskey.co.nz/zh-cn/tags/mobile-development/</link>
    <description>关于软件工程与研发团队领导力的短文——绩效评估、招聘与团队扩张、CI/CD、DevOps 监控、智能体 AI。写于首尔。</description>
    <generator>Hugo</generator>
    <language>zh-CN</language>
    <copyright>© 2026 仁才德</copyright>
    <lastBuildDate>Sun, 15 Nov 2026 18:30:53 +0900</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/zh-cn/tags/mobile-development/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>用 Cloudflare WARP 做内网穿透：把笔记本、手机和工作站连成一个私有网络</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-10-01-cloudflare-warp-dev-network/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-10-01-cloudflare-warp-dev-network/</guid>
      <pubDate>Thu, 01 Oct 2026 00:00:00 +1200</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Cloudflare</category>
      <category>WARP</category>
      <category>Zero Trust</category>
      <category>Cloudflare Tunnel</category>
      <category>Networking</category>
      <category>SSH</category>
      <category>DevOps</category>
      <category>AI Agents</category>
      <category>Ollama</category>
      <category>Mobile Development</category>
      <category>IPv6</category>
      <description>我用 Cloudflare WARP 加两条 Cloudflare Tunnel（Zero Trust），把笔记本、连着 5G 的手机和办公室里的 GPU 工作站放进同一个私有网络：固定的私有 IP，不开任何端口，dev server 挂在 Access 后面。</description>
      <content:encoded><![CDATA[<p>Cloudflare WARP 能把你自己的几台机器放进同一个私有网络，一个端口都不用开。在每台想访问的机器上跑一条 Cloudflare Tunnel（<code>cloudflared</code>），让每条隧道各自通告一个私有 IP 网段，再用 WARP 客户端把笔记本和手机注册进一个 Zero Trust 组织，split tunnel 设成 include 模式。之后，连着 5G 的手机直接连 <code>198.18.42.2</code>，就能落到办公室里的那台工作站上。下面是我的具体配置，以及路上踩过的四个坑。</p>
<p>我的工作环境是三台很少待在同一个地方的设备。一台 MacBook Air，我去哪它去哪。一台放在办公室、叫 devbox 的工作站，有块像样的 GPU，上面跑着 Ollama、几样微调工具、一个自带容器镜像仓库的小 Kubernetes 集群，还有我丢在那儿慢慢啃长任务的某个 agent。再就是我的手机：我做的应用真正被使用的地方就是它，而它一天里大部分时间连的是移动数据，不是 wifi。</p>
<p>很长一段时间里，这三台设备之间基本不通。笔记本在办公室局域网里能连上 devbox，出了办公室就不行。手机和笔记本连着同一个 wifi 时，能访问笔记本上的 dev server，前提是我记得绑定 <code>0.0.0.0</code>，还得手动敲进 DHCP 那天早上分给 Mac 的地址。工作站上所有有意思的东西，Ollama API、集群的仪表盘、链路追踪、镜像仓库，都绑在 localhost 或集群网络上，这是故意的，因为它们都不该出现在公网上。</p>
<p>这篇文章讲我怎么用 Cloudflare WARP 和两条 Cloudflare Tunnel 把它们连起来，这对我做 AI 功能和移动应用的方式带来了什么变化，还有那几个坏了却一声不吭的地方。</p>

<h2 class="relative group">我真正想要的
    <div id="我真正想要的" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e7%9c%9f%e6%ad%a3%e6%83%b3%e8%a6%81%e7%9a%84" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>写成需求的话，很短：</p>
<ol>
<li>笔记本应该是个瘦客户端。凡是需要 GPU、大量内存或者要跑几个小时的东西，都应该在 devbox 上跑，而笔记本无论在办公室、在家还是在咖啡馆，都用同一种方式连过去。</li>
<li>手机应该能在任何地方、用移动数据访问我的 dev server 和 shell，而且不需要一个我得记着开关的 VPN。</li>
<li>我用来观察系统运行状态的东西，仪表盘、链路追踪、<code>docker info</code>、模型列表，应该只有我能访问，而且永远不该有公网 URL。</li>
<li>不开入站端口。办公室路由器不开，家里路由器不开，哪儿都不开。</li>
</ol>
<p>第四条排除了老办法，也就是端口转发加动态 DNS。它也排除了很多取巧的方案：devbox 和笔记本都在我控制不了的 NAT 后面，而笔记本每隔几小时就换一个 NAT。</p>

<h2 class="relative group">之前：一个装满 SSH 隧道的仓库
    <div id="之前一个装满-ssh-隧道的仓库" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b9%8b%e5%89%8d%e4%b8%80%e4%b8%aa%e8%a3%85%e6%bb%a1-ssh-%e9%9a%a7%e9%81%93%e7%9a%84%e4%bb%93%e5%ba%93" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>最早的版本是我自己写的一个小仓库，到现在它仍然是底层。它在笔记本上只解决一个问题：给通过 SSH 访问的东西起干净的名字，别的不管。dnsmasq 把 <code>*.test</code> 解析到 <code>127.0.0.1</code>，Caddy 按主机名路由到本地端口，用 <code>tls internal</code> 让浏览器满意，再由一组 autossh launch agent 保持 SSH 转发开着，断了就重连。主机名本身说明了东西在哪儿：</p>
<table>
	<thead>
			<tr>
					<th>后缀</th>
					<th>含义</th>
					<th>承载方式</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>*.local.test</code></td>
					<td>这台 Mac</td>
					<td>无，就是个 dev server</td>
			</tr>
			<tr>
					<td><code>*.ssh.test</code></td>
					<td>某台服务器</td>
					<td>一条 autossh 转发</td>
			</tr>
			<tr>
					<td><code>*.cloud.test</code></td>
					<td>托管在云上的应用</td>
					<td>托管平台自带的代理</td>
			</tr>
	</tbody>
</table>
<p>所以 <code>https://devbox-ollama.ssh.test/api/tags</code> 列出的是工作站上的模型，<code>https://api.local.test</code> 是我手上在做的那个应用的 API，跑在我自己的机器上。</p>
<p>用的是 <code>.test</code> 的子域名，而不是 <code>.ssh</code>、<code>.cloud</code> 这样新造的顶级域，也不是 <code>.local</code>。RFC 6761 把 <code>.test</code> 专门保留给这种用途，而 <code>.local</code> 归 mDNS 所有；占用它的话，Mac 上的 Bonjour 发现就会失效。dnsmasq 本来就通配了整个 <code>*.test</code>，所以多一级标签不花任何成本：一个指向 <code>127.0.0.1</code> 的 <code>/etc/resolver/test</code> 文件，此后再也不用改 DNS。</p>

<h3 class="relative group">给不存在的域名上 HTTPS
    <div id="给不存在的域名上-https" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%bb%99%e4%b8%8d%e5%ad%98%e5%9c%a8%e7%9a%84%e5%9f%9f%e5%90%8d%e4%b8%8a-https" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>这些名字全都走 HTTPS，证书浏览器也信任，对一个只存在于我笔记本上的主机名来说，这听起来不太可能。Caddy 靠它自带的内部证书颁发机构做到这一点。在某个站点上写 <code>tls internal</code>，Caddy 就会用本地 CA 给这个站点签证书，而不是去找 Let&rsquo;s Encrypt；安装脚本会跑一次 <code>caddy trust</code>，把 CA 的根证书放进 macOS 的系统钥匙串（Chrome 和 Safari 读这里），以及 Firefox 自己的证书库。从此 <code>https://anything.test</code> 打开时都不会有证书警告，普通的 <code>http://</code> 会重定向过去，而且没有任何东西离开这台机器。</p>
<p>这不只是为了好看。现在 Web 平台上有很多东西在纯 HTTP 下直接罢工：secure cookie、service worker、剪贴板 API、任何带 <code>SameSite=None</code> 的东西。在纯 <code>http://localhost</code> 上测 web 构建，会把那些到了真正 HTTPS 域名上才冒出来的 bug 藏起来。在 <code>https://app.local.test</code> 上测，它们就会在我的笔记本上现形。</p>
<p>一个站点块，每个服务除了端口都一样：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-caddyfile" data-lang="caddyfile"><span class="line"><span class="cl"><span class="gh">devbox-ollama.ssh.test</span>, <span class="gh">devbox-ollama.test</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">	<span class="k">tls</span> <span class="no">internal</span>
</span></span><span class="line"><span class="cl">	<span class="k">import</span> cors
</span></span><span class="line"><span class="cl">	<span class="k">reverse_proxy</span> <span class="n">127.0.0.1</span><span class="p">:</span><span class="mi">11435</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">		<span class="k">import</span> proxyhdr
</span></span><span class="line"><span class="cl">		<span class="k">transport</span> <span class="s">http</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">			<span class="k">keepalive</span> <span class="no">off</span>
</span></span><span class="line"><span class="cl">			<span class="k">dial_timeout</span> <span class="mi">5s</span>
</span></span><span class="line"><span class="cl">		<span class="p">}</span>
</span></span><span class="line"><span class="cl">	<span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>麻烦的部分都在那两个 snippet 里。<code>cors</code> 把调用方的 <code>Origin</code> 原样回传，而不是发 <code>*</code>，因为一旦涉及凭据，<code>*</code> 就不被允许；它还自己用 204 应答 <code>OPTIONS</code> 预检请求，上游永远不用操心。<code>proxyhdr</code> 把 <code>Host</code> 头改写成实际连接的地址。有些挑剔的后端，包括路由器管理页面和 Chrome 的远程调试端点，会校验 <code>Host</code>，否则就会把 <code>devbox-ollama.ssh.test</code> 当成一个从没听说过的名字拒掉。Ollama 自己的 origin 检查接受任意端口的 loopback，所以把 <code>Host</code> 改成 <code>127.0.0.1:11435</code> 就能过。</p>
<p><code>keepalive off</code> 是我原本肯定会搞错的那个。上游是 SSH 转发，网络一变，autossh 就会把它拆掉重建。开着 keep-alive 的话，Caddy 会一直攥着一条通往已经死掉的隧道的池化连接，在重载之前一直返回莫名其妙的 404。关掉之后每个请求都重新建连，在 loopback 上这点开销几乎测不出来。</p>
<p>每个服务也仍然响应它原来的扁平名字（<code>devbox-ollama.test</code>），所以启用后缀方案之前的书签还能用。</p>

<h3 class="relative group">菜单栏
    <div id="菜单栏" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%8f%9c%e5%8d%95%e6%a0%8f" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>launchd 撑着十几条转发，我老在问的问题是&quot;它还活着吗？&quot;，而答案散在三个地方：<code>launchctl list</code>、<code>lsof</code> 和一次 <code>curl</code>。于是我写了个小小的菜单栏插件把它们归到一处，每个主机名前面有个圆点：</p>
<ul>
<li>🟢 服务通过隧道响应了请求</li>
<li>🟡 隧道是通的，但后面的服务没反应</li>
<li>🔴 本地端口上没有任何东西在监听，也就是隧道本身断了</li>
</ul>
<p>有用的是黄色这一档。只分绿和红的检查，区分不了&quot;SSH 转发断了&quot;和&quot;远端的 Ollama 崩了&quot;，而这两者的修法完全不同。插件不自己维护服务列表，而是读取和其他部分同一份代理配置和 SSH 配置，所以在那里加一个服务，菜单里也就有了。</p>
<p>第一版太贪了。它每十秒刷新一次，每个服务都要起好几个进程，一次运行大约七十个，macOS 立刻把它列进了&quot;耗电量大的应用&quot;。改成每次运行只取一次快照、每隔几分钟刷新之后，降到了大约一个核的 0.1%。一个状态灯要是费电，就帮了倒忙，所以开销最好一开始就算进去。</p>
<p>它有一个漏洞，恰恰是最要紧的那个。devbox 没有公网域名。它的 SSH 转发连的是一个 <code>192.168.x</code> 地址，所以只有笔记本在办公室局域网里时才管用。一离开办公室，菜单栏就变红，而且一直红着；我为了给笔记本减负而搬到工作站上的所有东西，恰好在我不坐在它旁边的时候全都够不着。</p>

<h2 class="relative group">两条隧道，方向要对
    <div id="两条隧道方向要对" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%a4%e6%9d%a1%e9%9a%a7%e9%81%93%e6%96%b9%e5%90%91%e8%a6%81%e5%af%b9" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>解法分三部分，前两部分是 Cloudflare Tunnel。</p>
<p>Cloudflare Tunnel 就是 <code>cloudflared</code> 保持一条通往 Cloudflare 边缘的出站连接。Cloudflare 把请求沿着这条连接送回来，所以不管机器躲在多少层 NAT 后面，路由器上不用监听任何端口就能访问到它。笔记本连上酒店 wifi 它照样跟着走，CGNAT 也拦不住它。</p>
<p>我跑了两条，每台机器一条，原因值得说一句。显而易见的捷径是只在笔记本上跑一条隧道，再加一条 ingress 规则，指向办公室局域网里 devbox 的 SSH 端口。这样 devbox 上什么都不用装。可它也要经过笔记本，而笔记本正是那台会离开办公室的机器。它会恰好在它本该解决的那种情况下失效。devbox 不挪窝，所以由 devbox 自己保持通往边缘的连接。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># config.yml on devbox (runs as a systemd service)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l">auto       </span><span class="w"> </span><span class="c"># prefer QUIC, fall back to HTTP/2 over TCP 443</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">ha-connections</span><span class="p">:</span><span class="w"> </span><span class="m">4</span><span class="w">     </span><span class="c"># mains-powered, its job is to stay reachable</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">warp-routing</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">connectTimeout</span><span class="p">:</span><span class="w"> </span><span class="l">5s</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">ingress</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">hostname</span><span class="p">:</span><span class="w"> </span><span class="l">ssh-devbox.example.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">service</span><span class="p">:</span><span class="w"> </span><span class="l">tcp://127.0.0.1:22</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">service</span><span class="p">:</span><span class="w"> </span><span class="l">http_status:404</span></span></span></code></pre></div></div>
<p>用 <code>tcp://</code> 而不是 <code>ssh://</code>，是个很容易弄错的地方。<code>ssh://</code> 选的是 Cloudflare 在浏览器里渲染的终端，它会把数据流包装成网页用的格式；普通的 <code>ssh</code> 客户端从这里过，能收到 banner，然后死在密钥交换那一步。<code>tcp://</code> 才是 <code>cloudflared access ssh</code> 期待的那种纯字节管道，顺带还能承载 <code>scp</code>、<code>rsync</code>、走 SSH 的 git 和端口转发。</p>
<p>最后这一点，正好补上了 SSH 这一层的漏洞。现在 SSH 配置会按每次连接选路：</p>
<div class="highlight-wrapper"><pre tabindex="0"><code class="language-sshconfig" data-lang="sshconfig">Match originalhost devbox !exec &#34;nc -z -G 1 &lt;office-lan-ip&gt; 22 &gt;/dev/null 2&gt;&amp;1&#34;
    ProxyCommand cloudflared access ssh --hostname ssh-devbox.example.com ...</code></pre></div>
<p>在办公室局域网里，探测成功，SSH 直连，一跳到位。在其他任何地方探测失败，SSH 就走 Cloudflare，用 Access service token 认证，中间不用在浏览器里登录。这里是 <code>Match originalhost</code>，不是 <code>Match host</code>：<code>host</code> 在 <code>HostName</code> 替换之后才匹配，那时名字已经变成 IP 了，这个块永远不会触发。结果就是 <code>devbox-ollama.ssh.test</code> 在办公室、在家、在火车上都能用，菜单栏上的圆点一直是绿的。</p>
<p>笔记本上那条隧道方向相反。它给 Mac 上的 dev server 分配真正的公网 HTTPS 主机名：我手上在做的每个应用，都有 API、WebSocket 服务和 web 构建这三个。它们每一个都挡在 Cloudflare Access 后面，这一点后面还会讲，因为正是它让这件事变得安全，而不是鲁莽。</p>
<p>菜单栏也学会了认这两条隧道，而且没法靠探测来做。入站隧道没有本地端口可查，两个 connector 里有一个根本不在笔记本上跑，而最直接的测试，curl 一下 <code>ssh-devbox.example.com</code>，不管有没有 connector 挂着，都会从 Cloudflare 边缘拿到响应，所以隧道死了它也会显示绿色。launchd 也好不到哪去：<code>cloudflared</code> 所有边缘连接都断了，它照样显示&quot;loaded, exit 0&quot;。所以隧道这部分改成去问 Cloudflare API 每条隧道有没有健康的 connector，因为决定一次 <code>ssh</code> 能不能落地的就是它。如果连不上 API，这一整部分就干脆不显示，而不是画成红色。菜单是扫一眼就看的东西，那里的一次误报，比少一行的代价更大。</p>

<h2 class="relative group">第三部分：WARP 让它成为一个网络
    <div id="第三部分warp-让它成为一个网络" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e4%b8%89%e9%83%a8%e5%88%86warp-%e8%ae%a9%e5%ae%83%e6%88%90%e4%b8%ba%e4%b8%80%e4%b8%aa%e7%bd%91%e7%bb%9c" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>带主机名的隧道对任何说 HTTPS 的东西都很好用，对能跑 <code>cloudflared</code> 的机器上的 SSH 也一样。手机不行。而且隧道主机名不是一个 TCP 端点：Cloudflare 边缘在上面只终结 HTTPS 和 WebSocket，所以 <code>ssh.example.com</code> 的 22 端口是关着的，在 Access 上怎么折腾都打不开。</p>
<p>这就是 WARP 的活了。Cloudflare One Agent（企业版 WARP 客户端，不是面向普通用户的&quot;1.1.1.1&quot;应用，那个加入不了组织）装在笔记本和手机上，注册进我的 Zero Trust 组织。每条隧道通告私有路由，运行 WARP 的设备就能直接对这些地址开一个普通 socket，落到正确的机器上。它不再是&quot;按名字访问这个服务&quot;，而是&quot;这几台机器和我在同一个网络里&quot;：</p>
<table>
	<thead>
			<tr>
					<th>地址</th>
					<th>机器</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>198.18.42.1</code> / <code>fd12:3456:789a::1</code></td>
					<td>MacBook Air</td>
			</tr>
			<tr>
					<td><code>198.18.42.2</code> / <code>fd12:3456:789a::2</code></td>
					<td>devbox</td>
			</tr>
			<tr>
					<td><code>198.18.42.3</code> / <code>fd12:3456:789a::3</code></td>
					<td>另一台 Mac</td>
			</tr>
	</tbody>
</table>
<p>这些地址是每台机器上的 loopback 别名，开机时创建，所以跟 DHCP 或者我身后是哪台路由器都没关系。<code>198.18.42.2</code> 就是 devbox，在办公室是，在家是，从连着 5G 的手机上也是。Mac 真正的局域网地址我每换一个地方就变一次；这个永远不变。</p>
<p>split tunnel 用的是 <strong>include 模式</strong>，里面只有这些路由（外加 WARP 自身需要的 Cloudflare 网段）。正是这一点让这个客户端能长期开着。默认是 exclude 模式，WARP 承载除一串私有网段之外的所有流量，于是手机发出的每个字节都要绕道 Cloudflare。这对电量和延迟有实打实的代价，大到我最后只会在需要时才打开它，那就失去意义了。在 include 模式下，发往我这三台机器的流量走 WARP，其他一切照常走原来的路径，完全不受影响。所以客户端就一直开着。笔记本上的 <code>warp-cli status</code> 整天都是 <code>Connected</code>，我根本不用去想它。</p>
<p>传输方式我选的是 MASQUE，也就是跑在 UDP 443 上的 HTTP/3，带 HTTP/2 回退，而不是跑在 UDP 2408 上的 WireGuard。有些运营商和访客网络会封 2408；几乎没人封 443。我组织的策略还给 MASQUE 打开了后量子密钥协商，这不是我特意去找的，但也没理由拒绝。</p>

<h2 class="relative group">为什么是 198.18，为什么还有 IPv6 地址
    <div id="为什么是-19818为什么还有-ipv6-地址" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e6%98%af-19818%e4%b8%ba%e4%bb%80%e4%b9%88%e8%bf%98%e6%9c%89-ipv6-%e5%9c%b0%e5%9d%80" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>这些地址看着有点怪，而我最初挑的那几个错得很有教育意义。</p>
<p>我第一次用的是 <code>10.10.0.1</code>，因为大家顺手就会选它。它在两种 split tunnel 模式下都不行。在 exclude 模式下，WARP 的默认列表排除了所有 RFC 1918 网段外加 <code>100.64.0.0/10</code>，所以客户端会在流量离开设备之前就把它丢掉。在 include 模式下，它会和我碰巧接入的任何真实 <code>10.x</code> 网络冲突；咖啡馆、联合办公空间和不少办公室用的正是这个网段。<code>198.18.0.0/15</code> 是 RFC 2544 的基准测试网段。它是保留地址，从不在公网上路由，不在 WARP 的排除列表里，普通网络也不会用它。IPv6 地址用 ULA（<code>fd00::/8</code>），理由相同。</p>
<p>为什么要有 IPv6，这个故事更有意思。v4 地址通了以后，我在手机上连着 wifi 测了一下，没问题，就当完事了。换到 5G 上，不通了。Agent 显示 <em>connected</em> ，隧道健康，Access 也没问题；wifi 上的测试已经证明了这些。问题在于现在的移动网络大多是纯 IPv6。手机根本没有原生 IPv4，是通过运营商的 464XLAT 转换器去访问那个 v4 字面地址的，而当 include 列表里只有一个 v4 前缀时，这个转换器位于隧道 <em>之外</em> 。流量就这么出了公网，而 <code>198.18.0.0/15</code> 在公网上不路由，于是被悄无声息地丢掉了。手机上没有报错，connector 的日志里什么也没有。</p>
<p>解法是给每台机器再配一个手机能原生通过 IPv6 访问的地址，并把它加进路由和 include 列表。现在我手机上的 SSH 客户端在移动数据下真正用的，就是 <code>fd12:3456:789a::</code> 这组地址。</p>

<h2 class="relative group">卸载：把笔记本当终端用
    <div id="卸载把笔记本当终端用" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%8d%b8%e8%bd%bd%e6%8a%8a%e7%ac%94%e8%ae%b0%e6%9c%ac%e5%bd%93%e7%bb%88%e7%ab%af%e7%94%a8" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>整套配置就是为这一部分存在的。</p>
<p><strong>模型和微调。</strong> Ollama 跑在 devbox 上，绑定 <code>127.0.0.1:11434</code>。办公室局域网里的其他机器都看不见它，更别说公网了。在笔记本上，它出现在 <code>https://devbox-ollama.ssh.test</code>，或者给需要端口的工具一个裸端口：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">OLLAMA_HOST</span><span class="o">=</span>127.0.0.1:11435 ollama list</span></span></code></pre></div></div>
<p>用 11435 而不是 11434 是故意的：11434 是 Ollama 自己的默认端口，要是笔记本哪天也跑了个本地 Ollama，两者就会抢这个端口，而我会根据谁先启动，悄悄地从&quot;本地&quot;那个拿到 devbox 的回答。</p>
<p>实际效果是，我做 AI 功能时，它调用的模型跑在工作站的 GPU 上，而不是笔记本上，不管我人在哪儿。评估跑批、给一大堆文档做 embedding、跑一次微调：都在 devbox 上跑，笔记本的风扇一声不响。做 agent 原型时，可以让它指向工作站上的本地模型，反复跑工具调用也不产生 API 账单，等循环调顺了再换成托管模型。</p>
<p><strong>长时间运行的 agent。</strong> 一个要跑一小时的 agent 会话，不该取决于我的笔记本盖子是不是一直开着。改在 devbox 上跑，笔记本就只是一扇看它的窗口：合上盖子，过会儿不管在哪儿 <code>ssh devbox</code>，或者从手机上连，它都还在。有隧道之前，这只在办公室里管用，而办公室恰恰是我最不需要它的地方。</p>
<p><strong>构建和集群。</strong> devbox 上的集群有自己的镜像仓库，所以镜像可以在工作站上构建和推送，就在它们运行的地方旁边，而不是用笔记本通过酒店 wifi 上传。集群仪表盘、ingress 仪表盘和镜像仓库的 UI，在笔记本上都是 <code>*.ssh.test</code> 主机名。</p>
<p><strong>移动端的开发循环。</strong> 手机和笔记本在同一个私有网络里，笔记本的 dev server 还有挂在 Access 后面的公网主机名。所以我可以带着应用的原生构建走出大楼，连着 5G，它照样和我桌上跑着的 API 通信。或者和 devbox 上那个通信，如果我把它留在那儿的话。在真机、真实移动网络上的反馈循环，以前意味着部署到共享的 staging 服务器。现在意味着保存一个文件。</p>
<p>这里有个坑，最好在你把它当成应用 bug 去调之前就知道。Access 也保护着 WebSocket 主机名，而原生的 WebSocket 客户端不是浏览器。它不带 <code>CF_Authorization</code> cookie，所以原生构建连到 WebSocket 服务的连接会在边缘被一个 403 拒掉，看起来跟你自己服务器报的错完全不像。浏览器标签页没问题，因为登录后它们已经有了那个 cookie。对任何不是浏览器的东西（原生应用、脚本、调用 dev API 的 agent），答案是 Access 的 <strong>service token</strong>，以两个请求头的形式发送：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">CF-Access-Client-Id:     &lt;client_id&gt;
</span></span><span class="line"><span class="cl">CF-Access-Client-Secret: &lt;client_secret&gt;</span></span></code></pre></div></div>
<p>这个 token 本身什么权限都不给。Access 只在策略里点了它名的应用上认它，所以它能触及的范围恰好就是那串 dev 主机名，一点不多。我把它的策略归在 <code>non_identity</code> 决策下，而不是 <code>allow</code>，这样在审计日志里它始终显示为一个持有者凭据，而不是某个登录进来的人。</p>

<h2 class="relative group">公网永远看不到的数据
    <div id="公网永远看不到的数据" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%85%ac%e7%bd%91%e6%b0%b8%e8%bf%9c%e7%9c%8b%e4%b8%8d%e5%88%b0%e7%9a%84%e6%95%b0%e6%8d%ae" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>我想要的另一半是可观测性。能告诉你系统运行状况的东西，大多数本就不该公开，这没错。在 devbox 上，这些东西是：</p>
<ul>
<li>ingress 代理的仪表盘，以及装着它的链路追踪的追踪界面</li>
<li>管 Kubernetes 集群的仪表盘</li>
<li>容器镜像仓库的 UI（只读）</li>
<li>Ollama 的模型列表和当前加载了哪些模型</li>
<li><code>docker info</code> 和容器统计数据</li>
</ul>
<p>这些都没有公网主机名，以后也不会有。它们绑定在 loopback 或集群的 service IP 上，通过 SSH 转发访问，而这条转发本身又跑在隧道上。我手机上有个监控应用，经 WARP 通过 SSH 读取 <code>docker info --format '{{json .}}'</code>，所以不管在哪儿，我都能看到容器是不是都在跑，或者有没有什么东西把内存吃光了。</p>
<p>也正是这个应用让我发现了一个值得一提的小 bug。Mac 上那个隧道用的 sshd，还停留在我调试时设的 <code>LogLevel DEBUG2</code>。带 <code>-e</code> 时 sshd 把日志写到 stderr，而对一个会话来说，这个 stderr <em>就是</em> SSH 通道的 stderr。每条命令的输出后面都多了一行 <code>debug2: do_setup_env: set TMPDIR</code>，而手机应用会把两个流合并，于是拿到的是合法 JSON 后面跟着一行日志，解析失败，把整段显示成错误。改成 <code>LogLevel INFO</code> 就好了。调试完记得把日志级别改回去。</p>
<p>同样是刻意为之的，是我 <em>不</em> 放进这个网络的东西。旧的 autossh 隧道还能连到几台别人网络里的路由器，我帮忙照看着。它们没有公网主机名，也没有 WARP 路由。路由器管理页面挂在公网上，哪怕有登录挡着也是个隐患，而且那不是我的网络，轮不到我去扩大它的暴露面。</p>

<h2 class="relative group">Access 不是可选项
    <div id="access-不是可选项" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#access-%e4%b8%8d%e6%98%af%e5%8f%af%e9%80%89%e9%a1%b9" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>Cloudflare Tunnel 的主机名，DNS 记录一建好就在公网上了。它前面没有防火墙；不开端口的全部意义就在这里。保护必须来自 Cloudflare 边缘，而这正是 Access 做的事。在访问者证明自己是谁之前，它根本不转发请求，所以没认证的扫描器永远到不了笔记本。这很重要，因为这些是 dev server：带着 settings 的调试模式报错页，一个敞开的 JavaScript bundler。这些主机名后面的东西，没有一样是为面对公网而做的。</p>
<p>策略只放行我自己的几个邮箱地址，别的一概不放，证明身份的方式有两种：邮件一次性 PIN 码和 SSO 单点登录。会话持续八小时，因为现实中的威胁是一台在咖啡馆里开着、带着一整天有效 cookie 的笔记本，而不是有人暴力破解 PIN 码。</p>
<p>SSH 被认证了两次，由两个互不知情的系统分别负责。Access 决定一条 TCP 流能不能到达 sshd；sshd 照样要我的密钥。丢了其中任何一个，机器都不会因此敞开。Mac 上的隧道 sshd 还信任 Cloudflare 的 SSH CA，所以 Access 可以用从我的 SSO 会话签发的短期证书让我登录，同时 <code>authorized_keys</code> 也照样能用，这样一份坏掉的 Access 配置也不会把我锁在自己的笔记本外面。</p>
<p>我最满意的是一个很小的部分。暴露发生在三件事同时成立的时候：一条 DNS 记录、一个在跑的 connector、一个已激活的 zone。它们在不同时间变为真，顺序也不由我控制；zone 会在 nameserver 改完之后过一阵子自己变成 active，那时 Mac 很可能正睡着。所以 launch agent 不直接跑 <code>cloudflared</code>。它先跑一个预检：从隧道自己的配置里读出主机名，问 Access API 哪些已经被覆盖，只要有一个没被覆盖就拒绝启动：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">HOSTNAMES</span><span class="o">=</span><span class="k">$(</span>grep -E <span class="s1">&#39;^\s*-\s*hostname:&#39;</span> <span class="s2">&#34;</span><span class="nv">$CONFIG</span><span class="s2">&#34;</span> <span class="p">|</span> sed -E <span class="s1">&#39;s/.*hostname:\s*//&#39;</span> <span class="p">|</span> sort -u<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">PROTECTED</span><span class="o">=</span><span class="k">$(</span>curl -fsS -H <span class="s2">&#34;Authorization: Bearer </span><span class="nv">$CLOUDFLARE_API_TOKEN</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;https://api.cloudflare.com/client/v4/accounts/</span><span class="nv">$CLOUDFLARE_ACCOUNT_ID</span><span class="s2">/access/apps?per_page=100&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="p">|</span> python3 -c <span class="s1">&#39;import sys,json; print(&#34;\n&#34;.join(a.get(&#34;domain&#34;,&#34;&#34;) for a in json.load(sys.stdin)[&#34;result&#34;]))&#39;</span><span class="k">)</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="o">||</span> <span class="o">{</span> <span class="nb">echo</span> <span class="s2">&#34;could not reach the Access API. refusing (fail closed).&#34;</span><span class="p">;</span> <span class="nb">exit</span> 1<span class="p">;</span> <span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">for</span> h in <span class="nv">$HOSTNAMES</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    grep -qxF <span class="s2">&#34;</span><span class="nv">$h</span><span class="s2">&#34;</span> <span class="o">&lt;&lt;&lt;</span><span class="s2">&#34;</span><span class="nv">$PROTECTED</span><span class="s2">&#34;</span> <span class="o">||</span> <span class="o">{</span> <span class="nb">echo</span> <span class="s2">&#34;NOT starting: </span><span class="nv">$h</span><span class="s2"> has no Access app&#34;</span><span class="p">;</span> <span class="nb">exit</span> 1<span class="p">;</span> <span class="o">}</span>
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span><span class="line"><span class="cl"><span class="nb">exec</span> cloudflared tunnel --config <span class="s2">&#34;</span><span class="nv">$CONFIG</span><span class="s2">&#34;</span> run</span></span></code></pre></div></div>
<p>launch agent 设了 <code>KeepAlive</code>，所以被拒之后它每 30 秒自己重试一次，Access 应用一建好，隧道就自己起来了。失败时关闭，代价是一次宕机。失败时敞开，代价是一次暴露。我很清楚这两件事里我更愿意解释哪一件。</p>

<h2 class="relative group">踩过的四个坑
    <div id="踩过的四个坑" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%b8%a9%e8%bf%87%e7%9a%84%e5%9b%9b%e4%b8%aa%e5%9d%91" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>上面这些现在都能用了。一路走来，四个坑里有三个是同一个模式：坏掉的那个东西在任何地方都不报错，而我能看到的部分全都显示健康。</p>
<p><strong>路由和 include 列表是两份不同的列表。</strong> 隧道路由让 Cloudflare <em>愿意</em> 把某个地址的流量送到正确的 connector。WARP 的 include 列表才决定客户端一开始会不会 <em>发送</em> 它。devbox 从手机上连不通，就是因为它的路由已经存在，但 include 列表里还只有 Mac 的地址。手机在本地就把包丢了，connector 从没见到过任何流量，所有仪表盘都是绿的。每加一台新机器，都要把它的地址同时加进这两处。</p>
<p><strong>纯 IPv6 移动网络上的 IPv4 字面地址。</strong> 上面讲过了：wifi 上能用，5G 上失败，没有报错。如果一条 WARP 路由在 wifi 上能用、移动数据上不行，而 Agent 显示已连接，那是路由的问题，不是隧道的问题。</p>
<p><strong>cloudflared 后面的 macOS sshd。</strong> macOS 用 launchd 的 socket activation 启动 sshd，每个连接一个短命的 <code>sshd -i</code>。放在 cloudflared 后面时，banner 能到达客户端，但在客户端的标识字符串传回来之前，数据流就被拆掉了，所以每次登录都死在 <code>kex_exchange_identification</code>。我从两端都确认过，还用一个普通的 TCP 中继复现了出来，排除了 Cloudflare 的嫌疑。解法是另起一个独立的 <code>sshd -D</code>，监听 <code>127.0.0.1:2222</code> 和 WARP 的 loopback 地址，以我的用户身份运行，唯一的用途就是充当隧道的源站。系统设置里的远程登录原封不动。devbox 是 Linux，跑的是正常的常驻 sshd，从来没有这个问题。</p>
<p><strong>不复存在的配置字段。</strong> 旧的示例在隧道配置里写着 <code>warp-routing: enabled: true</code>。cloudflared 2026.8 会直接拒绝这个字段。只要这个块存在、且有路由指向这条隧道，WARP 路由就是开着的。至少这个报了错，跟前面三个比起来，简直称得上厚道。</p>

<h2 class="relative group">它改变了什么
    <div id="它改变了什么" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%ae%83%e6%94%b9%e5%8f%98%e4%ba%86%e4%bb%80%e4%b9%88" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>老实说，总结起来就是：我不再根据硬件在哪儿来决定在哪儿干活。笔记本是一副好键盘、一块好屏幕，续航很长，它不需要比这更多。工作站不管我在哪儿都替我扛重活。手机是在真实网络上的真实测试设备，而不是拴在办公室 wifi 上的东西。而我用来观察系统在干什么的那些部分，对我来说一点就开，对别人来说根本不存在。</p>
<p>这个规模下，它在 Cloudflare 免费的 Zero Trust 套餐以内。花掉的是时间，外加一份我很庆幸写了的 README，因为上面那些故障，每一个第二次遇到时都会是一个全新的谜。</p>
<p>如果你在考虑搭类似的东西，下面是我会拿来问你的配置的几个问题：</p>
<ol>
<li>有哪些东西跑在你的笔记本上，只是因为笔记本是你唯一随时能连上的机器？</li>
<li>你的手机能用移动数据访问你的 dev server 吗，而不只是在办公室 wifi 上？用 5G 测，别用 wifi。</li>
<li>你的仪表盘里，有哪些是公开的，只因为那是从外面看它们最省事的办法？每一个都可以改成私有路由。</li>
<li>如果明天某个隧道主机名起来了却没有对应的 Access 应用，什么会拦住它？如果答案是&quot;我会记得&quot;，那就把预检写出来。</li>
<li>你的私有地址所在的网段，是你去过的那些网络永远不会用的吗？</li>
</ol>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-10-01-cloudflare-warp-dev-network/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>用 Codemagic Patch 替换我自建的 Expo 更新服务器</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-13-moving-to-codemagic-patch/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-13-moving-to-codemagic-patch/</guid>
      <pubDate>Sun, 13 Sep 2026 00:00:00 +0900</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>React Native</category>
      <category>Expo</category>
      <category>OTA Updates</category>
      <category>Codemagic Patch</category>
      <category>CodePush</category>
      <category>Self-Hosted</category>
      <category>Mobile Development</category>
      <category>CI/CD</category>
      <description>我把一个真实的 Expo 应用，连原生工程一起，从 expo-updates 迁到了 Codemagic Patch：本地栈、迁移过程、一个我自己造成又通过 OTA 修掉的 bug，以及一次发布真的崩了之后回滚是什么样子。</description>
      <content:encoded><![CDATA[<blockquote><p><strong>声明。</strong> 这次迁移和这篇文章是 Codemagic 付费委托的。他们只对事实准确性做了一轮审阅，不涉及语气，文中没有任何内容是应他们要求修改的。凡是我遇到问题并反馈了的地方，我都会说明；如果你读到这里时问题已经修复，文中会写成已修复。</p>
</blockquote><blockquote><p><strong>2026 年 9 月 23 日更新。</strong> 我反馈的问题，Codemagic 的开发者都逐一处理了。大部分已经修复，包括 iOS 版本检测的 bug、重复计数的安装、首次运行时的静默，以及那条吵闹的调试命令；文档现在也写到了已提交的原生工程和崩溃回滚的额度。下文中每个问题出现的地方我都标注了，仍未解决的那几个保持原样。</p>
</blockquote><blockquote><p><strong>2026 年 10 月 16 日更新。</strong> 迁到 Patch 之后的第一次原生升级（Expo SDK 58）构建出了一个完全不含 Patch 配置的 Android release，而且没有任何地方报错。来龙去脉和只改一个文件的修复写在 <a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-13-moving-to-codemagic-patch/#%e7%ac%ac%e4%b8%80%e6%ac%a1%e5%8e%9f%e7%94%9f%e5%8d%87%e7%ba%a7" >第一次原生升级</a>。</p>
</blockquote><p>二月我写过一篇<a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-02-22-self-hosted-ota-updates/" >自己搭 Expo 更新服务器</a>的文章。它现在还在跑。我运营的社区应用 maru 从那以后每一次 OTA 修复都走它，两个平台都是，每月大约一美元。</p>
<p>这也意味着每一块都归我管：几张数据库表、一个 API 接口、一条管理命令、一个发布脚本、一个共享密钥，还有一堆坑，每个坑都是靠一次坏掉的更新学来的。坐下来做规划时我才发现，那个脚本从我写它的第一天起，每次生产发布之后都会打印 &ldquo;Sent 0 push notifications&rdquo;，读的是一个这台服务器从未返回过的字段。没人注意到，最没注意到的就是我。自己维护一套东西，大概就会变成这样。</p>
<p>所以当 Codemagic 问我要不要试试 <a href="https://patch.codemagic.io/"  target="_blank" rel="noreferrer sponsored">Patch</a>，他们那套<a href="https://github.com/codemagic-ci-cd/codemagic-patch"  target="_blank" rel="noreferrer sponsored">开源</a>、可自托管的 CodePush 替代品，我答应了，只有一个条件：要用真实的应用，而不是 demo。真实的签名、真实的发布流程、已经提交进仓库并且手改过的原生工程，全套。大多数打算离开 EAS Update 的人，要迁的都是这样的应用，不是刚生成的模板。</p>
<p>下面就是整个过程，毛边都留着。</p>
<figure><div class="film-pair">
  <div class="mc-film film-dark">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film-poster.jpg" style="background:url('data:image/webp;base64,UklGRngAAABXRUJQVlA4IGwAAADQBACdASogABIAPw12qkmmI6GYDAQAYxDE9IABUYPdOZbru82h5cj1rTAwl7UkCAD+6LtMSUUTk7Xb87esmRGyzFCtrX13j1gdi5rqnvw7rsZGz3OYwYPBwIvD2aLoLjGuPChToAJcOOivQAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <div class="mc-film film-light">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film-light-poster.jpg" style="background:url('data:image/webp;base64,UklGRoIAAABXRUJQVlA4IHYAAACQBACdASogABIAPw1sqUemIyIYBABjEMT0gAFRZY1tQKVVHPUfWxkc2Bs75kAA/u+6aABtB+MYV02ZVTPoxBkkmzc3vO1UQaTBYenW4qyDVxhq0vJFiUKvn4G3BTnsUdC0oW9arIFlmI4kbi/flHgAMAOOZAAA') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film-light.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/patch-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <script>(function(){if(window.mcFilm)return window.mcFilm();var a={play:'<path d="M8 5.6v12.8a1 1 0 0 0 1.52.85l10.2-6.4a1 1 0 0 0 0-1.7L9.52 4.75A1 1 0 0 0 8 5.6z"/>',pause:'<rect x="6.5" y="5" width="4" height="14" rx="1.2"/><rect x="13.5" y="5" width="4" height="14" rx="1.2"/>',volume:'<path d="M4 9.5v5a1 1 0 0 0 1 1h3l4.4 3.6a.6.6 0 0 0 1-.47V5.37a.6.6 0 0 0-1-.47L8 8.5H5a1 1 0 0 0-1 1z"/><path d="M16.5 8.5a5 5 0 0 1 0 7M19 6a8.5 8.5 0 0 1 0 12" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/>',muted:'<path d="M4 9.5v5a1 1 0 0 0 1 1h3l4.4 3.6a.6.6 0 0 0 1-.47V5.37a.6.6 0 0 0-1-.47L8 8.5H5a1 1 0 0 0-1 1z"/><path d="M16.5 9.5l5 5m0-5l-5 5" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/>',cc:'<rect x="3" y="5.5" width="18" height="13" rx="3" fill="none" stroke="currentColor" stroke-width="1.8"/><path d="M10.5 10.3a2.2 2.2 0 1 0 0 3.4M17 10.3a2.2 2.2 0 1 0 0 3.4" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/>',full:'<path d="M4.5 9V5.5a1 1 0 0 1 1-1H9M15 4.5h3.5a1 1 0 0 1 1 1V9M19.5 15v3.5a1 1 0 0 1-1 1H15M9 19.5H5.5a1 1 0 0 1-1-1V15" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>',exit:'<path d="M9 4.5V8a1 1 0 0 1-1 1H4.5M19.5 9H16a1 1 0 0 1-1-1V4.5M15 19.5V16a1 1 0 0 1 1-1h3.5M4.5 15H8a1 1 0 0 1 1 1v3.5" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>'},s={en:["Play","Pause","Mute","Unmute","Subtitles","Off","Full screen","Exit full screen","Seek"],ko:["재생","일시정지","음소거","음소거 해제","자막","끄기","전체 화면","전체 화면 종료","탐색"],ja:["再生","一時停止","ミュート","ミュート解除","字幕","オフ","全画面","全画面を終了","シーク"],zh:["播放","暂停","静音","取消静音","字幕","关闭","全屏","退出全屏","进度"],vi:["Phát","Tạm dừng","Tắt tiếng","Bật tiếng","Phụ đề","Tắt","Toàn màn hình","Thoát toàn màn hình","Tua"]},r=(document.documentElement.lang||"en").toLowerCase().slice(0,2),e=s[r]||s.en,t=function(e){return'<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">'+a[e]+"</svg>"},o={},i=function(e,t){if(o[e]||typeof window.gtag!="function")return;o[e]=!0;var n=(t.currentSrc||(t.querySelector("source")||{}).src||"").split("/").pop();window.gtag("event",e,{film:n.replace(/-light(?=\.)/,"")})},n=function(e){(!isFinite(e)||e<0)&&(e=0),e=Math.floor(e);var t=Math.floor(e/3600),n=Math.floor(e%3600/60),s=String(e%60).padStart(2,"0");return t?t+":"+String(n).padStart(2,"0")+":"+s:n+":"+s};function c(s){var a,r,c,d,u,m,p,g,v,b,j,_,w,O,C,E,k,A,o=s.querySelector("video");if(!o)return;s.classList.add("is-ready"),o.controls=!1,o.removeAttribute("controls"),s.insertAdjacentHTML("beforeend",'<button type="button" class="mc-film__big" aria-label="'+e[0]+'">'+t("play")+'</button><div class="mc-film__bar"><button type="button" class="mc-film__btn" data-act="play" aria-label="'+e[0]+'">'+t("play")+'</button><span class="mc-film__time"><span data-cur>0:00</span><span class="mc-film__of"> / </span><span data-dur>0:00</span></span><input class="mc-film__seek" type="range" min="0" max="1000" step="1" value="0" aria-label="'+e[8]+'"><span class="mc-film__cc"><button type="button" class="mc-film__btn" data-act="cc" aria-label="'+e[4]+'" aria-haspopup="true" aria-expanded="false">'+t("cc")+'</button><span class="mc-film__menu" role="menu" hidden></span></span><button type="button" class="mc-film__btn" data-act="mute" aria-label="'+e[2]+'">'+t("volume")+'</button><button type="button" class="mc-film__btn" data-act="full" aria-label="'+e[6]+'">'+t("full")+"</button></div>"),A=s.querySelector(".mc-film__big"),a=s.querySelector(".mc-film__bar"),j=a.querySelector('[data-act="play"]'),p=a.querySelector('[data-act="mute"]'),u=a.querySelector('[data-act="full"]'),d=a.querySelector('[data-act="cc"]'),r=a.querySelector(".mc-film__menu"),c=a.querySelector(".mc-film__seek"),w=a.querySelector("[data-cur]"),O=a.querySelector("[data-dur]"),g=!1,v=0,b=function(){return Array.prototype.filter.call(o.textTracks,function(e){return e.kind==="subtitles"||e.kind==="captions"})},b().length||(d.parentNode.hidden=!0),_=null;function f(e){var n,i,t=!s.classList.contains("is-idle")&&s.classList.contains("is-started");if(e!==!0&&t===_)return;_=t,n=o.clientHeight,i=n?Math.max(40,100-(a.offsetHeight+22)/n*100):85,b().forEach(function(e){if(e.mode!=="showing"||!e.cues)return;for(var n,s=0;s<e.cues.length;s++)n=e.cues[s],t?(n.snapToLines=!1,n.line=i,n.lineAlign="end"):(n.snapToLines=!0,n.line="auto",n.lineAlign="start")})}m=function(){f(!0)},window.addEventListener("resize",m),Array.prototype.forEach.call(o.querySelectorAll("track"),function(e){e.addEventListener("load",m)});function y(){o.paused||o.ended?o.play().catch(function(){}):o.pause()}function l(){s.classList.remove("is-idle"),f(),clearTimeout(v),v=setTimeout(function(){!o.paused&&r.hidden&&!a.querySelector(":focus-visible")&&(s.classList.add("is-idle"),f())},2600)}function M(){clearTimeout(v),h(),s.classList.add("is-idle"),f()}function h(){r.hidden=!0,d.setAttribute("aria-expanded","false")}function F(){var t=b(),n=t.filter(function(e){return e.mode==="showing"})[0];r.innerHTML="",[null].concat(t).forEach(function(s){var o=document.createElement("button");o.type="button",o.setAttribute("role","menuitemradio"),o.setAttribute("aria-checked",String(s?s===n:!n)),o.textContent=s?s.label||s.language:e[5],o.addEventListener("click",function(){t.forEach(function(e){e.mode=e===s?"showing":"disabled"}),h(),setTimeout(m,0),l()}),r.appendChild(o)}),r.hidden=!1,d.setAttribute("aria-expanded","true")}function x(){var n=!o.paused&&!o.ended;s.classList.toggle("is-playing",n),j.innerHTML=t(n?"pause":"play"),j.setAttribute("aria-label",n?e[1]:e[0]),n||l()}function S(){if(w.textContent=n(o.currentTime),!g&&o.duration){var e=o.currentTime/o.duration*1e3;c.value=e,c.style.setProperty("--p",e/10+"%")}}A.addEventListener("click",function(){o.play().catch(function(){})}),C="mouse",s.addEventListener("pointerdown",function(e){C=e.pointerType}),o.addEventListener("click",function(){if(!s.classList.contains("is-started"))return o.play().catch(function(){});if(C==="mouse")return y();s.classList.contains("is-idle")?l():M()}),j.addEventListener("click",y),o.addEventListener("play",function(){s.classList.contains("is-started")||i("film_play",o),s.classList.add("is-started"),x(),l()}),"IntersectionObserver"in window&&(E=new IntersectionObserver(function(e){if(!e.some(function(e){return e.isIntersecting}))return;E.disconnect(),i("film_view",o)},{threshold:.5}),E.observe(s)),o.addEventListener("pause",x),o.addEventListener("ended",x),o.addEventListener("timeupdate",S),o.addEventListener("durationchange",function(){O.textContent=n(o.duration),S()}),o.addEventListener("loadedmetadata",function(){O.textContent=n(o.duration)}),o.addEventListener("volumechange",function(){p.innerHTML=t(o.muted?"muted":"volume"),p.setAttribute("aria-label",o.muted?e[3]:e[2])}),p.addEventListener("click",function(){o.muted=!o.muted}),c.addEventListener("input",function(){g=!0,c.style.setProperty("--p",c.value/10+"%"),o.duration&&(o.currentTime=c.value/1e3*o.duration,w.textContent=n(o.currentTime))}),c.addEventListener("change",function(){g=!1}),d.addEventListener("click",function(e){e.stopPropagation(),r.hidden?F():h()}),document.addEventListener("click",function(e){!r.hidden&&!r.contains(e.target)&&h()}),u.addEventListener("click",function(){document.fullscreenElement||document.webkitFullscreenElement?(document.exitFullscreen||document.webkitExitFullscreen).call(document):s.requestFullscreen?s.requestFullscreen().catch(function(){}):s.webkitRequestFullscreen?s.webkitRequestFullscreen():o.webkitEnterFullscreen&&o.webkitEnterFullscreen()}),k=function(){var n=(document.fullscreenElement||document.webkitFullscreenElement)===s;s.classList.toggle("is-fullscreen",n),u.innerHTML=t(n?"exit":"full"),u.setAttribute("aria-label",n?e[7]:e[6])},document.addEventListener("fullscreenchange",k),document.addEventListener("webkitfullscreenchange",k),s.addEventListener("pointermove",function(e){e.pointerType==="mouse"&&l()}),s.addEventListener("focusin",l),s.addEventListener("keydown",function(e){if(e.target===c&&/^Arrow/.test(e.key))return;var t=e.key.toLowerCase();if(t==="k"||t===" "&&e.target===o)y();else if(t==="arrowleft")o.currentTime=Math.max(0,o.currentTime-5);else if(t==="arrowright")o.currentTime=Math.min(o.duration||0,o.currentTime+5);else if(t==="m")o.muted=!o.muted;else if(t==="f")u.click();else if(t==="escape"&&!r.hidden)h();else return;e.preventDefault(),l()}),o.tabIndex=0}window.mcFilm=function(){document.querySelectorAll(".mc-film:not(.is-ready)").forEach(c)},window.mcFilm()})()</script></div>
  <script>
  new MutationObserver(() => {
    const dark = document.documentElement.classList.contains("dark");
    document.querySelectorAll(".film-pair").forEach((pair) => {
      const from = pair.querySelector(dark ? ".film-light video" : ".film-dark video");
      const to = pair.querySelector(dark ? ".film-dark video" : ".film-light video");
      if (!from || !to || !from.currentTime) return;
      const playing = !from.paused;
      from.pause();
      to.currentTime = from.currentTime;
      [...from.textTracks].forEach((track, i) => { if (to.textTracks[i]) to.textTracks[i].mode = track.mode; });
      if (playing) to.play().catch(() => {});
    });
  }).observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
  </script><figcaption>这篇文章的九分钟视频版。旁白是英文，配有中文字幕。</figcaption>
</figure>


<h2 class="relative group">Patch 是什么
    <div id="patch-是什么" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#patch-%e6%98%af%e4%bb%80%e4%b9%88" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>Patch 是一台你自己跑的服务器，加一个放进应用里的 SDK。服务端包括一个 API、一个后台 worker、Postgres、S3 兼容的对象存储和一个 Web 面板，打包成一套 Docker Compose 栈。客户端是 <code>@codemagic/react-native-patch</code>，一个支持 iOS 和 Android 的 TurboModule，附带 Expo 配置插件，再加一个 CLI，<code>cmpatch</code>，负责打包 JavaScript 并发布。</p>
<p>读完源码之后，有两个设计决定让我印象深刻。</p>
<p>第一，应用从不向 API 询问有没有更新。发布一个 release 时，worker 会把纯 JSON 的清单写进对象存储，应用只是去取那些文件。一次更新检查就是对存储或 CDN 的两个静态 GET，API 只接收指标。我原来的接口站在每一次应用启动的请求路径上；这一套想站也站不上去。</p>
<p>第二，每个 release 都精确地写明它面向哪个二进制版本，CLI 会对你的原生工程算一个指纹，拒绝把 JavaScript 发到原生代码对不上的二进制上。我的服务器只有一个版本字符串，剩下的全靠祈祷。</p>

<h2 class="relative group">先在自己笔记本上试
    <div id="先在自己笔记本上试" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%85%88%e5%9c%a8%e8%87%aa%e5%b7%b1%e7%ac%94%e8%ae%b0%e6%9c%ac%e4%b8%8a%e8%af%95" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>文档一上来让你搭的是本地评估栈，从这里开始是对的。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npm install -g @codemagic/patch-cli
</span></span><span class="line"><span class="cl">cmpatch selfhost local-eval up</span></span></code></pre></div></div>
<p>CLI 两秒就装好了。整套栈第一次起来花了 3 分 14 秒，大部分时间在本地构建服务器和面板的镜像，而且在非交互模式下，这期间它什么都不打印，看起来和挂死一模一样。（现已修复：它现在每一步会打印一行进度。）然后四个健康的容器就出现了，全部绑定在 localhost：面板在 8080，API 在 3000，Postgres，还有 MinIO 在 9100。它很懂事地避开了我自己那套栈已经占用的端口。</p>
<p>这个模式下登录是关掉的，每个页面上都有一条警告，叫你别把它暴露出去。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><span class="browser-frame__shot" style="background:url('data:image/webp;base64,UklGRmwAAABXRUJQVlA4IGAAAACQBACdASogABQAPv1ko0eloqGYBgBbD8TgCzgCWNWXs6T53beCcoRI0PP/N6AA/K7n/8I/+iwVHjl71MVWujkm+9TgA0wAr+PZ+x6+cQcgCHdovZ75vexrOBrFPrvj8AA=') center/cover no-repeat"><img
      class="browser-frame__page"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/local-eval-sign-in_hu_6ee9ddaa0c7c695e.webp"
      srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/local-eval-sign-in_hu_6ee9ddaa0c7c695e.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/local-eval-sign-in_hu_e5915d9b78052f15.webp 1280w"
      sizes="(min-width: 768px) 50vw, 65vw"
      width="1400" height="875"
      alt="本地评估模式的登录页，邮箱已预填，并提示认证已禁用"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/local-eval-sign-in_hu_8ae8b3cbcb1d7ae7.webp"></span></div>
  <figcaption>本地评估模式用一个预填好的邮箱代替了 GitHub 登录。</figcaption>
</figure>

<p>栈自带一个叫 Example Data 的种子应用，在你发布任何东西之前值得先看一眼，因为它展示了面板是用来干什么的。接下来两张截图里的数字都是种子数据，不是真实用户。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><span class="browser-frame__shot" style="background:url('data:image/webp;base64,UklGRmgAAABXRUJQVlA4IFwAAAAQBACdASogABUAPw1uqkqmIyGYDAQAYxDE9IABUVMfRogwtMiXImNo4AD+1hmAfbeuR0QbIc0lZuw4PBjyhGJq5t/3NdR81x+BG5H496NeiObQODoB8gkWF2AAAA==') center/cover no-repeat"><img
      class="browser-frame__page"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/demo-release-history_hu_dfad23ca3450bc38.webp"
      srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/demo-release-history_hu_dfad23ca3450bc38.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/demo-release-history_hu_453fd7641ffbc69b.webp 1280w"
      sizes="(min-width: 768px) 50vw, 65vw"
      width="1600" height="1037"
      alt="种子应用 Example Data 的发布历史，有一个 10% 的金丝雀发布，以及每个 release 的成功和失败次数"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/demo-release-history_hu_30abe30dd08f2234.webp"></span></div>
  <figcaption>种子演示数据：发布历史，含一个 10% 的金丝雀发布、目标版本，以及每个 release 的成功和失败次数。</figcaption>
</figure>

<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><span class="browser-frame__shot" style="background:url('data:image/webp;base64,UklGRoQAAABXRUJQVlA4IHgAAABwBACdASogABcAPw1qrEsmIqIYDAQAYxDE9IBnsglwh49zWML+lyXzzjPEgAD+4AZDuD4GlZfO+rTnJJ+yBUjSHGV1a2gPc+tdTO7IIMf86boVjtRW8VJ7KXLfxZsJzumvn68JtLzOqetoXfqt/I/Omlo4DyEAAAA=') center/cover no-repeat"><img
      class="browser-frame__page"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/demo-deployment-metrics_hu_2e0ff04f94cd5a88.webp"
      srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/demo-deployment-metrics_hu_2e0ff04f94cd5a88.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/demo-deployment-metrics_hu_91146bb0b6c75d52.webp 1280w"
      sizes="(min-width: 768px) 50vw, 65vw"
      width="1600" height="1155"
      alt="种子应用的部署指标：版本分布、随时间的采用率、更新结果"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/demo-deployment-metrics_hu_1f6ae6ce53428957.webp"></span></div>
  <figcaption>种子演示数据：设备实际在跑哪些 release，以及安装进行得如何。</figcaption>
</figure>

<p>作为对比，我的面板就是后台里的一张更新列表，带一个“启用”复选框。到底有多少台手机真的装了更新，我完全不知道。</p>
<p>CLI 登录是一套正经的浏览器流程，带 PKCE 和 localhost 回调，批准页面会告诉你是哪个账号在请求，以及授权码大约一分钟后过期。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><span class="browser-frame__shot" style="background:url('data:image/webp;base64,UklGRn4AAABXRUJQVlA4IHIAAADwBACdASogABQAPv1ioUeloqGYBgBbD8TxAFnAEsa4FDLDrochGk8HT/WQ+e1SUMAA/K7n5mOlQFSkxh0DtgfJ9tHRhVgvwu2jEApXgWL2ekdKJHkUb1NzXgNcjv6IA1JC+dF2JqE73QqxENNNeYvZMAA=') center/cover no-repeat"><img
      class="browser-frame__page"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/cli-login-approve_hu_ee30fa96a8ea860e.webp"
      srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/cli-login-approve_hu_ee30fa96a8ea860e.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/cli-login-approve_hu_c7af1bedbd1fa8b3.webp 1280w"
      sizes="(min-width: 768px) 50vw, 65vw"
      width="1400" height="875"
      alt="面板询问是否批准一次 CLI 登录"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/cli-login-approve_hu_c267548bca14bf21.webp"></span></div>
  <figcaption>cmpatch login 会请面板来批准这个终端。</figcaption>
</figure>


<h2 class="relative group">对准一个真实应用
    <div id="对准一个真实应用" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%af%b9%e5%87%86%e4%b8%80%e4%b8%aa%e7%9c%9f%e5%ae%9e%e5%ba%94%e7%94%a8" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>Patch 要求每个平台一个应用，每个应用会自动建好 Staging 和 Production 两个 deployment。我在面板里建了 <code>maru-ios</code>，又用 <code>cmpatch app create</code> 建了 <code>maru-android</code>，主要是两种方式都看看。建完应用后弹出的对话框是整个产品里对迁移最有用的一屏：两个 deployment key、SDK 需要的两个 URL，还有一句说明：deployment key 不是机密。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><span class="browser-frame__shot" style="background:url('data:image/webp;base64,UklGRoIAAABXRUJQVlA4IHYAAAAQBQCdASogABQAPuFWmkekIqEb9ABDDgT0gF8kHTL70/EPugF6lMUZ0A+0pWU0WRlAAPpGgpz7VeOvAMdDs/q/I00JZTDCozGF/p+yUbXDUjfdJacA2ZbVan+1M3EfSih3MXlM1+RWV02wNY/nmH4Pte3keQAA') center/cover no-repeat"><img
      class="browser-frame__page"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-created-keys_hu_31f66d5c03d282e7.webp"
      srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-created-keys_hu_31f66d5c03d282e7.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-created-keys_hu_ec9ad24dac45b7f9.webp 1280w"
      sizes="(min-width: 768px) 50vw, 65vw"
      width="1400" height="875"
      alt="应用创建完成的对话框，显示 Staging 和 Production 的 deployment key 以及 SDK 的 URL"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-created-keys_hu_bd9fb369cb1053b8.webp"></span></div>
  <figcaption>SDK 需要的一切，一屏看全。</figcaption>
</figure>

<p>两件小事。<code>cmpatch init</code> 当时是把项目关联到已经存在的应用上，所以不管迁移指南怎么暗示，它都不可能是第一条命令。这一点后来修好了：在交互模式下，它现在会自己给每个平台建一个应用。另外，对话框给的 API URL 是 <code>http://localhost:8080</code>，而文档和 CLI 说的是 3000。两个都能用，因为两个端口都同时提供这两种服务，但你会犯嘀咕。</p>
<p>接着我对着还没动过的应用跑了 <code>cmpatch doctor</code>，三秒钟它就找出了一个真问题。它报告 iOS 二进制版本是 2.0.0。应用其实是 2.5.1。</p>
<p>CLI 会找出 <code>ios/</code> 下所有的 <code>Info.plist</code>，如果没有一个路径里带 &ldquo;test&rdquo;，就按字母顺序取第一个。maru 有一个 WidgetKit 扩展，它的目录按字母排在应用本身的目录前面，于是 CLI 拿到的是扩展的 <code>Info.plist</code>。这个 plist 还停在 2.0.0，这是我的 bug，但后果很难看：自动检测会把每一个 iOS release 都对准一个没有任何手机在跑的版本，而且不会报任何错。更新只是永远不会到，正是我在自建服务器那篇里警告过的那种故障。Android 读 <code>versionName</code> 是对的。绕过的办法是传 <code>--target-binary-version</code> 或 <code>--plist-file</code>，我的发布脚本现在会先检查 <code>app.config.js</code> 和两个原生工程的版本一致，然后显式传入版本。后来同一个 bug 又让 <code>doctor</code> 自己的清单检查在一个运行正常的 deployment 上失败，因为它跑去找 2.0.0 版本的清单了。修好过期的 plist 之后，<code>doctor</code> 的 24 项检查全部通过。</p>
<p>Codemagic 后来修复了这个问题。CLI 现在读取的是应用 target 的 <code>Info.plist</code>，而不是扩展的；如果有不止一个 target 可能是应用，<code>cmpatch</code> 会问你是哪一个。</p>

<h2 class="relative group">JavaScript 这一侧
    <div id="javascript-这一侧" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#javascript-%e8%bf%99%e4%b8%80%e4%be%a7" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>去掉 <code>expo-updates</code>、加上 SDK，是两行的改动。把应用原来围绕更新做的那些事换过来，要多想一想。</p>
<p>maru 在启动时和每次回到前台时检查更新，最多每十五分钟一次。发现更新就下载，然后提议重启；你说不，它就在下一次冷启动时应用。设置页里还有一个手动检查，显示当前跑的是哪个 bundle，错误上报器也会给每份报告打上它来自哪个更新的标签。</p>
<p>从 SDK 源码里学到的第一件事是，它在 import 时就用 <code>TurboModuleRegistry.getEnforcing</code> 查找原生模块，模块不存在就直接抛错。maru 还有一个 Web 构建，顶层 import 会把 Web 应用整个搞挂。所以一切都走一个懒加载 SDK 的小模块，配一个什么都不返回的 <code>.web.ts</code> 孪生文件，这样还能把 SDK 彻底挡在 Web bundle 之外。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ts" data-lang="ts"><span class="line"><span class="cl"><span class="c1">// ota.ts (ota.web.ts exports a patchSdk() that always returns null)
</span></span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">Platform</span> <span class="p">}</span> <span class="kr">from</span> <span class="s2">&#34;react-native&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">type</span> <span class="nx">PatchSdk</span> <span class="o">=</span> <span class="k">typeof</span> <span class="kr">import</span><span class="p">(</span><span class="s2">&#34;@codemagic/react-native-patch&#34;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="kd">let</span> <span class="nx">sdk</span>: <span class="kt">PatchSdk</span> <span class="o">|</span> <span class="kc">null</span> <span class="o">|</span> <span class="kc">undefined</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">export</span> <span class="kd">function</span> <span class="nx">patchSdk</span><span class="p">()</span><span class="o">:</span> <span class="nx">PatchSdk</span> <span class="o">|</span> <span class="kc">null</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="p">(</span><span class="nx">sdk</span> <span class="o">!==</span> <span class="kc">undefined</span><span class="p">)</span> <span class="k">return</span> <span class="nx">sdk</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="p">(</span><span class="nx">Platform</span><span class="p">.</span><span class="nx">OS</span> <span class="o">===</span> <span class="s2">&#34;web&#34;</span><span class="p">)</span> <span class="k">return</span> <span class="p">(</span><span class="nx">sdk</span> <span class="o">=</span> <span class="kc">null</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">  <span class="k">try</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">sdk</span> <span class="o">=</span> <span class="kr">require</span><span class="p">(</span><span class="s2">&#34;@codemagic/react-native-patch&#34;</span><span class="p">)</span> <span class="kr">as</span> <span class="nx">PatchSdk</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span> <span class="k">catch</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">sdk</span> <span class="o">=</span> <span class="kc">null</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="nx">sdk</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>自动检查本身主要就是 <code>sync()</code>，它从不抛错，而是 resolve 成一个状态：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ts" data-lang="ts"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">status</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">patch</span><span class="p">.</span><span class="nx">sync</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">installMode</span><span class="o">:</span> <span class="s2">&#34;ON_NEXT_RESTART&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">mandatoryInstallMode</span><span class="o">:</span> <span class="s2">&#34;ON_NEXT_RESUME&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="p">});</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="p">(</span><span class="nx">status</span> <span class="o">===</span> <span class="s2">&#34;update-installed&#34;</span><span class="p">)</span> <span class="nx">offerRestart</span><span class="p">();</span></span></span></code></pre></div></div>
<p>SDK 对强制 release 的默认值是 <code>IMMEDIATE</code>，不管用户正在干什么都会直接重载 JavaScript。我改成了下次从后台回来时再应用，因为弄丢一篇写了一半的帖子，这个 bug 比大多数修复带来的好处都要糟。当时 <code>InstallMode</code> 是字符串联合类型，不是文档示例里暗示的那种枚举对象；现在它导出为一个常量对象，所以 <code>InstallMode.ON_NEXT_RESTART</code> 可以照文档那样用了。</p>

<h2 class="relative group">原生这一侧，当 ios/ 和 android/ 已经提交进仓库
    <div id="原生这一侧当-ios-和-android-已经提交进仓库" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%8e%9f%e7%94%9f%e8%bf%99%e4%b8%80%e4%be%a7%e5%bd%93-ios-%e5%92%8c-android-%e5%b7%b2%e7%bb%8f%e6%8f%90%e4%ba%a4%e8%bf%9b%e4%bb%93%e5%ba%93" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>迁移指南说，加完配置插件后跑 <code>npx expo prebuild --clean</code>。我在另一个 checkout 里跑了，它删掉了随包的图片、我的 Android 网络安全配置、iOS 隐私清单和 <code>Podfile.lock</code>，还把 <code>build.gradle</code> 里一个给测试工具做的修复连同 <code>Info.plist</code> 里的几百行一起回退了。不加 <code>--clean</code>，Expo 照样把两个目录清空。</p>
<p>这不怪 Patch。maru 一开始是托管的 Expo 应用，后来长出了原生定制，所以 <code>ios/</code> 和 <code>android/</code> 是提交进仓库的，EAS 拿它们原样构建。但长这样的应用多得很，指南当时没有提醒。现在有了：Expo 迁移指南分成两条路径，生成原生工程的走 prebuild，已提交原生工程的则列出需要手动应用的具体改动。</p>
<p>插件实际改的东西，其实少到可以手动完成。iOS 上，<code>AppDelegate.swift</code> 里一个 import 加一行：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="k">return</span> <span class="n">CodemagicPatch</span><span class="p">.</span><span class="n">bundleURL</span><span class="p">()</span> <span class="p">??</span> <span class="n">Bundle</span><span class="p">.</span><span class="n">main</span><span class="p">.</span><span class="n">url</span><span class="p">(</span><span class="n">forResource</span><span class="p">:</span> <span class="s">&#34;main&#34;</span><span class="p">,</span> <span class="n">withExtension</span><span class="p">:</span> <span class="s">&#34;jsbundle&#34;</span><span class="p">)</span></span></span></code></pre></div></div>
<p>Android 上，<code>MainApplication.kt</code> 里一个 import 加一个参数（这是 React Native 0.82+ 的写法；更早的版本是改写 <code>getJSBundleFile()</code>）：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-kotlin" data-lang="kotlin"><span class="line"><span class="cl"><span class="nc">ExpoReactHostFactory</span><span class="p">.</span><span class="n">getDefaultReactHost</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">  <span class="n">jsBundleFilePath</span> <span class="p">=</span> <span class="nc">CodemagicPatch</span><span class="p">.</span><span class="n">getJSBundleFile</span><span class="p">(</span><span class="n">applicationContext</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">  <span class="c1">// ...</span></span></span></code></pre></div></div>
<p>再加上每个平台三个配置值，以及删掉旧的 <code>expo-updates</code> 设置：两个工程加起来新增 13 行、删除 20 行。</p>
<p>插件会在 prebuild 时把那些配置值写成字面量，对于提交了原生工程的项目，这意味着每次构建都只能有一个写死的 deployment。我想让 preview 构建走 Staging、商店构建走 Production，用的还是同一个工程，所以这些值改成从构建环境来。<code>Info.plist</code> 里，Xcode 会展开构建设置：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"><span class="line"><span class="cl"><span class="nt">&lt;key&gt;</span>CodemagicPatchDeploymentKey<span class="nt">&lt;/key&gt;</span>
</span></span><span class="line"><span class="cl"><span class="nt">&lt;string&gt;</span>$(PATCH_IOS_DEPLOYMENT_KEY)<span class="nt">&lt;/string&gt;</span></span></span></code></pre></div></div>
<p><code>android/app/build.gradle</code> 里：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-groovy" data-lang="groovy"><span class="line"><span class="cl"><span class="kt">def</span> <span class="n">patchEnv</span> <span class="o">=</span> <span class="o">{</span> <span class="n">name</span> <span class="o">-&gt;</span> <span class="n">System</span><span class="o">.</span><span class="na">getenv</span><span class="o">(</span><span class="n">name</span><span class="o">)</span> <span class="o">?:</span> <span class="o">(</span><span class="n">findProperty</span><span class="o">(</span><span class="n">name</span><span class="o">)</span> <span class="o">?:</span> <span class="s2">&#34;&#34;</span><span class="o">)</span> <span class="o">}</span>
</span></span><span class="line"><span class="cl"><span class="n">resValue</span> <span class="s2">&#34;string&#34;</span><span class="o">,</span> <span class="s2">&#34;CodemagicPatchDeploymentKey&#34;</span><span class="o">,</span> <span class="n">patchEnv</span><span class="o">(</span><span class="s2">&#34;PATCH_ANDROID_DEPLOYMENT_KEY&#34;</span><span class="o">)</span></span></span></code></pre></div></div>
<p>这些 key 于是和 <code>EXPO_PUBLIC_</code> 那些值一起放在 <code>eas.json</code> 的各个构建 profile 里。值为空时 SDK 会安静地什么都不做，本地构建没关系，商店构建就是灾难，所以 <code>app.config.js</code> 现在会在 preview 或 production 的 EAS 构建缺了这些值、或者还指向 localhost 时直接抛错。</p>

<h2 class="relative group">第一次更新
    <div id="第一次更新" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e4%b8%80%e6%ac%a1%e6%9b%b4%e6%96%b0" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>第一个 release 我改的是引导页的大标题，不用登录就能看到，然后发布：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">./scripts/publish-update.sh ios --notes <span class="s2">&#34;Onboarding headline over the air&#34;</span></span></span></code></pre></div></div>
<p>耗时 30 秒，大部分是 Metro 和 Hermes。上传完成 0.6 秒后，服务器的 worker 就发布了清单。这个更新是一个 7.3 MB 的压缩 tarball，而我旧的导出流程产出的是 11 MB 的 Hermes bundle 加资源。</p>
<p>这里有一件事要做对：JavaScript bundle 在构建时会把 <code>EXPO_PUBLIC_</code> 那些值内联进去，所以一次更新必须用和它要落上去的那个二进制相同的值来构建，否则你发出去的 JavaScript 会连到错误的后端。我的脚本从构建那个二进制的同一个 <code>eas.json</code> profile 里加载它们。Patch 的 CI 文档现在也把这一点写清楚了，还说明了 <code>release-react</code> 本身不会读取 EAS profile。</p>
<p>然后我重新启动应用。设备日志显示整个更新检查就是对对象存储的两次请求，<code>meta.json</code> 和 <code>2.5.1/manifest.json</code>。启动三秒后 SDK 写下了一条 <code>Downloaded</code> 事件，把更新暂存好，应用弹出了重启提示。</p>
<figure><div class="phone-frame" style="aspect-ratio: 900 / 1840; --screen-radius: 15.7% / 7.2%">
    <video
      class="phone-frame__screen"
      style="left: 5.3333%; top: 2.5%; width: 89.3333%; height: 95%"
      autoplay loop muted playsinline preload="metadata"
      poster="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-update-poster.jpg" style="background:url('data:image/webp;base64,UklGRoYBAABXRUJQVlA4IHoBAAAwCgCdASogAEYAPw1oq0omIqIWagaoYxDE9IBo3u6bOACEWXWx1HDG/AwrSOYwsJmgoDuewmmxiJfqdlf28aG4OgV3Vy0nk3lgu8Wi25BY3FxW+lY1wMNQ5gAA/uqWQwe/E/6WeZpIf2UpLel/fKpwqlcmjLMeA7F4ReOblq5eH4qIOx1w7ZF3v0mxWMH8e4hZoalFig747vzom14jgdSClOC5vthxNjGbdjdmv0JuF4Bd3uw2FZbc3Dlojmgl1fUvZqyymqEqzOWLtImgLAZjJhWZgigFmKgGd+GQ0SIKjnJHHdXOZrb/cZMTM1wrOB56DkWBsUxEsixjmVu+Vb3yqJNYglAA21u7aH9XnZ18oNyTlPWugRrsPfZ+/F1gGsmkViDzBGO0f1wXrNBJimlGcHkGkCt7LH9QNjPcy1A9c2dBEltQFPx6XWi1nm9wND9YTEPiTwnjvIduwaNn9YfPJS9b+I1LMURaw77It/AhHjT2gmi4ar24AAA=') center/cover no-repeat"
      width="720"
      height="1566"
      aria-label="应用以随包 bundle 重新启动，提示有更新，然后重启进入 release v1">
      <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-update.mp4" type="video/mp4">
    </video>
    <img class="phone-frame__bezel nozoom" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/iphone-17-frame_hu_492bde446de4e1d1.webp" width="900" height="1840" alt="" aria-hidden="true" decoding="async">
  </div><figcaption>重新启动、sync() 返回 update-installed 时应用自己的提示，然后是通过 OTA 送达的 release v1。</figcaption>
</figure>


<h2 class="relative group">bug 是我的
    <div id="bug-是我的" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#bug-%e6%98%af%e6%88%91%e7%9a%84" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>然后我看了看面板。一台模拟器装了 release v1，面板却显示两次成功安装、两个活跃用户。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><span class="browser-frame__shot" style="background:url('data:image/webp;base64,UklGRmgAAABXRUJQVlA4IFwAAADwAwCdASogABQAPw1wqUqmIyGYDAQAYxDE9IABUVMd2rf8uKbf68owAP7WGYB/h1ia3xpTYkbuTZlMczaiJLdSTP+17jDH1qfCOJ+8A+IA+QScXzRlnhc+zceAAA==') center/cover no-repeat"><img
      class="browser-frame__page"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-double-counted_hu_4dd1f5d2ff813ace.webp"
      srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-double-counted_hu_4dd1f5d2ff813ace.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-double-counted_hu_13e5d2d984250bf3.webp 1280w"
      sizes="(min-width: 768px) 50vw, 65vw"
      width="1400" height="875"
      alt="Staging deployment 显示一台设备对应两个活跃用户和两次成功"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-double-counted_hu_b455b1f0b69680b5.webp"></span></div>
  <figcaption>一台模拟器，被数了两次。</figcaption>
</figure>

<p>SDK 把自己的状态和待发送的指标事件以文件形式存在应用容器里，追起来很方便。里面有两条 <code>Success</code> 事件，时间戳完全相同，id 不同。我的 hook 在挂载时用 <code>notifyAppReady()</code> 确认当前 bundle，紧接着就调用 <code>sync()</code>，而 <code>sync()</code> 自己也会调用 <code>notifyAppReady()</code>。两次调用重叠了，各自都看到这个 release 处于待确认状态，各自都记了事件。服务器按事件 id 去重，但这两条 id 不同，所以都算数了，而且这些重复是永久的。</p>
<p>我这边的修复是每次启动只做一次共享的确认，其他所有东西都等它。SDK 自己也可以防一下重叠调用，这一点我提了建议。现在它确实这么做了：重叠的 <code>notifyAppReady()</code> 调用，包括 <code>sync()</code> 内部那一次，会共用同一次确认，所以每次安装只记一次。SDK 参考文档现在也写明了 <code>sync()</code> 会自己确认就绪，用它的应用不需要再单独调用 <code>notifyAppReady()</code>。</p>
<p>舒服的地方在于发修复。这是纯 JavaScript 的改动，所以作为 release v2 发了出去，而且因为可以给 v1 上的设备发二进制差分，v2 下载下来是一个 543 KB 的 patch，而不是 7.3 MB 的 bundle，大约是原来的 7%。重启之后：一次下载、一次安装、一次成功、一台活跃设备。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><span class="browser-frame__shot" style="background:url('data:image/webp;base64,UklGRmwAAABXRUJQVlA4IGAAAADwAwCdASogABQAPw1qqksmIqGYDAQAYxDE9IABUVMd2rfRI1O5mmXAAP7WGYB/h1ia3xpTYkbuTZlMczaiJLkoVKAckjyruR4hTL7NmaqeP1qAfIJOLnmwKkXiX44AAAA=') center/cover no-repeat"><img
      class="browser-frame__page"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-v1-v2_hu_361247d6f35aa5fc.webp"
      srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-v1-v2_hu_361247d6f35aa5fc.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-v1-v2_hu_d07d239ec0e34973.webp 1280w"
      sizes="(min-width: 768px) 50vw, 65vw"
      width="1400" height="875"
      alt="发布历史显示 v1 的数字虚高，v2 正确"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-v1-v2_hu_dab633c48fa0be46.webp"></span></div>
  <figcaption>v1 的重复记录留着；v2 数得对。</figcaption>
</figure>


<h2 class="relative group">故意弄坏它
    <div id="故意弄坏它" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%95%85%e6%84%8f%e5%bc%84%e5%9d%8f%e5%ae%83" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>回滚是我最在意的功能，因为旧方案在设备端什么都没有。一个坏更新会让每次启动都崩溃，直到我注意到并把复选框取消勾选。</p>
<p>所以我发了一个 v3，在第一次渲染之前就抛错，也就是它永远没机会调用 <code>notifyAppReady()</code>。应用下载了它，提示重启，然后死回了主屏幕。</p>
<figure><div class="phone-frame" style="aspect-ratio: 900 / 1840; --screen-radius: 15.7% / 7.2%">
    <video
      class="phone-frame__screen"
      style="left: 5.3333%; top: 2.5%; width: 89.3333%; height: 95%"
      autoplay loop muted playsinline preload="metadata"
      poster="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-crashed-poster.jpg" style="background:url('data:image/webp;base64,UklGRjACAABXRUJQVlA4ICQCAADQDgCdASogAEYAPw1+rU4mJCIhKbqpIMYhieIAuzPq4M7sW3lP/kPxexnET5ASwFv8Htr8DNovWXwo2ZQynTi8ui+9q1qzPLfv97/wPQgMDj/+e/pvE9miOHoCzZC5Gv/U0oN8n33d1NMZxA4+qT/uNT35EBYJZa/w3Ts1AUToAP5vfw4j/pjBP6ZaA8LejegsfSPzEPXc0mvX+J1dMRFcTwhgh8BttzpcI4CRjUDkbGoa6UAnxK5kCSatezNL4gQf4nZeHytilXmRtp2c1xohb5/y8HBhWsukQWCAk8rKnNMQYUQJEVbasq2JgftASZSBFtiUkjtFF9K+EYtO0DOtXBWDPeHJf1TqqEHHwl4CQ1zsv9Cx+l8KPR2tUhRR8Ctso49YsumZzdxVCAKQdb9pNx77EfSYM6ALaYnzRt4qTUeUBf3ENt66RmZKq5nGflJ9lEW0oDnWjx6zoAqeJS44t1nUDDIZm1gayu9+nhUWZE+InoYr7YlMmmXX2kklVMVsT0s5xOQqPPlW4UoSUv0NgFVDavqEtwMzPqNuUIjjfwXToJhzDbgUidZqS0gSOrBna2Xj2XcOmf2KfPjtTFgKpl74NNsPw+SkvLP+XIfGRP7f4DZ3SF5r4kITD9QK1Mb4Z3frLXQeA432gyyslKobZUjhHzgpw6Lsv1z4B+zVfYG/nF6OiGZ+SPJQMFRe2LmOB4/oyDsE7meakIUBZvS1zSAAAA==') center/cover no-repeat"
      width="720"
      height="1566"
      aria-label="应用在坏 release 上崩溃后的模拟器主屏幕">
      <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-crashed.mp4" type="video/mp4">
    </video>
    <img class="phone-frame__bezel nozoom" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/iphone-17-frame_hu_492bde446de4e1d1.webp" width="900" height="1840" alt="" aria-hidden="true" decoding="async">
  </div><figcaption>v3 启动即崩。</figcaption>
</figure>

<p>下一次启动又跑了 v3，又崩了，这让我很意外，因为文档说在 <code>notifyAppReady()</code> 之前崩溃的 bundle 会被回滚。源码解释了原因：SDK 允许三次未确认的启动，之后才判定为崩溃，因为一次未确认的启动也可能只是 iOS 在任何 JavaScript 跑起来之前就杀掉了一个健康的进程。第四次启动回到了 v2。</p>
<figure><div class="phone-frame" style="aspect-ratio: 900 / 1840; --screen-radius: 15.7% / 7.2%">
    <video
      class="phone-frame__screen"
      style="left: 5.3333%; top: 2.5%; width: 89.3333%; height: 95%"
      autoplay loop muted playsinline preload="metadata"
      poster="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-rolled-back-poster.jpg" style="background:url('data:image/webp;base64,UklGRsABAABXRUJQVlA4ILQBAABQCgCdASogAEYAPw1mq0umIqGU2q7YYxDE9IBowO6mweBInrUPWk42PSTT65hMmOGGOXZWA/sd5q9BGdjSK2j84FuUL93nyJVQuphNZ6mwXQhv8NVWhs+Q6BIAAP74ukd3WXEH+9Z7Rrx8W8zZkkK5+g1e2Lc8Yi325om3Qy3bb7uYsUutPzhS99cwA1kptzZhyUOs2MW6lH9eP8+SPePVMJGvfSIxSO6tL43kYr+PfLzJw/oJabDsUcKslfz5t3nFCXsiVKRSWBi80g/4Y8CJZiDrEvRejhn6wF7DlE4cfLc64tC8OpWtwMjLNLzfe0pK5MjRdPbq4v5sKsY7T49CjMzJz033ddGNJ1Vmp+9decCnIDCYl2pLqRBhrM5E+D4Cw6TfkPAN/WpX0LXCs9Wr8ACcRRwajxQnbjxLU1tKX+yJyrshjPphgACyyYJKjidt2xw5zVQZcF6XykRe430a0dWMKdcBvnMqq2qBswoqRDNp4NIHmM7r87FSOG3y5ScC9wPZH2OoU+6Am86Nz+s2Tk/J+sj1gZFVQqfqXFWH4AEGF/cO+yLfluiKfZvqAOcwbgAA') center/cover no-repeat"
      width="720"
      height="1566"
      aria-label="自动回滚后，应用再次运行在 v2 上">
      <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/app-rolled-back.mp4" type="video/mp4">
    </video>
    <img class="phone-frame__bezel nozoom" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/iphone-17-frame_hu_492bde446de4e1d1.webp" width="900" height="1840" alt="" aria-hidden="true" decoding="async">
  </div><figcaption>第四次启动：回滚到 v2，没有任何人碰过服务器。</figcaption>
</figure>

<p>然后设备自己上报了这次失败，类型是 <code>crash_rollback</code>，面板把它记在了 v3 名下。这个设计合理，但有必要把它的含义说白：一个坏 release 会让每个用户崩三次启动才能恢复，而当时文档没有提这个数字。现在提了，而且这个额度可以配置，原生侧用 <code>CodemagicPatchMaxLaunchAttempts</code>，或者用 Expo 插件的 <code>maxLaunchAttempts</code>。这正是先发 Staging、再小比例发 Production 的理由。</p>
<p>替其他所有人叫停一个坏 release 是一条命令，不到一秒：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">cmpatch release rollback --app maru-ios --deployment Staging</span></span></code></pre></div></div>
<p>它不改写历史。它把上一个 release 重新发布成一个新的（v4，标记为 v2 的回滚），所以崩溃的那个 release 连同它的失败计数一起留在列表里，这是诚实的记录。面板上通过一个对话框做同样的事。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><video
      class="browser-frame__page"
      autoplay loop muted playsinline preload="metadata"
      poster="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/dashboard-rollback-poster.jpg"
      style="background:url('data:image/webp;base64,UklGRmwAAABXRUJQVlA4IGAAAABwBACdASogABQAPw1qp0emIyGYBABjEMT0gGfQEs2nvxX7EOeFbRn3H5Si4AD+1iXJGzIunVk/ewlUVdIUbFiwAGX5QAkFFcZDl2at4PkETvjCXCOVoXFdscz2ut9AAAA=') center/cover no-repeat"
      width="1280"
      height="800"
      aria-label="在面板里回滚 Staging：上一个 release 被重新发布为 v4">
      <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/dashboard-rollback.mp4" type="video/mp4">
    </video></div>
  <figcaption>在面板里回滚：v2 以 v4 的身份回来，v3 留在列表里。</figcaption>
</figure>

<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><span class="browser-frame__shot" style="background:url('data:image/webp;base64,UklGRmoAAABXRUJQVlA4IF4AAAAwBACdASogABQAPw1op0emIyGYBABjEMTygAFRZbu1b6Gdq9jYHm/TLAAA/tYZgH+HWJrfGlNiRvwNU+RVn1Uhl5QjE2FNRxQPa3YDnfLX9O0wDNn7xOtAkLPDgAAA') center/cover no-repeat"><img
      class="browser-frame__page"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-after-rollback_hu_6a96ca1588cc6310.webp"
      srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-after-rollback_hu_6a96ca1588cc6310.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-after-rollback_hu_5552e433d6a65a3f.webp 1280w"
      sizes="(min-width: 768px) 50vw, 65vw"
      width="1400" height="875"
      alt="回滚后的发布历史，v4 标记为回滚，v3 显示一次失败"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/staging-after-rollback_hu_5066c51b1ba693c2.webp"></span></div>
  <figcaption>v4 是回滚；v3 留着它的失败记录。</figcaption>
</figure>


<h2 class="relative group">Android
    <div id="android" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#android" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>Android 有两个意外，都不是 Patch 的问题。我给 SDK 加的 R8 keep 规则放在 <code>app.config.js</code> 里，而它只能通过 prebuild 才能到达原生工程，所以我第一个 release 构建等于无意中测试了 SDK 在没有 keep 规则的情况下能不能扛住 R8。能：R8 把它所有的类都重命名了，更新照样下载、安装、回滚，一切正常。另外，刚冷启动的模拟器加上还占着内存的 Gradle，慢到我的第一次测试在 SDK 完成那个早已开始的下载之前 45 秒就放弃了。</p>
<p>Release v1 应用成功，一次成功、一台活跃设备，一个会崩的 v2 在同样的三次启动额度之后回滚了。</p>
<figure>
  <div class="phone-frame" style="aspect-ratio: 900 / 1892; --screen-radius: 9.85% / 4.43%"><span class="phone-frame__screen phone-frame__ph" aria-hidden="true" style="left: 4.889%; top: 2.326%; width: 90.222%; height: 95.349%; background:url('data:image/webp;base64,UklGRsgBAABXRUJQVlA4ILwBAABQCwCdASogAEcAPw1wr06mIqIhJngMAMYhiekAzRAKJZ22yvEtm7/GFRCOt1Z6YnyGNWf+i7i0ewagB55W+rOp9DBjbctVlnDXK6lGDu9FH315DSWJUMBYkPGJY2+xw/B5QDAA/vURG5LVrYKJoO2SXy+UxQiUlovs8pxF48eKxgmVxH4hV0qd23H4fTbOXId4reHVkO/ZtsoHNdCHkv0JWiIqSQvxGntYFegdbOEkel+at+Jvs/b4yghmeIXnBH7M31JdyN1H2WvMPx2TwLZfiUh7Vs/c0xs3ET28MPX4PV32jfA2Qo55LcWZBHZVnPmnDwZLLo2Dv++B0SqBKWqbTWPQKOgzF+6YGKB7vcORmV6iyLh5aW30GEJ6lcPq8nat/61jd9i9CZePrzdLJPqGGJyPCbsjPkfhTd6BEdIQraUcOjRfSxAroG5B9nslpJZA63tGk2R93MKzS48w8pEUJKeCNc9lq7Q91gnOgYXePvVHH49kJkJCf5DnRUSgdBqJS0Dh6nG2R7OcW67l22CzkV09rMSoVJlTLhktX5d3Ximn/zbkXSgGUos1pjcQR73ncJ+50rXoCD05SAA=') center/cover no-repeat"></span>
    <img
      class="phone-frame__screen"
      style="left: 4.889%; top: 2.326%; width: 90.222%; height: 95.349%"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/android-after-v1_hu_a5ee68e09a427bed.webp"
      width="600" height="1333"
      alt="Android 应用显示通过 OTA 送达的大标题"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/android-after-v1_hu_a5ee68e09a427bed.webp">
    <img class="phone-frame__bezel nozoom" src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/pixel-8-frame_hu_52e6b4e761a590c9.webp" width="900" height="1892" alt="" aria-hidden="true" decoding="async">
  </div>
  <figcaption>Android：回滚后重新回到 v1。</figcaption>
</figure>


<h2 class="relative group">顺利路径之外
    <div id="顺利路径之外" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e9%a1%ba%e5%88%a9%e8%b7%af%e5%be%84%e4%b9%8b%e5%a4%96" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>更新能到、能回滚是核心，但一个团队天天用的是其他那些功能，所以我一个一个过了一遍。</p>
<p>灰度发布是确定性的，这点我喜欢。<code>md5(deviceId + &quot;-&quot; + releaseLabel)</code> 的前八位十六进制数字对 100 取模，小于灰度百分比的设备就在圈内，所以同一台手机对某个 release 要么一直在、要么一直不在。我算出模拟器在下一个 release 里落在 91 号桶，按 25% 发布，模拟器果然什么都没收到。用 <code>cmpatch release patch</code> 提到 95%，不到一秒，下次启动它就更新了。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><video
      class="browser-frame__page"
      autoplay loop muted playsinline preload="metadata"
      poster="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/dashboard-rollout-poster.jpg"
      style="background:url('data:image/webp;base64,UklGRnIAAABXRUJQVlA4IGYAAAAQBACdASogABQAPw1qqEemIyIYBABjEMT0gGH0Es2nvxX9G/4/1g7tAAD+1iXJGzIunVcHqQBmnStoD1oAHJUjpBT6bKy8GQx+Yo2Ka5cGJlghQl6jWcyOWHRQDYW9x5JJDLafQAA=') center/cover no-repeat"
      width="1280"
      height="800"
      aria-label="在面板里把一个 release 的灰度从 25% 提到 95%">
      <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/dashboard-rollout.mp4" type="video/mp4">
    </video></div>
  <figcaption>把部分灰度从 25% 提到 95%，没有重新发布。</figcaption>
</figure>

<p>接着我的下一个 release 失败了，返回 409：&ldquo;deployment has an active rollout below 100 percent&rdquo;。每个 deployment 同时只允许一个部分灰度，所以你得先把金丝雀发完、禁用或者回滚，才能发别的。这合理，也有文档，但一条每次合并都发布的流水线会在金丝雀进行到一半时撞上它。我反馈之后，CLI 在这里会把话说清楚了：如果是一个进行中的部分灰度挡住了你，它会告诉你等也没用，以及怎么把灰度发完或禁用；如果是另一个发布任务还在跑，它会让你用 <code>release inspect --wait</code> 等着。文档现在也有一节专门讲按顺序进行的发布变更。</p>
<p>强制 release 用的是 SDK 的 <code>mandatoryInstallMode</code>。我设的是下次回到前台时应用，应用下载了更新并弹出提示，我无视提示，把应用切到后台再切回来，新版本就直接在那里了。</p>
<p>禁用一个 release 做的不只是停止提供它。我一禁用最新的那个，清单就立刻指向了仍然启用的最新 release，禁用版本上的设备会被推一个回到它的 patch。把某个二进制版本的 release 全部禁用，清单的目标就变成 null，SDK 会把应用退回到它随二进制自带的 bundle。我的更新 hook 起初没有对这种情况弹提示，现在有了。</p>
<p>从 Staging 提升到 Production 不到一秒，而且复用的正是测试过的那个包，同样的哈希和备注，不会重新构建。它还接受一个灰度百分比，所以“提升到 Production 的 10%”就是一条命令。</p>
<p>构建和发布也可以拆成两步。<code>cmpatch bundle</code> 产出一个 <code>.cmpatch</code> 产物，面板的 &ldquo;Bundle upload&rdquo; 选项会在上传前读取它：平台、目标版本、指纹、签名状态、大小和打包器。这适合 CI 构建产物、再由别人决定什么时候发布的场景。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><video
      class="browser-frame__page"
      autoplay loop muted playsinline preload="metadata"
      poster="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/dashboard-upload-poster.jpg"
      style="background:url('data:image/webp;base64,UklGRnwAAABXRUJQVlA4IHAAAAAwBACdASogABQAPw14sE+mI6IhKAgAxiGJ6QAAM7aVPPd3tO2d2B9IEAAA/tYlyRsyLp1nLc5Hh5nniWZ+UIxN4AAKrWhTSPPLnDPJV90MvTw1QAmDXcvY3C3ghY+Uo+Wdxkjji3HNEgzIPqpIwAAA') center/cover no-repeat"
      width="1280"
      height="800"
      aria-label="在面板里上传 .cmpatch 产物：先读出平台、版本、指纹和大小，然后警告指纹不一致">
      <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/dashboard-upload.mp4" type="video/mp4">
    </video></div>
  <figcaption>bundle 上传：面板先读产物，然后指纹保护介入。</figcaption>
</figure>

<p>也是在这里，我真正撞上了指纹保护。修好过期的 widget plist 之后，服务器以 409 拒绝了我的下一个 release，因为原生工程的指纹和它为 2.5.1 记录的那个对不上了。Android 上，改一下 <code>app.config.js</code> 里的注释就够触发了，因为 Expo 把应用配置也算进指纹。面板把同样的检查显示成一条警告，带两个指纹和一个 &ldquo;Upload anyway&rdquo; 按钮。这两次已安装的二进制上都没有任何原生的东西变过，所以覆盖是对的。但在真实使用里，诚实的答案几乎总是升版本号、重新做一次商店构建，我的发布脚本现在遇到这种情况就会这么说。</p>
<p>代码签名用的是 RS256：CLI 用 RSA 私钥给包的哈希签名，SDK 用编译进二进制的公钥校验。公钥以一行 base64 的形式放进去，正好契合我走构建设置的做法，两个平台我都测了。应用里带了公钥之后，未签名的 release 在下载前就被拒了。给应用打开 &ldquo;require code signing&rdquo; 后，服务器拒绝了未签名的发布，错误信息里写明了修法并链接到指南。签名的 release 正常安装，SDK 记录签名为已验证。当我禁用签名的那个 release、服务器退回到一个更早的未签名 release 时，SDK 也把它拒了。要注意的是，公钥必须在你发出的第一个二进制里就带上，因为更新没法把它加进去。</p>
<figure>
  <div class="browser-frame">
    <div class="browser-frame__bar" aria-hidden="true">
      <span class="browser-frame__dots"><i></i><i></i><i></i></span>
      <span class="browser-frame__url">localhost:8080</span>
    </div><span class="browser-frame__shot" style="background:url('data:image/webp;base64,UklGRnAAAABXRUJQVlA4IGQAAABwBACdASogAB0APw14sE+mI6IhKAgAxiGJ6QAAM+3OuAEp3oUrP1GNW2QgAAD+1hmAf4eqLtdnP/9v1g2ZTHRXrrujcZyW6apQhqigB3MdqokDYA7HESmkf+QYJtIlWU+VYAAA') center/cover no-repeat"><img
      class="browser-frame__page"
      src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/signed-release-detail_hu_23c3bd38e0daa226.webp"
      srcset="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/signed-release-detail_hu_23c3bd38e0daa226.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/signed-release-detail_hu_2173e76e5a1b2cec.webp 1280w"
      sizes="(min-width: 768px) 50vw, 65vw"
      width="1400" height="1264"
      alt="Release 详情显示签名为 Signed, sha256"
      loading="lazy" decoding="async"
      data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/signed-release-detail_hu_f18ca5bb6112ee2a.webp"></span></div>
  <figcaption>一个签过名的 release。</figcaption>
</figure>

<p>团队和 CI 也都覆盖到了。成员会拿到四种团队级角色之一（owner、admin、developer、viewer），邀请会一直等到对方第一次登录。个人访问 token 在空的 home 目录下也能用，通过 <code>--token</code> 或环境变量传入都行，token 列表会显示每一个上次使用的时间。我还写了一个手动触发的 CI workflow，在 Linux runner 上跑同一个发布脚本，签名密钥来自 secret，不过还没跑过，因为它需要托管的服务器。</p>
<p>有一个工具当时我会跳过，<code>cmpatch debug ios</code>。它按 &ldquo;OTA&rdquo; 不区分大小写过滤系统日志流，而这会匹配到 &ldquo;Rotation&rdquo;，于是一次二十秒的应用启动产出了满屏的 SpringBoard 消息，应用自己的一条都没有。这已经修好了：它现在只显示带 SDK 标记的行。SDK 本身日志不多，主要是错误和开发构建下的警告，所以输出会很安静。你可能看到的那条 <code>getpwuid_r</code> 警告来自 <code>xcrun simctl</code>，不是 Patch。</p>

<h2 class="relative group">到底有多难
    <div id="到底有多难" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%88%b0%e5%ba%95%e6%9c%89%e5%a4%9a%e9%9a%be" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>Codemagic 想听我的看法，那就尽量说得直白。</p>
<p>试用很容易。两条命令、几分钟，你就有了真正的服务器、一个带演示数据的面板，和一个可以对准自己应用的 CLI。我会说这是头一个小时里最好的部分。</p>
<p>集成 SDK 是中等工作量，而且难点大多在你自己的项目里，不在 Patch。在一个原生目录是生成出来的新 Expo 应用上，确实就是插件加几行替换 <code>expo-updates</code> 调用的代码。在 maru 这样的应用上，原生工程已提交、有 widget 扩展、有 Web 构建、有 R8 和构建 profile，活儿都在边边角角。我得手动应用原生改动来避开 prebuild，把配置改成构建时注入好让 Staging 和 Production 构建能不一样，还要把 SDK 挡在 Web 之外。我还得保证更新里的 JavaScript 和二进制用同样的环境构建。搞明白之后没有一件是难的。我做的时候，这些大多不在文档里，不过已提交原生工程的路径和 bundle 构建时的环境，现在都写进去了。</p>
<p>日常使用很好。发布是一条命令，半分钟左右。灰度、提升、禁用和回滚，从 CLI 或面板操作都不到一秒，错误信息会说出了什么问题、该怎么办。服务器的那些保护（指纹检查、同时只能一个金丝雀、签名）严格得不止一次拦住我做错事。</p>
<p>在生产环境跑它是更大的承诺。它是一套带 Postgres 和对象存储的 Docker Compose 栈，你得托管、备份、升级，还需要两个域名和一个 OAuth 应用。对已经在跑服务器的团队，这是一个安静的下午。对那些正因为不想碰服务器才用 EAS 的团队，这才是切换的真实成本，比 SDK 那部分工作更大。</p>
<p>按挂钟时间算，我 12:29 装好 CLI，13:34 第一个更新在模拟器上应用成功，其中半小时是一次 Xcode 构建卡住了，原因和 Patch 无关。这篇文章里的所有东西，两个平台，都在下午过半之前做完了，托管服务器不算在内。</p>
<p>最耗我时间的几件事，按顺序：<code>expo prebuild --clean</code> 抹掉了我提交的原生工程，然后是研究怎么手动接好一切；iOS 版本检测的 bug，它会把更新发给一个没人在跑的版本；重复计数的安装，虽然是我自己造成的，但任何人都很容易重蹈，因为 <code>sync()</code> 自己会调 <code>notifyAppReady()</code>；还有没写进文档的三次启动崩溃额度，在一次测试进行到一半时把我吓了一跳。再往后是一些本身正确、但需要规划的事：无害的原生相关改动触发指纹保护，每个 deployment 同时只能一个金丝雀，以及不能重叠的生命周期任务，一旦脚本要连着做几件事，这就很要紧。剩下的都是小事：首次运行时静默的搭建过程、一条吵闹的调试命令，还有几个当时和代码对不上的文档示例。</p>
<p>这些我都连同细节一起写给了 Codemagic，到 9 月 23 日，大部分已经修复：版本检测、重叠的确认、prebuild 的提醒、崩溃额度、静默的搭建过程、调试命令、<code>InstallMode</code> 的示例，以及发布任务或金丝雀挡路时给出的报错。还没解决的都是小事：面板显示 API 在 <code>:8080</code>，而其他地方都说 <code>:3000</code>；SDK 在 Web 和 Jest 里一 import 就抛错；以及文档里的几处空白。</p>

<h2 class="relative group">上生产
    <div id="上生产" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%8a%e7%94%9f%e4%ba%a7" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>上面的一切都是在评估栈上跑的。生产就是同一个应用、同一套脚本对准一台真实的服务器，下面是 maru 的计划。</p>
<!-- 编辑备注：本节是操作步骤。真正切换之后，替换成实际发生的情况（主机、耗时、出了什么问题）。 -->
<p>官方支持的服务器部署方式是 Docker Compose 安装：一台开放 80 和 443 端口的 Linux 机器、两个域名（一个给 API 和面板，一个给下载），以及一个用于登录的 GitHub OAuth 应用，没有它服务器不会启动。安装器负责剩下的事，包括 TLS：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">scripts/selfhost/install.sh <span class="se">\
</span></span></span><span class="line"><span class="cl">  --api-domain updates.example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --storage-domain storage.updates.example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --email you<span>@</span>example.com <span class="se">\
</span></span></span><span class="line"><span class="cl">  --github-oauth-client-id &lt;id&gt; --github-oauth-client-secret &lt;secret&gt;</span></span></code></pre></div></div>
<p>它会写一个 <code>.env.selfhost</code>，里面是数据库和存储的密钥，应该放进你的密码管理器。</p>
<p>不过你不一定要用自带的数据库和存储，这正是它能嵌进我这种栈的原因。maru 的 API 已经跑在 Fly.io 上，文件放在 Tigris，Patch 在两者上都能工作。Compose 文件底下，服务器就是一个以 <code>MODE=all</code>（API 和 release worker 一起）运行的容器，需要一个 Postgres 数据库、S3 兼容存储，和一个供文件访问的公开 HTTPS URL。也就是一个用仓库的 Dockerfile 构建的 Fly 应用（目前还没有发布的镜像，所以由 <code>fly deploy</code> 来构建）、一个 Fly Postgres 数据库，和一个 Tigris 桶：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">MODE</span><span class="o">=</span>all
</span></span><span class="line"><span class="cl"><span class="nv">DATABASE_URL</span><span class="o">=</span>postgresql://…            <span class="c1"># Fly Postgres</span>
</span></span><span class="line"><span class="cl"><span class="nv">STORAGE_ADAPTER</span><span class="o">=</span>s3
</span></span><span class="line"><span class="cl"><span class="nv">S3_ENDPOINT</span><span class="o">=</span>https://fly.storage.tigris.dev
</span></span><span class="line"><span class="cl"><span class="nv">S3_REGION</span><span class="o">=</span>auto
</span></span><span class="line"><span class="cl"><span class="nv">S3_BUCKET</span><span class="o">=</span>myapp-patch
</span></span><span class="line"><span class="cl"><span class="nv">S3_FORCE_PATH_STYLE</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="nv">PUBLIC_BASE_URL</span><span class="o">=</span>https://myapp-patch.fly.storage.tigris.dev/codemagic-patch</span></span></code></pre></div></div>
<p>两点提醒。在 Compose 之外运行，仓库里的文档把它定位为参考材料，而不是这个首个开源版本里受支持的路径，所以在 Fly 上，升级和备份得靠你自己。我也还没这样部署过；这是计划，不是报告。另外，如果你读过我写 <a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-09-scale-to-zero-504s/" >Fly 缩容到零</a>的那篇，记得至少留一台机器在跑。手机做更新检查时从不等 API，因为清单直接来自存储，但不然的话，每一次指标上传和每一个 release 任务都会从一次冷启动开始。</p>
<p>Tigris 是我最期待的部分。maru 的文件本来就在那儿，而且它在每次应用启动都要访问的那个 URL 前面放了一层 CDN。这么做的话要留意清单的缓存：用普通的 base-URL 分发适配器时，Patch 会把清单以 <code>no-cache</code> 提供，因为它没法清 CDN，而一份按自己 TTL 缓存的清单会一直提供你刚刚回滚掉的那个 release。配置参考现在在 <code>MANIFEST_CACHE_CONTROL</code> 下写明了这一点，文档站也讲到了 S3 兼容存储。</p>
<p>在托管服务器上，重新建一遍应用，把新的 key 放进 <code>eas.json</code> 的 <code>preview</code> 和 <code>production</code> profile（分别是 Staging 的 key 和 Production 的 key），再创建一个用于发布的 token：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">cmpatch token create --name ci</span></span></code></pre></div></div>
<p>想要代码签名的话，现在就定：生成生产环境的密钥对，私钥作为 CI secret 保管，公钥放进构建 profile，然后给两个应用都打开 &ldquo;require code signing&rdquo;。第一个 Patch 二进制还需要一个新版本号，因为商店里已有的二进制跑的是 <code>expo-updates</code>。先用 preview profile 构建给 TestFlight 和 Play 内部测试，交给任何人之前，先确认 key 真的进了构建出来的 <code>Info.plist</code> 和 Android 资源。这是我本地测试唯一没有覆盖到的一环，因为环境变量是我手动导出的。然后发到 Staging，确认每个测试者一次下载、一次成功，之后才构建商店版本。</p>
<p>生产 release 从小开始，逐步放大：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">./scripts/publish-update.sh ios --production --rollout <span class="m">10</span>
</span></span><span class="line"><span class="cl">cmpatch release patch --app maru-ios --deployment Production --label v1 --rollout-percentage <span class="m">100</span></span></span></code></pre></div></div>
<p>旧服务器这期间继续开着。所有还没更新的 2.5.1 副本仍然在向它检查，给它们的热修复也仍然走旧脚本。等日志显示那些请求停了，旧服务器连同它的发布脚本和密钥就可以全部删掉。</p>

<h2 class="relative group">第一次原生升级
    <div id="第一次原生升级" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e4%b8%80%e6%ac%a1%e5%8e%9f%e7%94%9f%e5%8d%87%e7%ba%a7" aria-label="锚点">#</a>
    </span>
    
</h2>
<p><em>2026 年 10 月 16 日补充。</em></p>
<p>从 10 月初开始，maru 的生产更新就交给 Patch 来发了。那之后的第一次原生发布是升级到 Expo SDK 58：React Native 0.88，Android 上还有 Gradle 插件的一个新大版本。原生改动没法 OTA，所以这是一个新的二进制 2.6.0，而我的发布脚本在这个二进制存在之前会拒绝发 2.6.0 的更新。两个平台第一次就都干净地构建成功了。</p>
<p>上面的生产部分说过，交给任何人之前，先确认 key 真的进了构建出来的 <code>Info.plist</code> 和 Android 资源。这次我真的查了，而这一节正是因为这次检查才有的。iOS 构建里四个 Patch 设置都在。Android 构建里一个都没有：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">bundletool dump resources --bundle<span class="o">=</span>build.aab --values <span class="p">|</span> grep -A1 <span class="s2">&#34;string/Codemagic&#34;</span></span></span></code></pre></div></div>
<p>这条命令对 2.5.11 的构建打印出四个 key，对 2.6.0 什么都没打印。问题不在环境变量：Gradle 的 <code>generateReleaseResValues</code> 四个都写了。它们是之后被 release 构建的资源缩减器（resource shrinker）删掉的，而它在 Android Gradle Plugin 9 里激进了很多。同一个应用的资源从 9,240 个降到了 7,116 个。SDK 用 <code>getIdentifier</code> 按名字读取配置，缩减器看不到这种用法，于是把这四个字符串当成没用的删掉了。缺失的字符串读出来是空的，而空意味着&quot;没有更新&quot;。什么都不会失败。Android 2.6.0 会正常安装、正常运行，却永远收不到更新，唯一的迹象是面板上一台 Android 2.6.0 设备都没有。</p>
<p>修复是一个资源文件，告诉缩减器保留这四个字符串：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-xml" data-lang="xml"><span class="line"><span class="cl"><span class="c">&lt;!-- android/app/src/main/res/raw/codemagic_patch_keep.xml --&gt;</span>
</span></span><span class="line"><span class="cl"><span class="nt">&lt;resources</span> <span class="na">xmlns:tools=</span><span class="s">&#34;http://schemas.android.com/tools&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="na">tools:keep=</span><span class="s">&#34;@string/CodemagicPatch*&#34;</span> <span class="nt">/&gt;</span></span></span></code></pre></div></div>
<p>别把它叫做 <code>keep.xml</code>：React Native 的 bundle 任务已经会为你的 JavaScript 资源生成一个 <code>raw/keep.xml</code>（图片和字体能幸存就是因为它），两个文件会冲突。这条规则更合适的位置是 SDK 本身，因为库的 keep 文件会自动合并进应用；而 release 构建在没有 deployment key 的情况下启动时，只要有一条警告，就能把这种悄无声息的情况变成看得见的。这和前面 iOS 版本检测的 bug 是同一类失败：什么都不报错，更新就是永远不来。</p>
<p>同一次检查还发现了第二个问题，跟 Patch 无关，但出于另一个原因值得知道。Android 的 release 构建一启动就崩溃，而且崩了两次，原因是 Expo 自己模块里的两个不同问题。第一个是 Expo 的 widget 模块没能注册它的原生类，所以应用在任何 JavaScript 运行之前就挂了。修好之后，应用能走到启动 JavaScript 这一步，然后就停住了，因为有三个已经迁到 Expo 新模块系统的模块从来没被注册。这两种情况 Patch 的崩溃回滚都帮不上忙，因为根本没有可以回滚的更新。它保护你不受坏更新的影响，而不是坏二进制。不管用不用 Patch，原生升级在上商店之前都得在真机或模拟器上装好、打开一次。</p>
<p>同一轮测试还带出了一件小事。<code>sync()</code> 失败时会返回 <code>&quot;error&quot;</code>，除非应用跑在开发模式下，否则不会告诉你原因，所以 release 构建只能在日志里记一句出错了。现在我的 hook 在 sync 失败后会调用一次 <code>checkForUpdate()</code>，把它抛出的错误记下来，我就是这样发现问题不是服务器坏了，而是一个本地模拟器构建的 Patch URL 是空的（<code>unsupported URL</code>）。如果最后一次的错误在 release 构建里也能读到，会有帮助。</p>
<p>我的原生发布检查清单现在多了以前没有的三行：从构建出来的 <code>.ipa</code> 和 <code>.aab</code> 里导出 Patch 设置，把 deployment key 和构建 profile 对一遍，以及在提交前启动 release 构建本身，而不是 debug 构建。</p>

<h2 class="relative group">想对正在付 Expo 账单的人说的话
    <div id="想对正在付-expo-账单的人说的话" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%83%b3%e5%af%b9%e6%ad%a3%e5%9c%a8%e4%bb%98-expo-%e8%b4%a6%e5%8d%95%e7%9a%84%e4%ba%ba%e8%af%b4%e7%9a%84%e8%af%9d" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>如果你付费用 EAS Update 是因为搭服务器看起来太费事，Patch 是一个实在的答案：你确实要跑一台服务器，但那是一套 Compose 栈和一个安装器，不是你要维护的代码。和我自己搭的那套相比，你会得到灰度发布、每个 release 的安装和失败数字、二进制 patch、指纹保护、代码签名、设备端的崩溃回滚，和一个回滚按钮。这些我一个都没做过。</p>
<p>代价是：在任何人收到 Patch 更新之前先要发一个新二进制，因为 SDK 得进到应用里；一台要持续升级和备份的服务器；release 坏得够彻底时每个用户三次崩溃启动（默认值）；以及原生工程已提交的话，一些手工活。它也还年轻。这是 0.3.0 版本，我碰到了一个版本检测 bug、一条吵闹的调试命令和文档里的几处空白，还自己造了一个 SDK 本可以防住的 bug。版本检测和调试命令后来都修好了，文档的空白大多补上了，SDK 现在也能防住我犯的那个错。这些都没有挡住迁移，而且全都看得见，在 CLI 里、在面板里、或者在设备上 SDK 自己的文件里，这一点我的旧方案可说不上。</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-09-13-moving-to-codemagic-patch/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>Zustand vs React Query（TanStack Query）vs AsyncStorage：状态该放在哪里</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-05-05-zustand-vs-react-query/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-05-05-zustand-vs-react-query/</guid>
      <pubDate>Tue, 05 May 2026 00:00:00 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>React</category>
      <category>React Native</category>
      <category>Zustand</category>
      <category>React Query</category>
      <category>TanStack Query</category>
      <category>AsyncStorage</category>
      <category>State Management</category>
      <category>Mobile Development</category>
      <category>Web Development</category>
      <description>Zustand 和 React Query 不是二选一：React Query（TanStack Query）缓存服务器状态，Zustand 管客户端状态，AsyncStorage 保存必须扛过重启的数据。我在 React 和 React Native 里怎么在三者之间划分状态，Zustand 和 React Query 怎么一起用，以及三者怎么组合出真正能用的离线模式。</description>
      <content:encoded><![CDATA[<p>Zustand 和 React Query 并不互相竞争，所以 &ldquo;Zustand 还是 React Query&rdquo; 这个问题，真正的答案通常是：两个都要。React Query（现在以 TanStack Query 的名字发布）管的是服务器状态，也就是归服务器所有的数据，由它负责拉取、缓存、去重，并在数据过期时重新拉取。Zustand 管的是客户端状态，只有你的应用自己知道的东西，比如当前打开的是哪个标签页、填了一半的表单里写了什么。大多数应用两个一起用；到了 React Native 里，AsyncStorage 是第三块，负责所有必须扛过重启的数据。这篇文章剩下的部分讲我把这几条线画在哪里（附代码），以及三者怎么合起来，做出一个离线也能用的应用。</p>
<p>我正在做的报价 App 有一条硬性要求：没信号也得能用。报价都是上门时在现场做的，而现场经常是毛坯房或者地下室，信号根本靠不住。正是这条约束，逼着我认真回答一个大多数 React 项目都含糊对付的问题：每种状态到底该放在哪里？</p>
<p>最常见的翻车方式，是把所有东西塞进同一个 store。API 缓存、用户偏好、表单状态、认证令牌，全搅在同一个 Redux 大泥球里。可这些状态的性质和生命周期各不相同，各有各的合适工具。Zustand、React Query、AsyncStorage 每个都恰好把一个问题解决得很好。边界画清楚了，架构基本就自己理顺了。</p>

<h2 class="relative group">状态分三种
    <div id="状态分三种" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%8a%b6%e6%80%81%e5%88%86%e4%b8%89%e7%a7%8d" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>聊库之前，先弄清楚自己到底在管理什么。</p>
<p>客户端状态只存在于应用运行时：UI 开关、选中的标签页、表单输入、弹窗开没开。上游没有谁拥有它，进程一结束它就没了。</p>
<p>服务器状态不一样。它的主人是服务器，应用手里只有一份本地副本。用户资料、商品列表、通知、动态流。你的副本会过期，需要重新拉取，而且此刻别的客户端可能正看着另一个版本。</p>
<p>持久化状态是那些必须扛过重启的数据：认证令牌、引导完成标记、缓存的偏好、离线数据。它存在设备本身上。</p>
<p>大多数应用三种都有。大多数烂摊子，都是拿一个工具硬管三种状态造成的。</p>

<h2 class="relative group">Zustand：管客户端状态
    <div id="zustand管客户端状态" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#zustand%e7%ae%a1%e5%ae%a2%e6%88%b7%e7%ab%af%e7%8a%b6%e6%80%81" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>Zustand 是个没什么仪式感的小状态库。没有 provider，没有模板代码，没有一层套一层的 context。建个 store，组件里直接用，要学的基本就这些。</p>
<p>它适合的场景：多个组件共享同一份 UI 状态（侧边栏开关、当前筛选条件、选中的项目）；不来自 API 的应用级状态（主题、语言、启动时读的功能开关）；以及真正的客户端逻辑，比如购物车计算或多步表单向导。凡是需要同步、可预测地更新的，基本都归它。</p>
<p>一个基础的 store：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">create</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;zustand&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">interface</span> <span class="nx">AppState</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">theme</span><span class="o">:</span> <span class="s1">&#39;light&#39;</span> <span class="o">|</span> <span class="s1">&#39;dark&#39;</span>
</span></span><span class="line"><span class="cl">  <span class="nx">sidebarOpen</span>: <span class="kt">boolean</span>
</span></span><span class="line"><span class="cl">  <span class="nx">selectedFilters</span>: <span class="kt">string</span><span class="p">[]</span>
</span></span><span class="line"><span class="cl">  <span class="nx">setTheme</span><span class="o">:</span> <span class="p">(</span><span class="nx">theme</span><span class="o">:</span> <span class="s1">&#39;light&#39;</span> <span class="o">|</span> <span class="s1">&#39;dark&#39;</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="k">void</span>
</span></span><span class="line"><span class="cl">  <span class="nx">toggleSidebar</span><span class="o">:</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="k">void</span>
</span></span><span class="line"><span class="cl">  <span class="nx">setFilters</span><span class="o">:</span> <span class="p">(</span><span class="nx">filters</span>: <span class="kt">string</span><span class="p">[])</span> <span class="o">=&gt;</span> <span class="k">void</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">useAppStore</span> <span class="o">=</span> <span class="nx">create</span><span class="p">&lt;</span><span class="nt">AppState</span><span class="p">&gt;((</span><span class="kr">set</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">theme</span><span class="o">:</span> <span class="s1">&#39;light&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">sidebarOpen</span>: <span class="kt">false</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">selectedFilters</span><span class="o">:</span> <span class="p">[],</span>
</span></span><span class="line"><span class="cl">  <span class="nx">setTheme</span><span class="o">:</span> <span class="p">(</span><span class="nx">theme</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="kr">set</span><span class="p">({</span> <span class="nx">theme</span> <span class="p">}),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">toggleSidebar</span><span class="o">:</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="kr">set</span><span class="p">((</span><span class="nx">state</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">({</span> <span class="nx">sidebarOpen</span><span class="o">:</span> <span class="o">!</span><span class="nx">state</span><span class="p">.</span><span class="nx">sidebarOpen</span> <span class="p">})),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">setFilters</span><span class="o">:</span> <span class="p">(</span><span class="nx">filters</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="kr">set</span><span class="p">({</span> <span class="nx">selectedFilters</span>: <span class="kt">filters</span> <span class="p">}),</span>
</span></span><span class="line"><span class="cl"><span class="p">}))</span></span></span></code></pre></div></div>
<p>组件里这样用：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-tsx" data-lang="tsx"><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">Sidebar() {</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="p">{</span> <span class="nx">sidebarOpen</span><span class="p">,</span> <span class="nx">toggleSidebar</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">useAppStore</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">sidebarOpen</span><span class="p">)</span> <span class="k">return</span> <span class="kc">null</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">className</span><span class="o">=</span><span class="s">&#34;sidebar&#34;</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">&lt;</span><span class="nt">button</span> <span class="na">onClick</span><span class="o">=</span><span class="p">{</span><span class="nx">toggleSidebar</span><span class="p">}&gt;</span><span class="nx">Close</span><span class="p">&lt;/</span><span class="nt">button</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">{</span><span class="cm">/* sidebar content */</span><span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>

<h3 class="relative group">我不往 Zustand 里放的东西
    <div id="我不往-zustand-里放的东西" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e4%b8%8d%e5%be%80-zustand-%e9%87%8c%e6%94%be%e7%9a%84%e4%b8%9c%e8%a5%bf" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>首先是 API 响应。我见过这样的项目：每次 API 调用都写进 Zustand store，组件不查询接口，改从 store 里读。结局就是自己手搓缓存失效、加载状态、错误处理、重新拉取和分页，而这些恰恰是 React Query 白送的。</p>
<p>其次是需要扛过重启的数据。Zustand 的状态在内存里，应用一关就没了。persist 中间件可以搭桥到 AsyncStorage（后面会讲），但那应该是想清楚之后的决定，而不是顺手为之。</p>

<h2 class="relative group">React Query：管服务器状态
    <div id="react-query管服务器状态" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#react-query%e7%ae%a1%e6%9c%8d%e5%8a%a1%e5%99%a8%e7%8a%b6%e6%80%81" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>React Query（现在叫 TanStack Query）管理远程数据的整个生命周期：拉取、缓存、同步、更新、垃圾回收。关键的观念转变，是把服务器数据当成一份要保持新鲜的缓存，而不是你拥有的状态。数据的主人是服务器，你只是暂存了一份副本。</p>
<p>只要是 API 来的数据，我一律交给它。多个组件用同一个接口的数据（请求会自动去重）、分页和无限滚动、用户回到应用时需要后台刷新的数据、先改 UI 被服务器拒绝再回滚的乐观更新，全在它的射程之内。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">useQuery</span><span class="p">,</span> <span class="nx">useMutation</span><span class="p">,</span> <span class="nx">useQueryClient</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;@tanstack/react-query&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">useUser</span><span class="p">(</span><span class="nx">userId</span>: <span class="kt">string</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="nx">useQuery</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">    <span class="nx">queryKey</span><span class="o">:</span> <span class="p">[</span><span class="s1">&#39;user&#39;</span><span class="p">,</span> <span class="nx">userId</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">    <span class="nx">queryFn</span><span class="o">:</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="nx">fetch</span><span class="p">(</span><span class="sb">`/api/users/</span><span class="si">${</span><span class="nx">userId</span><span class="si">}</span><span class="sb">`</span><span class="p">).</span><span class="nx">then</span><span class="p">(</span><span class="nx">res</span> <span class="o">=&gt;</span> <span class="nx">res</span><span class="p">.</span><span class="nx">json</span><span class="p">()),</span>
</span></span><span class="line"><span class="cl">    <span class="nx">staleTime</span>: <span class="kt">5</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">,</span> <span class="c1">// 5 分钟内视为新鲜
</span></span></span><span class="line"><span class="cl">  <span class="p">})</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">useUpdateUser() {</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">queryClient</span> <span class="o">=</span> <span class="nx">useQueryClient</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="nx">useMutation</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">    <span class="nx">mutationFn</span><span class="o">:</span> <span class="p">(</span><span class="nx">data</span><span class="o">:</span> <span class="p">{</span> <span class="nx">id</span>: <span class="kt">string</span><span class="p">;</span> <span class="nx">name</span>: <span class="kt">string</span> <span class="p">})</span> <span class="o">=&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="nx">fetch</span><span class="p">(</span><span class="sb">`/api/users/</span><span class="si">${</span><span class="nx">data</span><span class="p">.</span><span class="nx">id</span><span class="si">}</span><span class="sb">`</span><span class="p">,</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="nx">method</span><span class="o">:</span> <span class="s1">&#39;PATCH&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="nx">body</span>: <span class="kt">JSON.stringify</span><span class="p">(</span><span class="nx">data</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">      <span class="p">}),</span>
</span></span><span class="line"><span class="cl">    <span class="nx">onSuccess</span><span class="o">:</span> <span class="p">(</span><span class="nx">_</span><span class="p">,</span> <span class="nx">variables</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">queryClient</span><span class="p">.</span><span class="nx">invalidateQueries</span><span class="p">({</span> <span class="nx">queryKey</span><span class="o">:</span> <span class="p">[</span><span class="s1">&#39;user&#39;</span><span class="p">,</span> <span class="nx">variables</span><span class="p">.</span><span class="nx">id</span><span class="p">]</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">  <span class="p">})</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>组件里：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-tsx" data-lang="tsx"><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">UserProfile</span><span class="p">({</span> <span class="nx">userId</span> <span class="p">}</span><span class="o">:</span> <span class="p">{</span> <span class="nx">userId</span>: <span class="kt">string</span> <span class="p">})</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="p">{</span> <span class="nx">data</span>: <span class="kt">user</span><span class="p">,</span> <span class="nx">isLoading</span><span class="p">,</span> <span class="nx">error</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">useUser</span><span class="p">(</span><span class="nx">userId</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">updateUser</span> <span class="o">=</span> <span class="nx">useUpdateUser</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="p">(</span><span class="nx">isLoading</span><span class="p">)</span> <span class="k">return</span> <span class="p">&lt;</span><span class="nt">Spinner</span> <span class="p">/&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="k">return</span> <span class="p">&lt;</span><span class="nt">ErrorMessage</span> <span class="na">error</span><span class="o">=</span><span class="p">{</span><span class="nx">error</span><span class="p">}</span> <span class="p">/&gt;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">div</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">&lt;</span><span class="nt">h1</span><span class="p">&gt;{</span><span class="nx">user</span><span class="p">.</span><span class="nx">name</span><span class="p">}&lt;/</span><span class="nt">h1</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">&lt;</span><span class="nt">button</span>
</span></span><span class="line"><span class="cl">        <span class="na">onClick</span><span class="o">=</span><span class="p">{()</span> <span class="o">=&gt;</span> <span class="nx">updateUser</span><span class="p">.</span><span class="nx">mutate</span><span class="p">({</span> <span class="nx">id</span>: <span class="kt">userId</span><span class="p">,</span> <span class="nx">name</span><span class="o">:</span> <span class="s1">&#39;New Name&#39;</span> <span class="p">})}</span>
</span></span><span class="line"><span class="cl">        <span class="na">disabled</span><span class="o">=</span><span class="p">{</span><span class="nx">updateUser</span><span class="p">.</span><span class="nx">isPending</span><span class="p">}</span>
</span></span><span class="line"><span class="cl">      <span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">        <span class="nx">Update</span> <span class="nx">Name</span>
</span></span><span class="line"><span class="cl">      <span class="p">&lt;/</span><span class="nt">button</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>

<h3 class="relative group">不用自己写的那些东西
    <div id="不用自己写的那些东西" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%8d%e7%94%a8%e8%87%aa%e5%b7%b1%e5%86%99%e7%9a%84%e9%82%a3%e4%ba%9b%e4%b8%9c%e8%a5%bf" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>我坚持把服务器数据放这儿，就是因为白送的机制实在太多。五个组件请求同一个用户，网络请求只发一次。窗口重新聚焦或网络重连时自动重新拉取。过期缓存自动垃圾回收。每个查询都带着 <code>isLoading</code>、<code>isError</code>、<code>data</code>，加载和错误 UI 不用每次现做。失败的请求按指数退避自动重试。带回滚的乐观更新是内置模式，不用花一下午自己接管道。</p>

<h3 class="relative group">它不适合干什么
    <div id="它不适合干什么" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%ae%83%e4%b8%8d%e9%80%82%e5%90%88%e5%b9%b2%e4%bb%80%e4%b9%88" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>纯客户端状态。数据压根不经过服务器的话，React Query 只会平添仪式感。弹窗的开关状态不需要缓存失效，也不需要重新拉取间隔。</p>
<p>它也不是持久化层。缓存在内存里，重启就清空、全部重拉。缓存可以持久化（React Native 上也确实应该做，见下面的离线部分），但数据的真实来源永远是服务器。</p>

<h2 class="relative group">AsyncStorage：管扛过重启的数据
    <div id="asyncstorage管扛过重启的数据" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#asyncstorage%e7%ae%a1%e6%89%9b%e8%bf%87%e9%87%8d%e5%90%af%e7%9a%84%e6%95%b0%e6%8d%ae" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>AsyncStorage 是 React Native 的键值存储。Web 上对应的是 <code>localStorage</code>（同步）或 <code>IndexedDB</code>（异步、能力更强）。思路都一样：写到设备上，让数据活得比进程久。</p>

<h3 class="relative group">各平台底下是什么
    <div id="各平台底下是什么" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%90%84%e5%b9%b3%e5%8f%b0%e5%ba%95%e4%b8%8b%e6%98%af%e4%bb%80%e4%b9%88" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>用 <code>@react-native-async-storage/async-storage</code> 的话 API 只有一套，但底下的实现每个平台差别不小。</p>
<p>Android 上是走 <code>RKStorage</code> 的 SQLite，数据库放在应用内部存储目录里。快、可靠、有沙盒隔离，别的应用碰不到。不过要留意下表里的默认容量上限。</p>
<p>iOS 上，小值走 <code>NSUserDefaults</code>，大值走序列化文件，同样被沙盒在应用容器里。Apple 没给 <code>NSUserDefaults</code> 定硬上限，但单个值控制在几百 KB 以内是共识。真有那么大的值，八成该直接上 WatermelonDB 或 Realm 这种正经数据库了。</p>
<p>Web 上（React Native Web / Expo Web）会退回 <code>localStorage</code>，上限看浏览器，大概 5-10 MB。纯 Web 的 React 应用直接用 <code>localStorage</code> 就行，数据大了就通过 <code>idb-keyval</code> 这类封装用 <code>IndexedDB</code>。</p>
<table>
	<thead>
			<tr>
					<th>平台</th>
					<th>底层实现</th>
					<th>容量上限</th>
					<th>存储位置</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Android</td>
					<td>SQLite (RKStorage)</td>
					<td>默认约 6 MB（可配置）</td>
					<td>应用内部存储</td>
			</tr>
			<tr>
					<td>iOS</td>
					<td>NSUserDefaults / 文件</td>
					<td>无硬上限（单个值尽量小）</td>
					<td>应用沙盒容器</td>
			</tr>
			<tr>
					<td>Web</td>
					<td>localStorage</td>
					<td>约 5-10 MB（因浏览器而异）</td>
					<td>浏览器按源（origin）隔离的存储</td>
			</tr>
	</tbody>
</table>

<h3 class="relative group">我放进去的东西
    <div id="我放进去的东西" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e6%94%be%e8%bf%9b%e5%8e%bb%e7%9a%84%e4%b8%9c%e8%a5%bf" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>认证令牌和会话数据、需要留下来的用户偏好（语言、主题、通知设置）、引导完成标记、离线用的缓存数据。一句话概括：需要扛过重启的小型键值数据，这个类别就这么大。</p>
<p>API 大概是存储方案里最朴素的样子：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="nx">AsyncStorage</span> <span class="kr">from</span> <span class="s1">&#39;@react-native-async-storage/async-storage&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 存储一个值
</span></span></span><span class="line"><span class="cl"><span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">setItem</span><span class="p">(</span><span class="s1">&#39;auth_token&#39;</span><span class="p">,</span> <span class="nx">token</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 读取一个值
</span></span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">token</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">getItem</span><span class="p">(</span><span class="s1">&#39;auth_token&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 存储一个对象（需要序列化）
</span></span></span><span class="line"><span class="cl"><span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">setItem</span><span class="p">(</span><span class="s1">&#39;user_preferences&#39;</span><span class="p">,</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">theme</span><span class="o">:</span> <span class="s1">&#39;dark&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">language</span><span class="o">:</span> <span class="s1">&#39;en&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">notifications</span>: <span class="kt">true</span><span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="p">}))</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 读取一个对象
</span></span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">prefs</span> <span class="o">=</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">parse</span><span class="p">(</span><span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">getItem</span><span class="p">(</span><span class="s1">&#39;user_preferences&#39;</span><span class="p">)</span> <span class="o">??</span> <span class="s1">&#39;{}&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 删除一个值
</span></span></span><span class="line"><span class="cl"><span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">removeItem</span><span class="p">(</span><span class="s1">&#39;auth_token&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 清空所有数据（慎用）
</span></span></span><span class="line"><span class="cl"><span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">clear</span><span class="p">()</span></span></span></code></pre></div></div>

<h3 class="relative group">Web 上怎么办
    <div id="web-上怎么办" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#web-%e4%b8%8a%e6%80%8e%e4%b9%88%e5%8a%9e" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>纯 Web 的 React 应用完全不需要 AsyncStorage。简单键值对用 <code>localStorage</code>：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="c1">// 同步的 - 会阻塞主线程，但对于小数据没问题
</span></span></span><span class="line"><span class="cl"><span class="nx">localStorage</span><span class="p">.</span><span class="nx">setItem</span><span class="p">(</span><span class="s1">&#39;theme&#39;</span><span class="p">,</span> <span class="s1">&#39;dark&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">theme</span> <span class="o">=</span> <span class="nx">localStorage</span><span class="p">.</span><span class="nx">getItem</span><span class="p">(</span><span class="s1">&#39;theme&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 结构化数据
</span></span></span><span class="line"><span class="cl"><span class="nx">localStorage</span><span class="p">.</span><span class="nx">setItem</span><span class="p">(</span><span class="s1">&#39;user&#39;</span><span class="p">,</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">({</span> <span class="nx">name</span><span class="o">:</span> <span class="s1">&#39;Jared&#39;</span><span class="p">,</span> <span class="nx">role</span><span class="o">:</span> <span class="s1">&#39;admin&#39;</span> <span class="p">}))</span>
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">user</span> <span class="o">=</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">parse</span><span class="p">(</span><span class="nx">localStorage</span><span class="p">.</span><span class="nx">getItem</span><span class="p">(</span><span class="s1">&#39;user&#39;</span><span class="p">)</span> <span class="o">??</span> <span class="s1">&#39;{}&#39;</span><span class="p">)</span></span></span></code></pre></div></div>
<p>数据集大了用 <code>IndexedDB</code>：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="kr">get</span><span class="p">,</span> <span class="kr">set</span><span class="p">,</span> <span class="nx">del</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;idb-keyval&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">await</span> <span class="kr">set</span><span class="p">(</span><span class="s1">&#39;large-dataset&#39;</span><span class="p">,</span> <span class="nx">hugeArray</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">data</span> <span class="o">=</span> <span class="k">await</span> <span class="kr">get</span><span class="p">(</span><span class="s1">&#39;large-dataset&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="k">await</span> <span class="nx">del</span><span class="p">(</span><span class="s1">&#39;large-dataset&#39;</span><span class="p">)</span></span></span></code></pre></div></div>

<h3 class="relative group">它不适合干什么
    <div id="它不适合干什么-1" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%ae%83%e4%b8%8d%e9%80%82%e5%90%88%e5%b9%b2%e4%bb%80%e4%b9%88-1" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>它是键值存储，不是数据库。关系型数据、几千上万条的数组、需要索引和查询的东西，归 SQLite（走 <code>expo-sqlite</code>）、WatermelonDB 或 Realm 管。</p>
<p>它也不是安全存储。设备一旦被 root 或越狱，AsyncStorage 里的内容就是明着放的。敏感令牌请放 <code>expo-secure-store</code> 或 <code>react-native-keychain</code>。</p>

<h2 class="relative group">三个怎么搭配着用
    <div id="三个怎么搭配着用" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%89%e4%b8%aa%e6%80%8e%e4%b9%88%e6%90%ad%e9%85%8d%e7%9d%80%e7%94%a8" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>真实的应用里三个是一起上的。几个我常用的搭配。</p>

<h3 class="relative group">认证流程
    <div id="认证流程" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%ae%a4%e8%af%81%e6%b5%81%e7%a8%8b" aria-label="锚点">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="c1">// 1. AsyncStorage: 持久化认证令牌
</span></span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="nx">AsyncStorage</span> <span class="kr">from</span> <span class="s1">&#39;@react-native-async-storage/async-storage&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">async</span> <span class="kd">function</span> <span class="nx">saveToken</span><span class="p">(</span><span class="nx">token</span>: <span class="kt">string</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">setItem</span><span class="p">(</span><span class="s1">&#39;auth_token&#39;</span><span class="p">,</span> <span class="nx">token</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">async</span> <span class="kd">function</span> <span class="nx">getToken</span><span class="p">()</span><span class="o">:</span> <span class="nx">Promise</span><span class="p">&lt;</span><span class="nt">string</span> <span class="err">|</span> <span class="na">null</span><span class="p">&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">getItem</span><span class="p">(</span><span class="s1">&#39;auth_token&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 2. Zustand: 在内存中跟踪认证状态
</span></span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">create</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;zustand&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">interface</span> <span class="nx">AuthState</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">isAuthenticated</span>: <span class="kt">boolean</span>
</span></span><span class="line"><span class="cl">  <span class="nx">token</span>: <span class="kt">string</span> <span class="o">|</span> <span class="kc">null</span>
</span></span><span class="line"><span class="cl">  <span class="nx">setAuth</span><span class="o">:</span> <span class="p">(</span><span class="nx">token</span>: <span class="kt">string</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="k">void</span>
</span></span><span class="line"><span class="cl">  <span class="nx">clearAuth</span><span class="o">:</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="k">void</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">useAuthStore</span> <span class="o">=</span> <span class="nx">create</span><span class="p">&lt;</span><span class="nt">AuthState</span><span class="p">&gt;((</span><span class="kr">set</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">isAuthenticated</span>: <span class="kt">false</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">token</span>: <span class="kt">null</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">setAuth</span><span class="o">:</span> <span class="p">(</span><span class="nx">token</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="kr">set</span><span class="p">({</span> <span class="nx">isAuthenticated</span>: <span class="kt">true</span><span class="p">,</span> <span class="nx">token</span> <span class="p">}),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">clearAuth</span><span class="o">:</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="kr">set</span><span class="p">({</span> <span class="nx">isAuthenticated</span>: <span class="kt">false</span><span class="p">,</span> <span class="nx">token</span>: <span class="kt">null</span> <span class="p">}),</span>
</span></span><span class="line"><span class="cl"><span class="p">}))</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 3. React Query: 使用令牌获取用户资料
</span></span></span><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">useCurrentUser() {</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">token</span> <span class="o">=</span> <span class="nx">useAuthStore</span><span class="p">((</span><span class="nx">s</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">s</span><span class="p">.</span><span class="nx">token</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="nx">useQuery</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">    <span class="nx">queryKey</span><span class="o">:</span> <span class="p">[</span><span class="s1">&#39;currentUser&#39;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">    <span class="nx">queryFn</span><span class="o">:</span> <span class="p">()</span> <span class="o">=&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="nx">fetch</span><span class="p">(</span><span class="s1">&#39;/api/me&#39;</span><span class="p">,</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="nx">headers</span><span class="o">:</span> <span class="p">{</span> <span class="nx">Authorization</span><span class="o">:</span> <span class="sb">`Bearer </span><span class="si">${</span><span class="nx">token</span><span class="si">}</span><span class="sb">`</span> <span class="p">},</span>
</span></span><span class="line"><span class="cl">      <span class="p">}).</span><span class="nx">then</span><span class="p">(</span><span class="nx">res</span> <span class="o">=&gt;</span> <span class="nx">res</span><span class="p">.</span><span class="nx">json</span><span class="p">()),</span>
</span></span><span class="line"><span class="cl">    <span class="nx">enabled</span><span class="o">:</span> <span class="o">!!</span><span class="nx">token</span><span class="p">,</span> <span class="c1">// 只在有令牌时才发请求
</span></span></span><span class="line"><span class="cl">  <span class="p">})</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>启动时：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="c1">// 应用初始化
</span></span></span><span class="line"><span class="cl"><span class="kr">async</span> <span class="kd">function</span> <span class="nx">initializeApp() {</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">token</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">getToken</span><span class="p">()</span> <span class="c1">// 从 AsyncStorage 读取
</span></span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="p">(</span><span class="nx">token</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">useAuthStore</span><span class="p">.</span><span class="nx">getState</span><span class="p">().</span><span class="nx">setAuth</span><span class="p">(</span><span class="nx">token</span><span class="p">)</span> <span class="c1">// 放入 Zustand 以便快速访问
</span></span></span><span class="line"><span class="cl">    <span class="c1">// React Query 会自动拉取用户资料
</span></span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>AsyncStorage 负责让令牌扛过重启，Zustand 让它在任何地方都能低成本读到，React Query 则在令牌一就位时去拉用户资料。每个工具只干自己最擅长的那件事。</p>

<h3 class="relative group">重启后还在的主题设置
    <div id="重启后还在的主题设置" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e9%87%8d%e5%90%af%e5%90%8e%e8%bf%98%e5%9c%a8%e7%9a%84%e4%b8%bb%e9%a2%98%e8%ae%be%e7%bd%ae" aria-label="锚点">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">create</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;zustand&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">persist</span><span class="p">,</span> <span class="nx">createJSONStorage</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;zustand/middleware&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="nx">AsyncStorage</span> <span class="kr">from</span> <span class="s1">&#39;@react-native-async-storage/async-storage&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// Zustand 的持久化中间件在两者之间搭建了桥梁
</span></span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">useThemeStore</span> <span class="o">=</span> <span class="nx">create</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">  <span class="nx">persist</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="p">(</span><span class="kr">set</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">({</span>
</span></span><span class="line"><span class="cl">      <span class="nx">theme</span><span class="o">:</span> <span class="s1">&#39;light&#39;</span> <span class="kr">as</span> <span class="s1">&#39;light&#39;</span> <span class="o">|</span> <span class="s1">&#39;dark&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">toggleTheme</span><span class="o">:</span> <span class="p">()</span> <span class="o">=&gt;</span>
</span></span><span class="line"><span class="cl">        <span class="kr">set</span><span class="p">((</span><span class="nx">state</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">({</span>
</span></span><span class="line"><span class="cl">          <span class="nx">theme</span>: <span class="kt">state.theme</span> <span class="o">===</span> <span class="s1">&#39;light&#39;</span> <span class="o">?</span> <span class="s1">&#39;dark&#39;</span> <span class="o">:</span> <span class="s1">&#39;light&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="p">})),</span>
</span></span><span class="line"><span class="cl">    <span class="p">}),</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">name</span><span class="o">:</span> <span class="s1">&#39;theme-storage&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">storage</span>: <span class="kt">createJSONStorage</span><span class="p">(()</span> <span class="o">=&gt;</span> <span class="nx">AsyncStorage</span><span class="p">),</span> <span class="c1">// React Native
</span></span></span><span class="line"><span class="cl">      <span class="c1">// storage: createJSONStorage(() =&gt; localStorage), // Web
</span></span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">)</span></span></span></code></pre></div></div>
<p>运行时状态归 Zustand 管，persist 中间件在背后同步到 AsyncStorage（Web 上是 localStorage）。组件既不知道也不需要知道持久化层的存在。</p>

<h3 class="relative group">离线优先的读取
    <div id="离线优先的读取" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%a6%bb%e7%ba%bf%e4%bc%98%e5%85%88%e7%9a%84%e8%af%bb%e5%8f%96" aria-label="锚点">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">useQuery</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;@tanstack/react-query&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="nx">AsyncStorage</span> <span class="kr">from</span> <span class="s1">&#39;@react-native-async-storage/async-storage&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">useProducts() {</span>
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="nx">useQuery</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">    <span class="nx">queryKey</span><span class="o">:</span> <span class="p">[</span><span class="s1">&#39;products&#39;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">    <span class="nx">queryFn</span>: <span class="kt">async</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="k">try</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kr">const</span> <span class="nx">res</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">fetch</span><span class="p">(</span><span class="s1">&#39;/api/products&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="kr">const</span> <span class="nx">data</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">res</span><span class="p">.</span><span class="nx">json</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">        <span class="c1">// 缓存到 AsyncStorage 以供离线使用
</span></span></span><span class="line"><span class="cl">        <span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">setItem</span><span class="p">(</span><span class="s1">&#39;cached_products&#39;</span><span class="p">,</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">(</span><span class="nx">data</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="nx">data</span>
</span></span><span class="line"><span class="cl">      <span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="c1">// 网络请求失败 - 尝试使用缓存数据
</span></span></span><span class="line"><span class="cl">        <span class="kr">const</span> <span class="nx">cached</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">getItem</span><span class="p">(</span><span class="s1">&#39;cached_products&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="p">(</span><span class="nx">cached</span><span class="p">)</span> <span class="k">return</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">parse</span><span class="p">(</span><span class="nx">cached</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">throw</span> <span class="nx">error</span>
</span></span><span class="line"><span class="cl">      <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="nx">staleTime</span>: <span class="kt">10</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="p">})</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>拉取和内存缓存归 React Query，断网时的兜底归 AsyncStorage，分工就这么简单。</p>

<h2 class="relative group">离线模式，一步一步来
    <div id="离线模式一步一步来" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%a6%bb%e7%ba%bf%e6%a8%a1%e5%bc%8f%e4%b8%80%e6%ad%a5%e4%b8%80%e6%ad%a5%e6%9d%a5" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>这部分才是我真正关心的。通常的说法是用户会在地铁、电梯、飞机上打开应用，这没错。但我的情况更直接：报价就是在现场写的，而现场有没有信号全看运气。地下室里转圈的加载动画，意味着丢掉一单报价。</p>
<p>好消息是，就靠这三个库，不用上重型框架也能搭出相当扎实的离线方案。</p>

<h3 class="relative group">第一步：知道自己断网了
    <div id="第一步知道自己断网了" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e4%b8%80%e6%ad%a5%e7%9f%a5%e9%81%93%e8%87%aa%e5%b7%b1%e6%96%ad%e7%bd%91%e4%ba%86" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>设备得把网络状态告诉应用，应用得有个地方存这个答案。事件由 <code>@react-native-community/netinfo</code> 提供，再用一个小小的 Zustand store 让全应用都能读到。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">create</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;zustand&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="nx">NetInfo</span> <span class="kr">from</span> <span class="s1">&#39;@react-native-community/netinfo&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">interface</span> <span class="nx">NetworkState</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">isOnline</span>: <span class="kt">boolean</span>
</span></span><span class="line"><span class="cl">  <span class="nx">setOnline</span><span class="o">:</span> <span class="p">(</span><span class="nx">online</span>: <span class="kt">boolean</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="k">void</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">useNetworkStore</span> <span class="o">=</span> <span class="nx">create</span><span class="p">&lt;</span><span class="nt">NetworkState</span><span class="p">&gt;((</span><span class="kr">set</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">isOnline</span>: <span class="kt">true</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">setOnline</span><span class="o">:</span> <span class="p">(</span><span class="nx">online</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="kr">set</span><span class="p">({</span> <span class="nx">isOnline</span>: <span class="kt">online</span> <span class="p">}),</span>
</span></span><span class="line"><span class="cl"><span class="p">}))</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 应用启动时订阅一次
</span></span></span><span class="line"><span class="cl"><span class="nx">NetInfo</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">((</span><span class="nx">state</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">useNetworkStore</span><span class="p">.</span><span class="nx">getState</span><span class="p">().</span><span class="nx">setOnline</span><span class="p">(</span><span class="nx">state</span><span class="p">.</span><span class="nx">isConnected</span> <span class="o">??</span> <span class="kc">false</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">})</span></span></span></code></pre></div></div>
<p>之后任何组件都能通过 <code>useNetworkStore((s) =&gt; s.isOnline)</code> 来显示离线横幅、禁用提交按钮，或者提示“联网后会自动同步”。</p>

<h3 class="relative group">第二步：把离线告诉 React Query
    <div id="第二步把离线告诉-react-query" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e4%ba%8c%e6%ad%a5%e6%8a%8a%e7%a6%bb%e7%ba%bf%e5%91%8a%e8%af%89-react-query" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>React Query 内置了 <code>networkMode</code>，控制断网时查询和变更的行为。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">QueryClient</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;@tanstack/react-query&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">queryClient</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">QueryClient</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">defaultOptions</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">queries</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">networkMode</span><span class="o">:</span> <span class="s1">&#39;offlineFirst&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="c1">// 先返回缓存数据，联网后在后台重新拉取
</span></span></span><span class="line"><span class="cl">      <span class="nx">staleTime</span>: <span class="kt">5</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">gcTime</span>: <span class="kt">24</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">,</span> <span class="c1">// 缓存保留 24 小时
</span></span></span><span class="line"><span class="cl">      <span class="nx">retry</span><span class="o">:</span> <span class="p">(</span><span class="nx">failureCount</span><span class="p">,</span> <span class="nx">error</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="c1">// 离线时不要重试 - 反正也会失败
</span></span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">useNetworkStore</span><span class="p">.</span><span class="nx">getState</span><span class="p">().</span><span class="nx">isOnline</span><span class="p">)</span> <span class="k">return</span> <span class="kc">false</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="nx">failureCount</span> <span class="o">&lt;</span> <span class="mi">3</span>
</span></span><span class="line"><span class="cl">      <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="nx">mutations</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">networkMode</span><span class="o">:</span> <span class="s1">&#39;offlineFirst&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">  <span class="p">},</span>
</span></span><span class="line"><span class="cl"><span class="p">})</span></span></span></code></pre></div></div>
<p>三种模式：</p>
<table>
	<thead>
			<tr>
					<th>模式</th>
					<th>行为</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>online</code>（默认）</td>
					<td>只在联网时发起查询，断网时暂停。</td>
			</tr>
			<tr>
					<td><code>always</code></td>
					<td>不管网络状态都发起查询，失败由你的 <code>queryFn</code> 处理。</td>
			</tr>
			<tr>
					<td><code>offlineFirst</code></td>
					<td>先发起一次查询（取缓存数据），之后暂停，等联网再重新拉取。</td>
			</tr>
	</tbody>
</table>
<p>大多数移动应用选 <code>offlineFirst</code> 就对了：缓存数据立刻出现，新数据等网络允许时再来。</p>

<h3 class="relative group">第三步：持久化查询缓存
    <div id="第三步持久化查询缓存" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e4%b8%89%e6%ad%a5%e6%8c%81%e4%b9%85%e5%8c%96%e6%9f%a5%e8%af%a2%e7%bc%93%e5%ad%98" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>默认缓存只在内存里，一重启就满屏转圈。要做离线模式，得把缓存持久化到 AsyncStorage：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">QueryClient</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;@tanstack/react-query&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">PersistQueryClientProvider</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;@tanstack/react-query-persist-client&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">createAsyncStoragePersister</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;@tanstack/query-async-storage-persister&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="nx">AsyncStorage</span> <span class="kr">from</span> <span class="s1">&#39;@react-native-async-storage/async-storage&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">queryClient</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">QueryClient</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">defaultOptions</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">queries</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">gcTime</span>: <span class="kt">24</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">,</span> <span class="c1">// 24 小时 - 必须 &gt;= maxAge
</span></span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">  <span class="p">},</span>
</span></span><span class="line"><span class="cl"><span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">asyncStoragePersister</span> <span class="o">=</span> <span class="nx">createAsyncStoragePersister</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">storage</span>: <span class="kt">AsyncStorage</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">key</span><span class="o">:</span> <span class="s1">&#39;react-query-cache&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl"><span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 在你的 App 组件中
</span></span></span><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">App() {</span>
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">PersistQueryClientProvider</span>
</span></span><span class="line"><span class="cl">      <span class="na">client</span><span class="o">=</span><span class="p">{</span><span class="nx">queryClient</span><span class="p">}</span>
</span></span><span class="line"><span class="cl">      <span class="na">persistOptions</span><span class="o">=</span><span class="p">{{</span>
</span></span><span class="line"><span class="cl">        <span class="nx">persister</span>: <span class="kt">asyncStoragePersister</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="nx">maxAge</span>: <span class="kt">24</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">60</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">,</span> <span class="c1">// 不恢复超过 24 小时的数据
</span></span></span><span class="line"><span class="cl">        <span class="nx">dehydrateOptions</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">          <span class="nx">shouldDehydrateQuery</span><span class="o">:</span> <span class="p">(</span><span class="nx">query</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="c1">// 只持久化成功的查询
</span></span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="nx">query</span><span class="p">.</span><span class="nx">state</span><span class="p">.</span><span class="nx">status</span> <span class="o">===</span> <span class="s1">&#39;success&#39;</span>
</span></span><span class="line"><span class="cl">          <span class="p">},</span>
</span></span><span class="line"><span class="cl">        <span class="p">},</span>
</span></span><span class="line"><span class="cl">      <span class="p">}}</span>
</span></span><span class="line"><span class="cl">    <span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">&lt;</span><span class="nt">YourApp</span> <span class="p">/&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;/</span><span class="nt">PersistQueryClientProvider</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>这样在没信号的地方打开应用，看到的是上次拉取的数据而不是白屏；网络一恢复，React Query 就在后台悄悄重拉。</p>

<h3 class="relative group">第四步：离线时把写操作排进队列
    <div id="第四步离线时把写操作排进队列" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e5%9b%9b%e6%ad%a5%e7%a6%bb%e7%ba%bf%e6%97%b6%e6%8a%8a%e5%86%99%e6%93%8d%e4%bd%9c%e6%8e%92%e8%bf%9b%e9%98%9f%e5%88%97" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>读是容易的那一半。有意思的是写：用户断网时发了评论、提交了订单、改了资料，这些变更得排队存好，等网络回来再重放。</p>
<p>React Query 的答案是 <code>useMutation</code> 加上 <code>onMutate</code> 里的乐观更新：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">useMutation</span><span class="p">,</span> <span class="nx">useQueryClient</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;@tanstack/react-query&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="nx">AsyncStorage</span> <span class="kr">from</span> <span class="s1">&#39;@react-native-async-storage/async-storage&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">interface</span> <span class="nx">Comment</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">id</span>: <span class="kt">string</span>
</span></span><span class="line"><span class="cl">  <span class="nx">text</span>: <span class="kt">string</span>
</span></span><span class="line"><span class="cl">  <span class="nx">postId</span>: <span class="kt">string</span>
</span></span><span class="line"><span class="cl">  <span class="nx">createdAt</span>: <span class="kt">string</span>
</span></span><span class="line"><span class="cl">  <span class="nx">pending?</span>: <span class="kt">boolean</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">useAddComment</span><span class="p">(</span><span class="nx">postId</span>: <span class="kt">string</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">queryClient</span> <span class="o">=</span> <span class="nx">useQueryClient</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="nx">useMutation</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">    <span class="nx">mutationFn</span>: <span class="kt">async</span> <span class="p">(</span><span class="nx">text</span>: <span class="kt">string</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="kr">const</span> <span class="nx">res</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">fetch</span><span class="p">(</span><span class="sb">`/api/posts/</span><span class="si">${</span><span class="nx">postId</span><span class="si">}</span><span class="sb">/comments`</span><span class="p">,</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="nx">method</span><span class="o">:</span> <span class="s1">&#39;POST&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="nx">headers</span><span class="o">:</span> <span class="p">{</span> <span class="s1">&#39;Content-Type&#39;</span><span class="o">:</span> <span class="s1">&#39;application/json&#39;</span> <span class="p">},</span>
</span></span><span class="line"><span class="cl">        <span class="nx">body</span>: <span class="kt">JSON.stringify</span><span class="p">({</span> <span class="nx">text</span> <span class="p">}),</span>
</span></span><span class="line"><span class="cl">      <span class="p">})</span>
</span></span><span class="line"><span class="cl">      <span class="k">return</span> <span class="nx">res</span><span class="p">.</span><span class="nx">json</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1">// 乐观更新 - 立即显示评论
</span></span></span><span class="line"><span class="cl">    <span class="nx">onMutate</span>: <span class="kt">async</span> <span class="p">(</span><span class="nx">text</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="k">await</span> <span class="nx">queryClient</span><span class="p">.</span><span class="nx">cancelQueries</span><span class="p">({</span> <span class="nx">queryKey</span><span class="o">:</span> <span class="p">[</span><span class="s1">&#39;comments&#39;</span><span class="p">,</span> <span class="nx">postId</span><span class="p">]</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">      <span class="kr">const</span> <span class="nx">previous</span> <span class="o">=</span> <span class="nx">queryClient</span><span class="p">.</span><span class="nx">getQueryData</span><span class="p">&lt;</span><span class="nt">Comment</span><span class="err">[]</span><span class="p">&gt;([</span><span class="s1">&#39;comments&#39;</span><span class="p">,</span> <span class="nx">postId</span><span class="p">])</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">      <span class="kr">const</span> <span class="nx">optimisticComment</span>: <span class="kt">Comment</span> <span class="o">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="nx">id</span><span class="o">:</span> <span class="sb">`temp-</span><span class="si">${</span><span class="nb">Date</span><span class="p">.</span><span class="nx">now</span><span class="p">()</span><span class="si">}</span><span class="sb">`</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="nx">text</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="nx">postId</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="nx">createdAt</span>: <span class="kt">new</span> <span class="nb">Date</span><span class="p">().</span><span class="nx">toISOString</span><span class="p">(),</span>
</span></span><span class="line"><span class="cl">        <span class="nx">pending</span>: <span class="kt">true</span><span class="p">,</span> <span class="c1">// 在 UI 中显示&#34;发送中...&#34;的标识
</span></span></span><span class="line"><span class="cl">      <span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">      <span class="nx">queryClient</span><span class="p">.</span><span class="nx">setQueryData</span><span class="p">&lt;</span><span class="nt">Comment</span><span class="err">[]</span><span class="p">&gt;(</span>
</span></span><span class="line"><span class="cl">        <span class="p">[</span><span class="s1">&#39;comments&#39;</span><span class="p">,</span> <span class="nx">postId</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">        <span class="p">(</span><span class="nx">old</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">[...(</span><span class="nx">old</span> <span class="o">??</span> <span class="p">[]),</span> <span class="nx">optimisticComment</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">      <span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">      <span class="k">return</span> <span class="p">{</span> <span class="nx">previous</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1">// 失败时回滚
</span></span></span><span class="line"><span class="cl">    <span class="nx">onError</span><span class="o">:</span> <span class="p">(</span><span class="nx">err</span><span class="p">,</span> <span class="nx">text</span><span class="p">,</span> <span class="nx">context</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="k">if</span> <span class="p">(</span><span class="nx">context</span><span class="o">?</span><span class="p">.</span><span class="nx">previous</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="nx">queryClient</span><span class="p">.</span><span class="nx">setQueryData</span><span class="p">([</span><span class="s1">&#39;comments&#39;</span><span class="p">,</span> <span class="nx">postId</span><span class="p">],</span> <span class="nx">context</span><span class="p">.</span><span class="nx">previous</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">      <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1">// 重新拉取以获取服务器的真实数据
</span></span></span><span class="line"><span class="cl">    <span class="nx">onSettled</span><span class="o">:</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">queryClient</span><span class="p">.</span><span class="nx">invalidateQueries</span><span class="p">({</span> <span class="nx">queryKey</span><span class="o">:</span> <span class="p">[</span><span class="s1">&#39;comments&#39;</span><span class="p">,</span> <span class="nx">postId</span><span class="p">]</span> <span class="p">})</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">  <span class="p">})</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>给变更设置了 <code>networkMode: 'offlineFirst'</code> 之后，<code>mutationFn</code> 会暂停到网络恢复为止。乐观更新让评论立刻出现在屏幕上，真正的 API 调用在重连时才发出去。</p>
<p>如果需要更正经的队列，比如几十个待处理变更必须按顺序重放，还可以把变更队列本身也持久化：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">MutationCache</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;@tanstack/react-query&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 将待处理的变更保存到 AsyncStorage
</span></span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">mutationCache</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">MutationCache</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">onError</span>: <span class="kt">async</span> <span class="p">(</span><span class="nx">error</span><span class="p">,</span> <span class="nx">variables</span><span class="p">,</span> <span class="nx">context</span><span class="p">,</span> <span class="nx">mutation</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="c1">// 记录失败的变更以便调试
</span></span></span><span class="line"><span class="cl">    <span class="kr">const</span> <span class="nx">pending</span> <span class="o">=</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">parse</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">      <span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">getItem</span><span class="p">(</span><span class="s1">&#39;pending_mutations&#39;</span><span class="p">)</span> <span class="o">??</span> <span class="s1">&#39;[]&#39;</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="nx">pending</span><span class="p">.</span><span class="nx">push</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">      <span class="nx">key</span>: <span class="kt">mutation.options.mutationKey</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">variables</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">timestamp</span>: <span class="kt">Date.now</span><span class="p">(),</span>
</span></span><span class="line"><span class="cl">    <span class="p">})</span>
</span></span><span class="line"><span class="cl">    <span class="k">await</span> <span class="nx">AsyncStorage</span><span class="p">.</span><span class="nx">setItem</span><span class="p">(</span><span class="s1">&#39;pending_mutations&#39;</span><span class="p">,</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">(</span><span class="nx">pending</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">  <span class="p">},</span>
</span></span><span class="line"><span class="cl"><span class="p">})</span></span></span></code></pre></div></div>

<h3 class="relative group">第五步：网络回来后对齐状态
    <div id="第五步网络回来后对齐状态" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e4%ba%94%e6%ad%a5%e7%bd%91%e7%bb%9c%e5%9b%9e%e6%9d%a5%e5%90%8e%e5%af%b9%e9%bd%90%e7%8a%b6%e6%80%81" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>重连的活儿 React Query 基本自己包了：暂停的变更恢复执行，过期的查询重新拉取。你要做的只是把它的管理器接到 React Native 的事件上。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="nx">NetInfo</span> <span class="kr">from</span> <span class="s1">&#39;@react-native-community/netinfo&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">onlineManager</span><span class="p">,</span> <span class="nx">focusManager</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;@tanstack/react-query&#39;</span>
</span></span><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">AppState</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;react-native&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 告诉 React Query 网络状态的变化
</span></span></span><span class="line"><span class="cl"><span class="nx">onlineManager</span><span class="p">.</span><span class="nx">setEventListener</span><span class="p">((</span><span class="nx">setOnline</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="nx">NetInfo</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">((</span><span class="nx">state</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">setOnline</span><span class="p">(</span><span class="o">!!</span><span class="nx">state</span><span class="p">.</span><span class="nx">isConnected</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">  <span class="p">})</span>
</span></span><span class="line"><span class="cl"><span class="p">})</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// 应用回到前台时重新拉取
</span></span></span><span class="line"><span class="cl"><span class="nx">focusManager</span><span class="p">.</span><span class="nx">setEventListener</span><span class="p">((</span><span class="nx">setFocused</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">subscription</span> <span class="o">=</span> <span class="nx">AppState</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s1">&#39;change&#39;</span><span class="p">,</span> <span class="p">(</span><span class="nx">status</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">setFocused</span><span class="p">(</span><span class="nx">status</span> <span class="o">===</span> <span class="s1">&#39;active&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">  <span class="p">})</span>
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="nx">subscription</span><span class="p">.</span><span class="nx">remove</span><span class="p">()</span>
</span></span><span class="line"><span class="cl"><span class="p">})</span></span></span></code></pre></div></div>
<p>用户把应用切后台一小时再回来，<code>focusManager</code> 会触发重拉，让他们看到新数据；走出隧道信号恢复时，<code>onlineManager</code> 会把暂停的操作重新跑起来。</p>

<h3 class="relative group">第六步：在 UI 上说清楚
    <div id="第六步在-ui-上说清楚" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e5%85%ad%e6%ad%a5%e5%9c%a8-ui-%e4%b8%8a%e8%af%b4%e6%b8%85%e6%a5%9a" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>无论如何，别把网络错误默默咽下去。要告诉用户现在离线了、哪些更改还在等待同步。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-tsx" data-lang="tsx"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">useNetworkStore</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;./stores/network&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">OfflineBanner() {</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">isOnline</span> <span class="o">=</span> <span class="nx">useNetworkStore</span><span class="p">((</span><span class="nx">s</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">s</span><span class="p">.</span><span class="nx">isOnline</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="p">(</span><span class="nx">isOnline</span><span class="p">)</span> <span class="k">return</span> <span class="kc">null</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">View</span> <span class="na">style</span><span class="o">=</span><span class="p">{</span><span class="nx">styles</span><span class="p">.</span><span class="nx">banner</span><span class="p">}&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">&lt;</span><span class="nt">Text</span><span class="p">&gt;</span><span class="nx">You</span><span class="err">&#39;</span><span class="nx">re</span> <span class="nx">offline</span><span class="p">.</span> <span class="nx">Changes</span> <span class="nx">will</span> <span class="nx">sync</span> <span class="nx">when</span> <span class="nx">you</span> <span class="nx">reconnect</span><span class="p">.&lt;/</span><span class="nt">Text</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;/</span><span class="nt">View</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">CommentItem</span><span class="p">({</span> <span class="nx">comment</span> <span class="p">}</span><span class="o">:</span> <span class="p">{</span> <span class="nx">comment</span>: <span class="kt">Comment</span> <span class="p">})</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">View</span> <span class="na">style</span><span class="o">=</span><span class="p">{[</span><span class="nx">styles</span><span class="p">.</span><span class="nx">comment</span><span class="p">,</span> <span class="nx">comment</span><span class="p">.</span><span class="nx">pending</span> <span class="o">&amp;&amp;</span> <span class="nx">styles</span><span class="p">.</span><span class="nx">pending</span><span class="p">]}&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">&lt;</span><span class="nt">Text</span><span class="p">&gt;{</span><span class="nx">comment</span><span class="p">.</span><span class="nx">text</span><span class="p">}&lt;/</span><span class="nt">Text</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">{</span><span class="nx">comment</span><span class="p">.</span><span class="nx">pending</span> <span class="o">&amp;&amp;</span> <span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="p">&lt;</span><span class="nt">Text</span> <span class="na">style</span><span class="o">=</span><span class="p">{</span><span class="nx">styles</span><span class="p">.</span><span class="nx">pendingLabel</span><span class="p">}&gt;</span><span class="nx">Sending</span><span class="p">...&lt;/</span><span class="nt">Text</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">)}</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;/</span><span class="nt">View</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>

<h3 class="relative group">整体架构
    <div id="整体架构" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%95%b4%e4%bd%93%e6%9e%b6%e6%9e%84" aria-label="锚点">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">┌─────────────────────────────────────────────────┐
</span></span><span class="line"><span class="cl">│                   Components                     │
</span></span><span class="line"><span class="cl">│  useQuery() for reads    useMutation() for writes│
</span></span><span class="line"><span class="cl">└──────────┬──────────────────────┬────────────────┘
</span></span><span class="line"><span class="cl">           │                      │
</span></span><span class="line"><span class="cl">     ┌─────▼──────┐        ┌─────▼──────┐
</span></span><span class="line"><span class="cl">     │ React Query │        │ React Query │
</span></span><span class="line"><span class="cl">     │   Cache     │        │  Mutation   │
</span></span><span class="line"><span class="cl">     │ (in-memory) │        │   Queue     │
</span></span><span class="line"><span class="cl">     └─────┬──────┘        └─────┬──────┘
</span></span><span class="line"><span class="cl">           │                      │
</span></span><span class="line"><span class="cl">     ┌─────▼──────────────────────▼──────┐
</span></span><span class="line"><span class="cl">     │     AsyncStorage Persister         │
</span></span><span class="line"><span class="cl">     │  (survives app restart)            │
</span></span><span class="line"><span class="cl">     └─────┬──────────────────────┬──────┘
</span></span><span class="line"><span class="cl">           │                      │
</span></span><span class="line"><span class="cl">     ┌─────▼──────┐        ┌─────▼──────┐
</span></span><span class="line"><span class="cl">     │   Zustand   │        │   Network  │
</span></span><span class="line"><span class="cl">     │ (isOnline,  │◄───────│   NetInfo  │
</span></span><span class="line"><span class="cl">     │  UI state)  │        │            │
</span></span><span class="line"><span class="cl">     └────────────┘        └────────────┘</span></span></code></pre></div></div>
<table>
	<thead>
			<tr>
					<th>层</th>
					<th>工具</th>
					<th>职责</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>网络检测</td>
					<td>Zustand + NetInfo</td>
					<td>跟踪在线/离线状态，驱动 UI 横幅</td>
			</tr>
			<tr>
					<td>数据拉取</td>
					<td>React Query</td>
					<td>在线时拉取，离线时返回缓存</td>
			</tr>
			<tr>
					<td>缓存持久化</td>
					<td>React Query + AsyncStorage</td>
					<td>应用重启时恢复缓存</td>
			</tr>
			<tr>
					<td>离线写入</td>
					<td>React Query mutations</td>
					<td>变更排队，重连后重放</td>
			</tr>
			<tr>
					<td>乐观 UI</td>
					<td>React Query <code>onMutate</code></td>
					<td>立即显示更改，失败时回滚</td>
			</tr>
			<tr>
					<td>前台同步</td>
					<td>React Query <code>focusManager</code></td>
					<td>应用回到前台时重新拉取过期数据</td>
			</tr>
	</tbody>
</table>

<h3 class="relative group">什么时候需要真正的同步引擎
    <div id="什么时候需要真正的同步引擎" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%bb%80%e4%b9%88%e6%97%b6%e5%80%99%e9%9c%80%e8%a6%81%e7%9c%9f%e6%ad%a3%e7%9a%84%e5%90%8c%e6%ad%a5%e5%bc%95%e6%93%8e" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>上面这套的前提是：服务器是数据的真实来源，离线只是暂时状态。如果你要的是带冲突解决的真·离线优先，比如两台设备离线编辑同一篇笔记，这套就不够了，得上专门的同步引擎。WatermelonDB 专为 React Native 打造，底层是 SQLite，自带解决冲突的同步协议。Realm 配上 Atlas Device Sync，就是一个通过 MongoDB Atlas 自动解决冲突的完整离线优先数据库。PowerSync 是基于 SQLite 的同步层，能直接对接你现有的 Postgres 后端。要完全的控制权，也可以 Expo SQLite 加自己写同步逻辑。</p>
<p>Zustand + React Query + AsyncStorage 能覆盖大约 80% 的移动应用。剩下的 20%，也就是协同编辑、多设备同步、重度离线的工作流，需要专门的同步数据库。</p>

<h2 class="relative group">拿不准放哪时
    <div id="拿不准放哪时" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%8b%bf%e4%b8%8d%e5%87%86%e6%94%be%e5%93%aa%e6%97%b6" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>我拿不准的时候，会按这个顺序问自己：</p>
<table>
	<thead>
			<tr>
					<th>问题</th>
					<th>是 → 用</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>数据来自服务器/API 吗？</td>
					<td>React Query</td>
			</tr>
			<tr>
					<td>是多个组件共享的纯客户端 UI 状态吗？</td>
					<td>Zustand</td>
			</tr>
			<tr>
					<td>需要扛过应用重启吗？</td>
					<td>AsyncStorage（可选配合 Zustand persist）</td>
			</tr>
			<tr>
					<td>是敏感数据吗（令牌、密码）？</td>
					<td>expo-secure-store / react-native-keychain</td>
			</tr>
			<tr>
					<td>是需要查询的大型结构化数据吗？</td>
					<td>SQLite / WatermelonDB / Realm</td>
			</tr>
			<tr>
					<td>只是单个组件用的简单表单输入吗？</td>
					<td>useState</td>
			</tr>
	</tbody>
</table>

<h3 class="relative group">常见场景
    <div id="常见场景" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%b8%b8%e8%a7%81%e5%9c%ba%e6%99%af" aria-label="锚点">#</a>
    </span>
    
</h3>
<table>
	<thead>
			<tr>
					<th>状态</th>
					<th>工具</th>
					<th>原因</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>API 响应数据</td>
					<td>React Query</td>
					<td>缓存、去重、重新拉取、加载状态</td>
			</tr>
			<tr>
					<td>选中的标签页 / 当前筛选条件</td>
					<td>Zustand</td>
					<td>纯客户端，多个组件都要用</td>
			</tr>
			<tr>
					<td>认证令牌</td>
					<td>AsyncStorage + Zustand</td>
					<td>重启后仍在，内存中读取快</td>
			</tr>
			<tr>
					<td>主题偏好</td>
					<td>Zustand + persist 中间件</td>
					<td>需要扛过重启的客户端状态</td>
			</tr>
			<tr>
					<td>购物车</td>
					<td>Zustand + persist 中间件</td>
					<td>客户端逻辑复杂，需要扛过重启</td>
			</tr>
			<tr>
					<td>表单输入</td>
					<td>useState</td>
					<td>只在单个组件里用，无需共享</td>
			</tr>
			<tr>
					<td>来自 API 的用户资料</td>
					<td>React Query</td>
					<td>服务器状态，可能过期</td>
			</tr>
			<tr>
					<td>引导完成标记</td>
					<td>AsyncStorage</td>
					<td>只是一个需要持久化的布尔值</td>
			</tr>
			<tr>
					<td>离线缓存的动态流</td>
					<td>React Query + AsyncStorage</td>
					<td>从服务器拉取，失败时退回缓存</td>
			</tr>
	</tbody>
</table>

<h2 class="relative group">各平台安装
    <div id="各平台安装" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%90%84%e5%b9%b3%e5%8f%b0%e5%ae%89%e8%a3%85" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">React Native (Android + iOS)
    <div id="react-native-android--ios" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#react-native-android--ios" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>三个一起装：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npm install zustand @tanstack/react-query @react-native-async-storage/async-storage</span></span></code></pre></div></div>
<p>敏感数据再加上安全存储：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npx expo install expo-secure-store
</span></span><span class="line"><span class="cl"><span class="c1"># 或者</span>
</span></span><span class="line"><span class="cl">npm install react-native-keychain</span></span></code></pre></div></div>

<h3 class="relative group">Expo
    <div id="expo" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#expo" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>AsyncStorage 在 Expo 里开箱即用，不需要原生链接。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npx expo install @react-native-async-storage/async-storage</span></span></code></pre></div></div>

<h3 class="relative group">纯 Web React
    <div id="纯-web-react" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ba%af-web-react" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>跳过 AsyncStorage，直接用 <code>localStorage</code> 或 <code>IndexedDB</code>。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npm install zustand @tanstack/react-query
</span></span><span class="line"><span class="cl"><span class="c1"># 可选，用于 IndexedDB</span>
</span></span><span class="line"><span class="cl">npm install idb-keyval</span></span></code></pre></div></div>
<p>Zustand 的 persist 中间件在 Web 上默认就用 <code>localStorage</code>：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="nx">persist</span><span class="p">(</span><span class="nx">storeConfig</span><span class="p">,</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">name</span><span class="o">:</span> <span class="s1">&#39;my-store&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="c1">// localStorage 在 Web 端是默认的 - 不需要额外配置
</span></span></span><span class="line"><span class="cl"><span class="p">})</span></span></span></code></pre></div></div>

<h2 class="relative group">我反复见到的错误
    <div id="我反复见到的错误" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e5%8f%8d%e5%a4%8d%e8%a7%81%e5%88%b0%e7%9a%84%e9%94%99%e8%af%af" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>把 API 数据塞进 Zustand。如果你的 action 里出现了 <code>setUsers(apiResponse.users)</code>，先停一下。那是 React Query 的活，再往前走一步，就是把缓存失效重新发明一遍，而且发明得不会太好。</p>
<p>用 React Query 管客户端状态。<code>queryFn</code> 里没有网络请求？工具用错了。</p>
<p>把 AsyncStorage 当数据库。往键值存储里序列化一万条记录的数组，结局不会体面。用数据库。</p>
<p>令牌不加密。AsyncStorage 不是安全存储。认证令牌、API 密钥、用户凭证，请放 <code>expo-secure-store</code> 或平台的 keychain。</p>
<p>手搓持久化。如果你在挂载时手动读 AsyncStorage、每次状态一变就手动写回去，Zustand 的 persist 中间件早就把这些连同水合、序列化一起做好了，代码更少，坑也更少。</p>
<hr>
<p>服务器数据走 React Query。客户端状态放 Zustand。要扛过重启的进 AsyncStorage，敏感的进安全存储。</p>
<p>我经手过的最糟的架构，无一例外都是所有东西流经一个巨型 store。好的架构里，服务器状态、客户端状态、需要持久化的东西之间有清清楚楚的线。这些线画得越早，后面的一切就越省事。</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-05-05-zustand-vs-react-query/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>如何用 Xcode 调试 iOS 应用：断点、LLDB、Instruments 和模拟器</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-02-26-debugging-ios-mobile-apps/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-02-26-debugging-ios-mobile-apps/</guid>
      <pubDate>Thu, 26 Feb 2026 00:00:00 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>iOS</category>
      <category>Xcode</category>
      <category>Debugging</category>
      <category>Swift</category>
      <category>iOS Simulator</category>
      <category>Mobile Development</category>
      <description>在 Xcode 里调试 iOS 应用：条件断点和符号断点、值得记住的 LLDB 命令、视图调试器和内存调试器、Instruments、各种 sanitizer、崩溃日志，以及模拟器发现不了、只有真机才能抓到的问题。</description>
      <content:encoded><![CDATA[<p>在 Xcode 里调试 iOS 应用，第一步是加一个异常断点，这样一崩溃就会停在抛异常的那一行；然后重现 bug，在 LLDB 控制台里用 <code>po</code> 查看状态。接下来按症状挑工具：布局问题用视图调试器，内存泄漏和卡顿用 Memory Graph 和 Instruments，时有时无的崩溃用 Address Sanitizer 和 Thread Sanitizer。最后一定要在真机上跑一遍，因为有一整类 bug 在模拟器里根本看不到。</p>
<p>我花在调试上的时间实在太多了。谁不是呢。最近大部分时间都在 Xcode 和模拟器里追自己应用的 bug，越用越有一个感受：Xcode 自带的调试工具其实很强，只是大多数人几乎不碰。这篇就把我多年下来沉淀的调试流程写出来，都是真正省时间的部分。</p>
<figure><div class="film-pair">
  <div class="mc-film film-dark">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film-poster.jpg" style="background:url('data:image/webp;base64,UklGRnYAAABXRUJQVlA4IGoAAACwBACdASogABIAPw10q0omI6GYDAQAYxDE9IABUYPdK9J7LAix1DOefbDeaFAAAP7ouyyQ8gmq2n0OJFwS2ozDV21keVe7mp4YMAaMcC2c0TvhxpeeVUutiNnRDQ7cGAAF5HvCUh6TAAAA') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <div class="mc-film film-light">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film-light-poster.jpg" style="background:url('data:image/webp;base64,UklGRpAAAABXRUJQVlA4IIQAAAAQBQCdASogABIAPw1yq0omI6GYDAQAYxDE9IAHPf226S4YClYzU9XAx5Z9snqv0mMAAP7zbrWGjWitB9IDF4k4ejBh2+lk/1wDWp0UmPbOye0BWqKsZ+tOCwLAfdMUc6whhMbqZ7T4TZFYHYuacvt5/h28z91+Bsx0AAIOdoDWMB6QAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film-light.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/ios-debugging-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <script>window.mcFilm && window.mcFilm()</script></div><figcaption>这篇文章的十分钟视频版。旁白是英文，配有中文字幕。</figcaption>
</figure>


<h2 class="relative group">断点比你想的更强大
    <div id="断点比你想的更强大" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%96%ad%e7%82%b9%e6%af%94%e4%bd%a0%e6%83%b3%e7%9a%84%e6%9b%b4%e5%bc%ba%e5%a4%a7" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>大多数人点一下行号边栏，设个断点就完事了。其实右键点开，里面有一堆能改变调试方式的选项。</p>

<h3 class="relative group">条件断点
    <div id="条件断点" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%9d%a1%e4%bb%b6%e6%96%ad%e7%82%b9" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>假设有个循环要处理 1000 个项目，只有第 347 个出问题。总不能先命中 346 次断点吧。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="k">for</span> <span class="n">i</span> <span class="k">in</span> <span class="mf">0.</span><span class="p">.&lt;</span><span class="n">users</span><span class="p">.</span><span class="bp">count</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="n">processUser</span><span class="p">(</span><span class="n">users</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>  <span class="c1">// 在这设断点，条件: i == 347</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>右键断点，加上条件 <code>i == 347</code>，Xcode 只在条件为真时停下。<code>userId == &quot;abc123&quot;</code>、<code>error != nil</code> 这类条件同样好使。</p>

<h3 class="relative group">符号断点
    <div id="符号断点" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%a6%e5%8f%b7%e6%96%ad%e7%82%b9" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>不知道方法在哪被调用时，就靠它。打开断点导航器（Cmd+8），点 + 按钮，选“Symbolic Breakpoint”。</p>
<p>想看每个视图控制器什么时候加载？把符号设成 <code>viewDidLoad</code>，Xcode 会在每一处暂停。太吵就缩小范围：<code>MyViewController.viewDidLoad</code>。</p>
<p>我常年留着这三个：</p>
<ul>
<li><code>UIViewAlertForUnsatisfiableConstraints</code>：当场抓住 Auto Layout 冲突</li>
<li><code>objc_exception_throw</code>：在崩溃之前就停在 Objective-C 异常上</li>
<li><code>malloc_error_break</code>：发现内存分配问题</li>
</ul>

<h3 class="relative group">异常断点
    <div id="异常断点" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%bc%82%e5%b8%b8%e6%96%ad%e7%82%b9" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>这大概是新项目里第一件该做的事。加一个异常断点（断点导航器里点 + → Exception Breakpoint），Xcode 会在抛异常的那一刻暂停，而不是等应用死透了才反应。</p>
<p>多少 nil 解包的问题都是靠它抓住的，不然只会在控制台里留下一条莫名其妙的崩溃。</p>

<h3 class="relative group">断点动作
    <div id="断点动作" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%96%ad%e7%82%b9%e5%8a%a8%e4%bd%9c" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>断点其实不必停止执行。编辑断点，点“Add Action”，可以：</p>
<ul>
<li>不暂停地输出变量：<code>&quot;User count: @(users.count)@&quot;</code></li>
<li>自动执行 LLDB 命令</li>
<li>执行 shell 脚本</li>
<li>播放声音（我用它来确认罕见代码路径有没有被走到）</li>
</ul>
<p>勾上“Automatically continue after evaluating actions”，断点就成了一个不打断流程的日志器。</p>

<h2 class="relative group">LLDB：你真正会用到的控制台命令
    <div id="lldb你真正会用到的控制台命令" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#lldb%e4%bd%a0%e7%9c%9f%e6%ad%a3%e4%bc%9a%e7%94%a8%e5%88%b0%e7%9a%84%e6%8e%a7%e5%88%b6%e5%8f%b0%e5%91%bd%e4%bb%a4" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>在断点停下时，底下那个控制台不只是看崩溃日志的地方。那是 LLDB，非常好用。</p>

<h3 class="relative group">基础
    <div id="基础" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%9f%ba%e7%a1%80" aria-label="锚点">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><pre tabindex="0"><code class="language-lldb" data-lang="lldb">(lldb) po user
▿ User
  - id: &#34;123&#34;
  - name: &#34;John Doe&#34;
  - email: &#34;john<span>@</span>example.com&#34;</code></pre></div>
<p><code>po</code> 用可读的格式打印对象。我 90% 的 LLDB 操作就是它。</p>
<p>想要更多细节，换 <code>p</code>：</p>
<div class="highlight-wrapper"><pre tabindex="0"><code class="language-lldb" data-lang="lldb">(lldb) p user.name
(String) $R0 = &#34;John Doe&#34;</code></pre></div>
<p>一次看完所有局部变量：</p>
<div class="highlight-wrapper"><pre tabindex="0"><code class="language-lldb" data-lang="lldb">(lldb) frame variable</code></pre></div>

<h3 class="relative group">运行时改值
    <div id="运行时改值" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%bf%90%e8%a1%8c%e6%97%b6%e6%94%b9%e5%80%bc" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>LLDB 真正值钱的地方在这：不用重新编译就能改变量。</p>
<div class="highlight-wrapper"><pre tabindex="0"><code class="language-lldb" data-lang="lldb">(lldb) expr user.name = &#34;Jane Doe&#34;
(lldb) expr index = 0</code></pre></div>
<p>发现 bug，想不重新构建就试一下修复？改掉变量继续跑就行。缩小边界情况范围的时候，我一直这么换值测试。</p>
<p>方法也能调：</p>
<div class="highlight-wrapper"><pre tabindex="0"><code class="language-lldb" data-lang="lldb">(lldb) po self.refreshUI()
(lldb) expr navigationController?.popViewController(animated: true)</code></pre></div>

<h3 class="relative group">导航
    <div id="导航" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%af%bc%e8%88%aa" aria-label="锚点">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><pre tabindex="0"><code class="language-lldb" data-lang="lldb">(lldb) bt              # 显示调用栈
(lldb) frame select 3  # 跳到不同的栈帧
(lldb) continue        # 继续运行（或者直接 &#39;c&#39;）
(lldb) n               # 单步跳过（下一行）
(lldb) s               # 单步进入函数</code></pre></div>

<h3 class="relative group">监视点
    <div id="监视点" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%9b%91%e8%a7%86%e7%82%b9" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>想知道变量什么时候被改了？设个监视点：</p>
<div class="highlight-wrapper"><pre tabindex="0"><code class="language-lldb" data-lang="lldb">(lldb) watchpoint set variable user.isLoggedIn</code></pre></div>
<p>之后不管代码哪里改了这个值，执行都会立刻暂停。追踪莫名其妙的状态变化，没有比这更好用的了。</p>

<h2 class="relative group">Console.app：被埋没的调试工具
    <div id="consoleapp被埋没的调试工具" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#consoleapp%e8%a2%ab%e5%9f%8b%e6%b2%a1%e7%9a%84%e8%b0%83%e8%af%95%e5%b7%a5%e5%85%b7" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>多数时候 Xcode 的控制台够用，但要把系统日志、崩溃报告全都看一遍时，就该打开 Console.app 了。</p>
<p>如果你在用 OSLog（应该用），Console.app 能让这些日志随便搜、随便过滤：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="kd">import</span> <span class="nc">os</span><span class="p">.</span><span class="nc">log</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kd">let</span> <span class="nv">logger</span> <span class="p">=</span> <span class="n">Logger</span><span class="p">(</span><span class="n">subsystem</span><span class="p">:</span> <span class="s">&#34;com.example.app&#34;</span><span class="p">,</span> <span class="n">category</span><span class="p">:</span> <span class="s">&#34;networking&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">logger</span><span class="p">.</span><span class="n">info</span><span class="p">(</span><span class="s">&#34;Starting API request&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">logger</span><span class="p">.</span><span class="n">debug</span><span class="p">(</span><span class="s">&#34;Request URL: </span><span class="si">\(</span><span class="n">url</span><span class="p">.</span><span class="n">absoluteString</span><span class="si">)</span><span class="s">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">logger</span><span class="p">.</span><span class="n">error</span><span class="p">(</span><span class="s">&#34;Failed to decode: </span><span class="si">\(</span><span class="n">error</span><span class="p">.</span><span class="n">localizedDescription</span><span class="si">)</span><span class="s">&#34;</span><span class="p">)</span></span></span></code></pre></div></div>
<p>Console.app 那边的步骤：</p>
<ol>
<li>选中你的模拟器或已连接的设备</li>
<li>按子系统过滤：<code>subsystem:com.example.app</code></li>
<li>按级别过滤：<code>subsystem:com.example.app AND level:error</code></li>
</ol>
<p>常用的过滤谓词可以存起来。我存了三个：看网络请求的、看数据库操作的、只显示错误和警告的。</p>

<h3 class="relative group">为什么用 OSLog 而不是 print()
    <div id="为什么用-oslog-而不是-print" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e7%94%a8-oslog-%e8%80%8c%e4%b8%8d%e6%98%af-print" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>OSLog 比到处撒 <code>print()</code> 强太多。它是结构化的，能按级别和分类过滤；日志本身经过优化，不会拖慢应用；生产环境里还会自动遮蔽敏感数据，而且应用崩了日志也还在。</p>
<p>临时看一眼，用 <code>print()</code> 没问题。以后可能要翻的东西，交给 OSLog。</p>

<h3 class="relative group">Console.app 过滤进阶
    <div id="consoleapp-过滤进阶" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#consoleapp-%e8%bf%87%e6%bb%a4%e8%bf%9b%e9%98%b6" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>Console.app 支持相当强的谓词查询。我常用的几条：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl"># 应用里所有的错误和故障
</span></span><span class="line"><span class="cl">subsystem:com.example.app AND (level:error OR level:fault)
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"># 失败的网络请求
</span></span><span class="line"><span class="cl">subsystem:com.example.app AND category:networking AND eventMessage CONTAINS &#34;failed&#34;
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"># 过去 5 分钟的所有内容
</span></span><span class="line"><span class="cl">subsystem:com.example.app AND timestamp &gt;= now(-5m)</span></span></code></pre></div></div>
<p>日志还能导出来附在 bug 报告里，比从 Xcode 控制台复制粘贴省事多了。</p>

<h2 class="relative group">视图调试
    <div id="视图调试" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%a7%86%e5%9b%be%e8%b0%83%e8%af%95" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>UI 坏了又看不出为什么，最快的路是视图调试器。</p>
<p>运行应用，走到出问题的页面，点 Xcode 调试栏里的“Debug View Hierarchy”按钮（或按 Cmd+Shift+D），整个视图层级就以 3D 分解图摊在你面前。</p>
<p>转一转，问题自己会冒出来：</p>
<ul>
<li>藏在其他视图后面照常渲染的视图</li>
<li>跑到屏幕外老远的视图</li>
<li>大小为零的视图</li>
<li>选中视图的完整约束链</li>
</ul>
<p>我用它找到过吞掉点击事件的隐形按钮、以 0x0 渲染的标签，还有一张不知怎么变成 10,000 像素宽的图片。</p>

<h3 class="relative group">Auto Layout 调试
    <div id="auto-layout-调试" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#auto-layout-%e8%b0%83%e8%af%95" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>视图层级里的紫色警告图标就是约束冲突。点开，Xcode 会告诉你到底哪些约束在打架。</p>
<p>给约束加上标识符：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="n">heightConstraint</span><span class="p">.</span><span class="n">identifier</span> <span class="p">=</span> <span class="s">&#34;ProfileImageHeight&#34;</span></span></span></code></pre></div></div>
<p>约束出问题时，错误里显示的就是 <code>&quot;ProfileImageHeight&quot;</code> 而不是一串内存地址，日志一下就能读了。</p>
<p>在 LLDB 里也能打印约束树：</p>
<div class="highlight-wrapper"><pre tabindex="0"><code class="language-lldb" data-lang="lldb">(lldb) po view.hasAmbiguousLayout
(lldb) po view._autolayoutTrace()</code></pre></div>

<h2 class="relative group">省时间的模拟器功能
    <div id="省时间的模拟器功能" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%9c%81%e6%97%b6%e9%97%b4%e7%9a%84%e6%a8%a1%e6%8b%9f%e5%99%a8%e5%8a%9f%e8%83%bd" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">慢速动画
    <div id="慢速动画" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%85%a2%e9%80%9f%e5%8a%a8%e7%94%bb" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>Debug → Slow Animations，一切放慢到 1/10 速度。想看清转场里到底发生了什么、动画为什么看着别扭，用它正好。</p>

<h3 class="relative group">模拟内存警告
    <div id="模拟内存警告" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%a8%a1%e6%8b%9f%e5%86%85%e5%ad%98%e8%ad%a6%e5%91%8a" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>Debug → Simulate Memory Warning，测试应用在低内存下的表现。我靠它发现过不少图片缓存 bug：内存警告触发之前一切正常，一触发所有图片全没了。</p>

<h3 class="relative group">Network Link Conditioner
    <div id="network-link-conditioner" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#network-link-conditioner" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>Xcode → Open Developer Tools → Network Link Conditioner</p>
<p>可以模拟 3G、LTE、高丢包率或者完全离线。如果你遇到过 API 请求在 WiFi 上好好的、一到蜂窝网络就超时，用它就能复现。</p>
<p>我常备一个“Bad Network”配置：500ms 延迟加 10% 丢包。那些在办公室高速 WiFi 上永远看不到的超时 bug 和加载状态问题，全在这现形。</p>

<h3 class="relative group">状态栏覆盖
    <div id="状态栏覆盖" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%8a%b6%e6%80%81%e6%a0%8f%e8%a6%86%e7%9b%96" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>在模拟器里右键状态栏，可以改时间、电量、信号强度和运营商。想统一截图，或者想看不同电量下 UI 的样子，都用得上。</p>

<h3 class="relative group">位置模拟
    <div id="位置模拟" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%bd%8d%e7%bd%ae%e6%a8%a1%e6%8b%9f" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>Debug → Location，人不离开桌子就能模拟各种位置：自定义坐标、城市步行、高速公路驾驶，全都有。测位置相关功能，或者查只在某些地区出现的问题，特别方便。</p>

<h2 class="relative group">内存调试
    <div id="内存调试" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%86%85%e5%ad%98%e8%b0%83%e8%af%95" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">Debug Memory Graph
    <div id="debug-memory-graph" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#debug-memory-graph" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>点 Debug Memory Graph 按钮（Cmd+Shift+M），Xcode 会展示内存里的每个对象、它们之间的引用关系，以及你真正关心的：哪些在泄漏。</p>
<p>紫色感叹号就是泄漏。点开就能看到循环引用。</p>
<p>我见得最多的泄漏长这样：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="kd">class</span> <span class="nc">ViewController</span><span class="p">:</span> <span class="n">UIViewController</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="kd">var</span> <span class="nv">onComplete</span><span class="p">:</span> <span class="p">(()</span> <span class="p">-&gt;</span> <span class="nb">Void</span><span class="p">)?</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="kd">func</span> <span class="nf">setupHandler</span><span class="p">()</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="n">onComplete</span> <span class="p">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="kc">self</span><span class="p">.</span><span class="n">dismiss</span><span class="p">(</span><span class="n">animated</span><span class="p">:</span> <span class="kc">true</span><span class="p">)</span>  <span class="c1">// ❌ 强引用了 self</span>
</span></span><span class="line"><span class="cl">        <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>用 weak self 修：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="n">onComplete</span> <span class="p">=</span> <span class="p">{</span> <span class="p">[</span><span class="kr">weak</span> <span class="kc">self</span><span class="p">]</span> <span class="k">in</span>
</span></span><span class="line"><span class="cl">    <span class="kc">self</span><span class="p">?.</span><span class="n">dismiss</span><span class="p">(</span><span class="n">animated</span><span class="p">:</span> <span class="kc">true</span><span class="p">)</span>  <span class="c1">// ✓ 没有循环引用</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>delegate 也得是 weak：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="kr">weak</span> <span class="kd">var</span> <span class="nv">delegate</span><span class="p">:</span> <span class="n">ManagerDelegate</span><span class="p">?</span>  <span class="c1">// 不只是 &#39;var&#39;</span></span></span></code></pre></div></div>

<h3 class="relative group">Instruments
    <div id="instruments" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#instruments" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>要认真查内存，就上 Instruments（Product → Profile，或 Cmd+I）。</p>
<p>Allocations 能看到每一次对象分配、内存随时间的增长、哪些类最占内存，以及每次分配发生在哪的堆栈跟踪。</p>
<p>我通常找三样东西：随时间线性增长的内存（八成是泄漏）、意料之外的大块分配（是不是把 1000 张图一次全加载了？）、该释放却还活着的对象。</p>
<p>在操作前后标记代（那个小旗子按钮），就能看出什么东西不该留却留下了。</p>

<h2 class="relative group">性能分析
    <div id="性能分析" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%80%a7%e8%83%bd%e5%88%86%e6%9e%90" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">Time Profiler
    <div id="time-profiler" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#time-profiler" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>Product → Profile → Time Profiler。一边在应用里做那个慢操作一边录制，然后读调用树。</p>
<p>按“Self Weight”排序找瓶颈。哪个函数占了 40% 的 self weight，时间就是耗在那了。</p>
<p>我有次发现一个 JSON 解析函数每秒被调用 1000 次。挪到后台队列，UI 立刻不卡了。</p>

<h3 class="relative group">Main Thread Checker
    <div id="main-thread-checker" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#main-thread-checker" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>后台线程上的 UI 更新，Xcode 会自动抓。看到这条：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Main Thread Checker: UI API called on a background thread: -[UILabel setText:]</span></span></code></pre></div></div>
<p>说明你干了这种事：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="n">URLSession</span><span class="p">.</span><span class="n">shared</span><span class="p">.</span><span class="n">dataTask</span><span class="p">(</span><span class="n">with</span><span class="p">:</span> <span class="n">url</span><span class="p">)</span> <span class="p">{</span> <span class="n">data</span><span class="p">,</span> <span class="n">response</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
</span></span><span class="line"><span class="cl">    <span class="kc">self</span><span class="p">.</span><span class="n">label</span><span class="p">.</span><span class="n">text</span> <span class="p">=</span> <span class="s">&#34;Loaded&#34;</span>  <span class="c1">// ❌ 崩溃！</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>改成这样：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="n">URLSession</span><span class="p">.</span><span class="n">shared</span><span class="p">.</span><span class="n">dataTask</span><span class="p">(</span><span class="n">with</span><span class="p">:</span> <span class="n">url</span><span class="p">)</span> <span class="p">{</span> <span class="n">data</span><span class="p">,</span> <span class="n">response</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
</span></span><span class="line"><span class="cl">    <span class="n">DispatchQueue</span><span class="p">.</span><span class="n">main</span><span class="p">.</span><span class="n">async</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="kc">self</span><span class="p">.</span><span class="n">label</span><span class="p">.</span><span class="n">text</span> <span class="p">=</span> <span class="s">&#34;Loaded&#34;</span>  <span class="c1">// ✓</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>

<h2 class="relative group">运行时诊断
    <div id="运行时诊断" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%bf%90%e8%a1%8c%e6%97%b6%e8%af%8a%e6%96%ad" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>Edit Scheme → Run → Diagnostics。这里一排复选框，专抓那些靠手动永远找不到的 bug。</p>

<h3 class="relative group">Address Sanitizer
    <div id="address-sanitizer" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#address-sanitizer" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>查内存损坏：use-after-free、缓冲区溢出、内存泄漏。应用会慢 2-3 倍，但它抓的 bug 换别的办法几乎无从下手。追那种偶尔才出现的崩溃时，我会把它打开。</p>

<h3 class="relative group">Thread Sanitizer
    <div id="thread-sanitizer" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#thread-sanitizer" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>抓数据竞争和线程问题。开着它跑应用，正常用就行，只要有竞态条件，它自然会找出来。</p>
<p>Address Sanitizer 和 Thread Sanitizer 不能同时开，所以碰到诡异崩溃我就在两者之间轮换。</p>

<h3 class="relative group">Zombie Objects
    <div id="zombie-objects" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#zombie-objects" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>抓发给已释放对象的消息。开着它，你一碰已释放的内存，Xcode 立刻告诉你：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">*** -[MyViewController viewDidLoad]: message sent to deallocated instance 0x600001234000</span></span></code></pre></div></div>
<p>别一直开着。它会阻止对象释放，内存只涨不降。但要钉死某个 use-after-free bug，它是最好的。</p>

<h2 class="relative group">常见调试场景
    <div id="常见调试场景" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%b8%b8%e8%a7%81%e8%b0%83%e8%af%95%e5%9c%ba%e6%99%af" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">一启动就崩溃
    <div id="一启动就崩溃" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%80%e5%90%af%e5%8a%a8%e5%b0%b1%e5%b4%a9%e6%ba%83" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>先加异常断点，通常就能抓到。</p>
<p>抓不到就查这几处：Info.plist 缺键、初始化代码里的强制解包、依赖注入失败。</p>

<h3 class="relative group">UI 不更新
    <div id="ui-不更新" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#ui-%e4%b8%8d%e6%9b%b4%e6%96%b0" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>每次。每一次，都是其中之一：</p>
<ol>
<li>更新不在主线程上</li>
<li>outlet 没连上</li>
<li>视图根本不在屏幕上（LLDB 里 <code>po view.window</code> 查一下，返回 nil 就说明不在层级里）</li>
</ol>
<p>表格或集合视图的话，是你忘了调 <code>reloadData()</code>。</p>

<h3 class="relative group">内存警告导致崩溃
    <div id="内存警告导致崩溃" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%86%85%e5%ad%98%e8%ad%a6%e5%91%8a%e5%af%bc%e8%87%b4%e5%b4%a9%e6%ba%83" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>用 Instruments Allocations 看什么在占内存。通常不外乎：图片没从缓存里放掉、视图控制器释放不了（循环引用）、某个数组或字典一直在涨。</p>
<p>在模拟器里模拟内存警告，把清理代码测一遍。</p>

<h3 class="relative group">神秘崩溃
    <div id="神秘崩溃" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%a5%9e%e7%a7%98%e5%b4%a9%e6%ba%83" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>sanitizer 全开。间歇性的多半是线程问题，用 Thread Sanitizer 跑；崩在系统框架里的多半是内存损坏，用 Address Sanitizer 跑。</p>

<h3 class="relative group">复现不了的崩溃
    <div id="复现不了的崩溃" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%a4%8d%e7%8e%b0%e4%b8%8d%e4%ba%86%e7%9a%84%e5%b4%a9%e6%ba%83" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>崩溃要是发生在别人的手机上，崩溃报告一般还找得到。TestFlight 和 App Store 的构建，Xcode 的 Organizer（Window → Organizer → Crashes）会收集那些同意共享分析数据的用户的崩溃报告，只要 dSYM 跟着构建一起上传了，报告就已经符号化好了。测试人员的手机上，报告就存在设备本地：设置 → 隐私与安全性 → 分析与改进 → 分析数据，里面以应用名开头的 <code>.ips</code> 文件就是，让对方用隔空投送（AirDrop）传过来就行。先看崩溃线程的调用栈，再按上面几种场景逐个排查。</p>

<h3 class="relative group">在模拟器里调试 OTA 更新
    <div id="在模拟器里调试-ota-更新" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%9c%a8%e6%a8%a1%e6%8b%9f%e5%99%a8%e9%87%8c%e8%b0%83%e8%af%95-ota-%e6%9b%b4%e6%96%b0" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>我的应用会推送 OTA（空中下载）更新，而调试这整条流程，模拟器是最省事的地方。</p>
<p>我先盯网络流量。把 Console.app 过滤到应用的子系统，清单请求和响应就实时滚出来，发了什么头部、服务器回了什么，一清二楚。</p>
<p>然后故意把网络弄坏。用 Network Link Conditioner 看看更新流程在慢连接、丢包下什么表现。应用挂住了吗？加载指示器出来了吗？有没有体面地降级？</p>
<p>更新检查逻辑周围都埋上日志：开始检查时、发现可用更新时、开始下载时、加载新 bundle 时，每个节点都记。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="kd">import</span> <span class="nc">os</span><span class="p">.</span><span class="nc">log</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kd">let</span> <span class="nv">logger</span> <span class="p">=</span> <span class="n">Logger</span><span class="p">(</span><span class="n">subsystem</span><span class="p">:</span> <span class="s">&#34;com.example.app&#34;</span><span class="p">,</span> <span class="n">category</span><span class="p">:</span> <span class="s">&#34;updates&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">logger</span><span class="p">.</span><span class="n">info</span><span class="p">(</span><span class="s">&#34;Checking for updates...&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="kd">let</span> <span class="nv">update</span> <span class="p">=</span> <span class="k">try</span> <span class="n">await</span> <span class="n">Updates</span><span class="p">.</span><span class="n">checkForUpdateAsync</span><span class="p">()</span>
</span></span><span class="line"><span class="cl"><span class="n">logger</span><span class="p">.</span><span class="n">info</span><span class="p">(</span><span class="s">&#34;Update available: </span><span class="si">\(</span><span class="n">update</span><span class="p">.</span><span class="n">isAvailable</span><span class="si">)</span><span class="s">&#34;</span><span class="p">)</span></span></span></code></pre></div></div>
<p>最后，清单端点本身也值得单独测一遍。用应用发的同样头部直接 curl：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">curl -H <span class="s2">&#34;expo-protocol-version: 1&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">     -H <span class="s2">&#34;expo-platform: ios&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">     -H <span class="s2">&#34;expo-runtime-version: 1.0.0&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">     https://updates.example.com/manifest</span></span></code></pre></div></div>
<p>先确认服务器返回的数据没问题，再去挖客户端。</p>

<h2 class="relative group">第三方工具
    <div id="第三方工具" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%ac%ac%e4%b8%89%e6%96%b9%e5%b7%a5%e5%85%b7" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">Charles Proxy / Proxyman
    <div id="charles-proxy--proxyman" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#charles-proxy--proxyman" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>看全部网络流量、改请求和响应、测试错误条件。API 调试离不开。</p>
<p>Proxyman 的 UI 比 Charles 好，在 macOS 上也更像原生应用。我去年换过去之后就没回头。</p>

<h3 class="relative group">Reveal
    <div id="reveal" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#reveal" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>类似 Xcode 的视图调试器，但更强。不连 Xcode 也能在真机上用，查测试人员设备上的布局问题很合适。</p>

<h2 class="relative group">模拟器和真机的区别
    <div id="模拟器和真机的区别" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%a8%a1%e6%8b%9f%e5%99%a8%e5%92%8c%e7%9c%9f%e6%9c%ba%e7%9a%84%e5%8c%ba%e5%88%ab" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>我大部分调试都在模拟器里做，因为快：不用插线，不用签名，也不用等安装。但模拟器说到底是一个跑在 Mac 处理器上的 iOS 构建，用的是 Mac 的内存、Mac 的网络，有些 bug 只有在手机上才会出现。</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>模拟器</th>
					<th>真机</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>速度</td>
					<td>用的是 Mac 的 CPU，通常比手机快</td>
					<td>数据是真实的，性能分析要在这上面做</td>
			</tr>
			<tr>
					<td>内存</td>
					<td>没有真正的上限，所以要手动模拟内存警告</td>
					<td>内存占用太多，系统会直接杀掉应用</td>
			</tr>
			<tr>
					<td>网络</td>
					<td>Mac 的网络连接</td>
					<td>蜂窝网络、信号弱、在 Wi-Fi 和移动数据之间来回切换</td>
			</tr>
			<tr>
					<td>相机、蓝牙、NFC</td>
					<td>用不了</td>
					<td>能用</td>
			</tr>
			<tr>
					<td>推送通知</td>
					<td>可以用 <code>xcrun simctl push</code> 模拟</td>
					<td>真实送达，和用户收到的方式一样</td>
			</tr>
			<tr>
					<td>迭代速度</td>
					<td>几秒钟</td>
					<td>慢一些：签名、安装、连线或 Wi-Fi</td>
			</tr>
	</tbody>
</table>
<p>所以我在模拟器里写逻辑、调逻辑，发版前再拿还在支持的最老的那台 iPhone 跑一遍。性能、内存压力，还有一切跟硬件打交道的东西，没在真机上跑过，就不算真正测过。</p>

<h3 class="relative group">在真机上运行
    <div id="在真机上运行" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%9c%a8%e7%9c%9f%e6%9c%ba%e4%b8%8a%e8%bf%90%e8%a1%8c" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>把 iPhone 插上，在运行目标里选中它，再到 Signing &amp; Capabilities 里设好 Team（只装到自己的手机上，免费的 Apple ID 就够了）。从 iOS 16 开始，手机还得在 设置 → 隐私与安全性 里打开开发者模式，第一次打开会重启。打开之后，手机自己的 设置 → 开发者 菜单里也有 Network Link Conditioner，弱网配置和 Mac 上的一样。</p>

<h3 class="relative group">无线调试
    <div id="无线调试" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%97%a0%e7%ba%bf%e8%b0%83%e8%af%95" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>用 USB 连一次设备，到 Window → Devices and Simulators 勾上“Connect via network”，然后拔线。只要在同一个 WiFi 下，设备就一直挂在 Xcode 里。</p>

<h3 class="relative group">Device Console
    <div id="device-console" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#device-console" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>Window → Devices and Simulators → Open Console。系统日志、应用日志、崩溃报告，全都在，比 Xcode 自己的控制台详细得多。</p>
<p>测试人员说“应用崩了”，我一定让他们把设备插上来抓控制台日志。往往里面就躺着一条系统级错误，把一切都解释清楚了。</p>

<h2 class="relative group">我调试时的实际顺序
    <div id="我调试时的实际顺序" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e8%b0%83%e8%af%95%e6%97%b6%e7%9a%84%e5%ae%9e%e9%99%85%e9%a1%ba%e5%ba%8f" aria-label="锚点">#</a>
    </span>
    
</h2>
<ol>
<li>没有异常断点就先加一个</li>
<li>重现 bug</li>
<li>在怀疑出问题的地方附近设断点</li>
<li>在 LLDB 里用 <code>po</code> 查值</li>
<li>改变量，不重编译就验证修复</li>
<li>UI 相关就查视图层级</li>
<li>性能相关就用 Instruments 分析</li>
<li>内存或线程相关就开 sanitizer</li>
</ol>
<p>诀窍是从症状往回推。崩溃？异常断点。慢？Time Profiler。内存？Instruments。UI 诡异？视图调试器。</p>

<h2 class="relative group">希望早点知道的事
    <div id="希望早点知道的事" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%b8%8c%e6%9c%9b%e6%97%a9%e7%82%b9%e7%9f%a5%e9%81%93%e7%9a%84%e4%ba%8b" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>用断言。逻辑错误还没变成 bug 就能被拦下：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-swift" data-lang="swift"><span class="line"><span class="cl"><span class="bp">assert</span><span class="p">(</span><span class="n">users</span><span class="p">.</span><span class="bp">count</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">,</span> <span class="s">&#34;Users array should never be empty here&#34;</span><span class="p">)</span></span></span></code></pre></div></div>
<p>调试前先提交。一旦开始改东西验证猜想，你迟早会想回退。</p>
<p>调完把 print 删掉，至少也用 <code>#if DEBUG</code> 包起来。旧的调试日志会挡住下一个 bug。</p>
<p>把 LLDB 学明白，比把应用重新构建二十遍快。</p>
<p>还有，模拟器不是真手机。只在真机上出现的 bug，几乎全是线程或内存问题。再不然就是性能问题，毕竟模拟器跑的是 Mac 的 CPU，不是真正的 iPhone 芯片。</p>

<h2 class="relative group">我一直开着的工具
    <div id="我一直开着的工具" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e4%b8%80%e7%9b%b4%e5%bc%80%e7%9d%80%e7%9a%84%e5%b7%a5%e5%85%b7" aria-label="锚点">#</a>
    </span>
    
</h2>
<ul>
<li>Xcode（这不用说）</li>
<li>过滤到应用子系统的 Console.app</li>
<li>网络调试用 Proxyman</li>
<li>事态严重时上 Instruments</li>
</ul>
<hr>
<p>没有哪个工具包打天下。视图调试器找不出内存泄漏，Instruments 也解不开 Auto Layout 冲突，功夫全在把工具对上症状。这事只能靠次数堆：循环引用踩得多了，看一眼堆栈跟踪就能闻出味来。调试大概永远谈不上有趣，但至少不再是受罪。</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-02-26-debugging-ios-mobile-apps/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>不用 EAS，自建 Expo OTA 热更新：用 Django 和 Tigris 搭更新服务器</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-02-22-self-hosted-ota-updates/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-02-22-self-hosted-ota-updates/</guid>
      <pubDate>Sun, 22 Feb 2026 00:00:00 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>React Native</category>
      <category>Expo</category>
      <category>OTA Updates</category>
      <category>Django</category>
      <category>Mobile Development</category>
      <category>CI/CD</category>
      <category>Self-Hosted</category>
      <category>Tigris</category>
      <category>S3</category>
      <description>Expo 的 OTA 热更新是怎么工作的，以及我怎么不用 EAS Update 自己托管：一台实现 Expo Updates 协议的 Django REST 服务器，bundle 放在 Tigris S3 上，每月成本大约一美元。</description>
      <content:encoded><![CDATA[<blockquote><p><strong>2026 年 9 月 13 日更新。</strong> 这篇发出之后，Codemagic 发布了 <a href="https://patch.codemagic.io/"  target="_blank" rel="noreferrer sponsored">Patch</a>，一个 CodePush 路线的<a href="https://github.com/codemagic-ci-cd/codemagic-patch"  target="_blank" rel="noreferrer sponsored">开源</a>、可自托管 OTA 服务器。如果你是因为不想自己写服务器才找到这里的，它现在是一个实在的选项：我已经<a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-13-moving-to-codemagic-patch/" >把一个应用从下面这套方案迁到了 Patch</a>，并把过程写了下来，<a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-02-22-self-hosted-ota-updates/#%e5%86%99%e5%9c%a8%e6%9c%80%e5%90%8e" >写在最后</a>一节里也有一段简短说明。声明：那次迁移和那篇文章是 Codemagic 付费委托的，他们也希望在这里提一句。正文里的代码后来已精简为简短的示例。</p>
</blockquote><p>我做的报价应用，bug 修复都是通过 OTA 推送的：JavaScript 改动不用等 App Store 审核，直接下发到用户手机上。Expo 官方的 EAS Update 本来就能做这件事，但我还是用 Django REST Framework 和 Tigris S3 自己搭了一套。从那以后，iOS 和 Android 的更新全都走这台服务器。</p>
<p>Expo 的 OTA 更新（也就是大家常说的热更新）是这样运作的：应用里的 <code>expo-updates</code> 库向更新服务器请求一份清单，请求头里带着自己的平台和运行时版本。服务器返回最新的兼容更新，以及这次更新的 JavaScript bundle 和资源文件的地址，应用把它们下载下来，下次启动时就跑新的 bundle。EAS Update 是 Expo 官方托管的一种实现，但任何实现了这套协议的服务器都能用，我自己搭的就是这样一台。</p>
<p>这篇文章把整个方案过一遍：数据模型、清单（manifest）接口、发布流水线，还有那些只有真正跑起来才会踩到的坑。</p>
<figure><div class="film-pair">
  <div class="mc-film film-dark">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film-poster.jpg" style="background:url('data:image/webp;base64,UklGRm4AAABXRUJQVlA4IGIAAAAQBQCdASogABIAPw1sqEemIyIYBABjEMT0gAHv/19hLgpVytr9aI4tbGYN60LlTyNgAP7ixnoxnS14Lf/jWFfD1Ayx7Fvv7xZAlaZJ6juRdHEk24X2J2/+A6wYlCvALkAAAA==') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <div class="mc-film film-light">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film-light-poster.jpg" style="background:url('data:image/webp;base64,UklGRoAAAABXRUJQVlA4IHQAAACQBACdASogABIAPw1qqEemIyIYBABjEMT0gAFRZYz2GsagLYYqubW7XVZz++AA/u+6YQNy59OpOVcSrgpPjcRqp3rs9rBcw35QGsQ974BdqiBwqzvG68GlC5Ck9kFFL9rbx7a7jNe7Qym3Zj2uivALkAAAAA==') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film-light.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/ota-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <script>window.mcFilm && window.mcFilm()</script></div><figcaption>这篇文章的九分钟视频版。旁白是英文，配有中文字幕。</figcaption>
</figure>


<h2 class="relative group">为什么要自己搭
    <div id="为什么要自己搭" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e8%a6%81%e8%87%aa%e5%b7%b1%e6%90%ad" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>对我来说主要是钱的问题。EAS Update 按用量计费，用户多了、更新频繁了，账单就跟着涨；而 Tigris 这类 S3 兼容存储几乎不要钱。当然还有别的理由：有些行业要求应用资产必须留在自己的基础设施里；服务器在自己手上，整个更新流程就都可控，想按用户群灰度、想做 bundle 的 A/B 测试都行。另外，更新链路也不再受 Expo 服务可用性或下一次调价的影响。</p>

<h2 class="relative group">整体架构
    <div id="整体架构" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%95%b4%e4%bd%93%e6%9e%b6%e6%9e%84" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>一共四个部分：Django 后端负责下发更新清单、保存元数据；Tigris 存放 bundle 和资源文件本体；一个发布脚本负责导出、上传、登记更新；再加上移动应用本身，把更新地址指向我的服务器而不是 Expo 的。</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">┌─────────────────┐
</span></span><span class="line"><span class="cl">│   Mobile App    │
</span></span><span class="line"><span class="cl">│  (expo-updates) │
</span></span><span class="line"><span class="cl">└────────┬────────┘
</span></span><span class="line"><span class="cl">         │ 1. Request manifest
</span></span><span class="line"><span class="cl">         │    (with headers: platform, runtime-version)
</span></span><span class="line"><span class="cl">         ↓
</span></span><span class="line"><span class="cl">┌─────────────────┐
</span></span><span class="line"><span class="cl">│  Django Server  │
</span></span><span class="line"><span class="cl">│  /api/expo-     │◄─── 2. Query DB for latest update
</span></span><span class="line"><span class="cl">│   updates/      │
</span></span><span class="line"><span class="cl">│   manifest/     │
</span></span><span class="line"><span class="cl">└────────┬────────┘
</span></span><span class="line"><span class="cl">         │ 3. Generate presigned URLs
</span></span><span class="line"><span class="cl">         │
</span></span><span class="line"><span class="cl">         ↓
</span></span><span class="line"><span class="cl">┌─────────────────┐
</span></span><span class="line"><span class="cl">│   Tigris S3     │
</span></span><span class="line"><span class="cl">│  (Asset Files)  │◄─── 4. App downloads bundles directly
</span></span><span class="line"><span class="cl">└─────────────────┘</span></span></code></pre></div></div>

<h2 class="relative group">具体实现
    <div id="具体实现" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%85%b7%e4%bd%93%e5%ae%9e%e7%8e%b0" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">两个模型
    <div id="两个模型" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%a4%e4%b8%aa%e6%a8%a1%e5%9e%8b" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>一切都建立在 <code>ExpoUpdate</code> 和 <code>ExpoUpdateAsset</code> 之上。前者保存每次更新的元数据：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">class</span> <span class="nc">ExpoUpdate</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="nb">id</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">UUIDField</span><span class="p">(</span><span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">runtime_version</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">50</span><span class="p">,</span> <span class="n">db_index</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">platform</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="n">max_length</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">choices</span><span class="o">=</span><span class="p">[(</span><span class="s2">&#34;ios&#34;</span><span class="p">,</span> <span class="s2">&#34;iOS&#34;</span><span class="p">),</span> <span class="p">(</span><span class="s2">&#34;android&#34;</span><span class="p">,</span> <span class="s2">&#34;Android&#34;</span><span class="p">)],</span>
</span></span><span class="line"><span class="cl">        <span class="n">db_index</span><span class="o">=</span><span class="kc">True</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">is_active</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">BooleanField</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">db_index</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">manifest_data</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">JSONField</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="n">description</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">TextField</span><span class="p">(</span><span class="n">blank</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">created_at</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateTimeField</span><span class="p">(</span><span class="n">auto_now_add</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">class</span> <span class="nc">Meta</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="n">indexes</span> <span class="o">=</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">            <span class="n">models</span><span class="o">.</span><span class="n">Index</span><span class="p">(</span><span class="n">fields</span><span class="o">=</span><span class="p">[</span><span class="s2">&#34;runtime_version&#34;</span><span class="p">,</span> <span class="s2">&#34;platform&#34;</span><span class="p">,</span> <span class="s2">&#34;is_active&#34;</span><span class="p">,</span> <span class="s2">&#34;-created_at&#34;</span><span class="p">])</span>
</span></span><span class="line"><span class="cl">        <span class="p">]</span></span></span></code></pre></div></div>
<p>这里有几个刻意的设计。<code>runtime_version</code> 对应 <code>app.json</code> 里的 <code>runtimeVersion</code>，客户端只会下载和自己运行时版本一致的更新，所以这个字段很关键。iOS 和 Android 的 bundle 不一样，所以分开存。<code>is_active</code> 是回滚开关：把有问题的更新停用，客户端就会退回上一个版本。<code>manifest_data</code> 直接把完整的 Expo Updates v1 协议清单存成 JSON，下发的时候取出来就行。</p>
<p><code>ExpoUpdateAsset</code> 记录每个文件：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">class</span> <span class="nc">ExpoUpdateAsset</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="nb">id</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">UUIDField</span><span class="p">(</span><span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">update</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">ExpoUpdate</span><span class="p">,</span> <span class="n">on_delete</span><span class="o">=</span><span class="n">models</span><span class="o">.</span><span class="n">CASCADE</span><span class="p">,</span> <span class="n">related_name</span><span class="o">=</span><span class="s2">&#34;assets&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="nb">hash</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">255</span><span class="p">,</span> <span class="n">db_index</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">key</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">255</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">content_type</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">file_extension</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">file_path</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">500</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">file_size</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">IntegerField</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span></span></span></code></pre></div></div>
<p>资源用 SHA-256 哈希来引用，天然不可变、好缓存，同一个资源可以被多次更新复用。</p>

<h3 class="relative group">清单接口
    <div id="清单接口" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%b8%85%e5%8d%95%e6%8e%a5%e5%8f%a3" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>应用和服务器真正打交道的地方是 <code>/api/expo-updates/manifest/</code>，实现的是 <a href="https://docs.expo.dev/technical-specs/expo-updates-1/"  target="_blank" rel="noreferrer">Expo Updates v1 协议</a>：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="nd">@action</span><span class="p">(</span><span class="n">detail</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">&#34;get&#34;</span><span class="p">],</span> <span class="n">url_path</span><span class="o">=</span><span class="s2">&#34;manifest&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">manifest</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Extract required headers</span>
</span></span><span class="line"><span class="cl">    <span class="n">protocol_version</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">META</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;HTTP_EXPO_PROTOCOL_VERSION&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">platform</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">META</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;HTTP_EXPO_PLATFORM&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">runtime_version</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">META</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;HTTP_EXPO_RUNTIME_VERSION&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># Validate protocol version</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">protocol_version</span> <span class="o">!=</span> <span class="s2">&#34;1&#34;</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">Response</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="p">{</span><span class="s2">&#34;error&#34;</span><span class="p">:</span> <span class="sa">f</span><span class="s2">&#34;Unsupported protocol version: </span><span class="si">{</span><span class="n">protocol_version</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">            <span class="n">status</span><span class="o">=</span><span class="mi">400</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># Find latest active update for this runtime + platform</span>
</span></span><span class="line"><span class="cl">    <span class="n">update</span> <span class="o">=</span> <span class="n">ExpoUpdate</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="n">runtime_version</span><span class="o">=</span><span class="n">runtime_version</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">platform</span><span class="o">=</span><span class="n">platform</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">is_active</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="s2">&#34;-created_at&#34;</span><span class="p">)</span><span class="o">.</span><span class="n">first</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># No update available - client uses embedded bundle</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="ow">not</span> <span class="n">update</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="n">response</span> <span class="o">=</span> <span class="n">Response</span><span class="p">(</span><span class="n">status</span><span class="o">=</span><span class="mi">204</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="n">response</span><span class="p">[</span><span class="s2">&#34;expo-protocol-version&#34;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&#34;1&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">response</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># Generate presigned URLs for all assets</span>
</span></span><span class="line"><span class="cl">    <span class="n">manifest_data</span> <span class="o">=</span> <span class="n">build_manifest</span><span class="p">(</span><span class="n">update</span><span class="p">)</span>  <span class="c1"># fills in presigned asset URLs</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">Response</span><span class="p">(</span><span class="n">manifest_data</span><span class="p">,</span> <span class="n">status</span><span class="o">=</span><span class="mi">200</span><span class="p">)</span></span></span></code></pre></div></div>
<p>有三个细节值得注意。没有更新时返回 204，应用会继续用内置的 bundle。清单里的资源地址是预签名 URL，应用直接从 Tigris 的 CDN 下载，不用整个流经 Django。响应头里的 <code>expo-protocol-version</code> 不能省，客户端真的会检查。</p>

<h3 class="relative group">发布更新
    <div id="发布更新" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%8f%91%e5%b8%83%e6%9b%b4%e6%96%b0" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>发布靠一条 Django 管理命令，外面再包一层 shell 脚本。管理命令负责读取 <code>expo export</code> 的输出、给每个资源算 SHA-256 哈希、把 bundle 和资源并行传到 Tigris、写数据库记录，需要的话还会往桶里放一份用于生产同步的导入 JSON。精简到关键部分大致是这样：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">concurrent.futures</span> <span class="kn">import</span> <span class="n">ThreadPoolExecutor</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">transaction</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">publish</span><span class="p">(</span><span class="n">platform</span><span class="p">,</span> <span class="n">runtime_version</span><span class="p">,</span> <span class="n">manifest</span><span class="p">,</span> <span class="n">files</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Upload the bundle and assets in parallel (keys are content hashes)</span>
</span></span><span class="line"><span class="cl">    <span class="k">with</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span> <span class="k">as</span> <span class="n">executor</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="nb">list</span><span class="p">(</span><span class="n">executor</span><span class="o">.</span><span class="n">map</span><span class="p">(</span><span class="n">upload_asset</span><span class="p">,</span> <span class="n">files</span><span class="p">))</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># Swap the active update in one transaction</span>
</span></span><span class="line"><span class="cl">    <span class="k">with</span> <span class="n">transaction</span><span class="o">.</span><span class="n">atomic</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">        <span class="n">ExpoUpdate</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="n">runtime_version</span><span class="o">=</span><span class="n">runtime_version</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">platform</span><span class="o">=</span><span class="n">platform</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">is_active</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">is_active</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">ExpoUpdate</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">create</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="n">runtime_version</span><span class="o">=</span><span class="n">runtime_version</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">platform</span><span class="o">=</span><span class="n">platform</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">manifest_data</span><span class="o">=</span><span class="n">manifest</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span></span></span></code></pre></div></div>
<p>平时真正敲的是外面这层脚本：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Publish to local environment</span>
</span></span><span class="line"><span class="cl">./publish.sh ios
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Publish to production</span>
</span></span><span class="line"><span class="cl">./publish.sh ios --production
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Dry run to validate</span>
</span></span><span class="line"><span class="cl">./publish.sh --dry-run</span></span></code></pre></div></div>
<p>它会在导出前加载生产环境变量，平台可以只发一个也可以两个都发，还顺带处理下一节要讲的生产同步。</p>

<h3 class="relative group">同步到生产环境
    <div id="同步到生产环境" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%90%8c%e6%ad%a5%e5%88%b0%e7%94%9f%e4%ba%a7%e7%8e%af%e5%a2%83" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>我不想把生产环境的凭证放在自己笔记本上，所以生产发布分两步：先在本地发布（资源传到 Tigris，同时生成一份元数据的 JSON 快照），再带着 S3 路径调用生产环境的 API，让服务器自己把元数据导进去：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="nd">@action</span><span class="p">(</span><span class="n">detail</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">methods</span><span class="o">=</span><span class="p">[</span><span class="s2">&#34;post&#34;</span><span class="p">],</span> <span class="n">url_path</span><span class="o">=</span><span class="s2">&#34;import-update&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">import_update</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Authenticate via Bearer token</span>
</span></span><span class="line"><span class="cl">    <span class="n">token</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">META</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;HTTP_AUTHORIZATION&#34;</span><span class="p">,</span> <span class="s2">&#34;&#34;</span><span class="p">)</span><span class="o">.</span><span class="n">removeprefix</span><span class="p">(</span><span class="s2">&#34;Bearer &#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="ow">not</span> <span class="n">hmac</span><span class="o">.</span><span class="n">compare_digest</span><span class="p">(</span><span class="n">token</span><span class="p">,</span> <span class="n">settings</span><span class="o">.</span><span class="n">IMPORT_TOKEN</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">Response</span><span class="p">({</span><span class="s2">&#34;error&#34;</span><span class="p">:</span> <span class="s2">&#34;Invalid token&#34;</span><span class="p">},</span> <span class="n">status</span><span class="o">=</span><span class="mi">401</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># Download the import JSON from the bucket</span>
</span></span><span class="line"><span class="cl">    <span class="n">s3_key</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">data</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;s3_key&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">obj</span> <span class="o">=</span> <span class="n">s3_client</span><span class="o">.</span><span class="n">get_object</span><span class="p">(</span><span class="n">Bucket</span><span class="o">=</span><span class="n">bucket_name</span><span class="p">,</span> <span class="n">Key</span><span class="o">=</span><span class="n">s3_key</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">data</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">obj</span><span class="p">[</span><span class="s2">&#34;Body&#34;</span><span class="p">]</span><span class="o">.</span><span class="n">read</span><span class="p">())</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># Import into the production database</span>
</span></span><span class="line"><span class="cl">    <span class="k">with</span> <span class="n">transaction</span><span class="o">.</span><span class="n">atomic</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">        <span class="n">update</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">ExpoUpdate</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">update_or_create</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">data</span><span class="p">[</span><span class="s2">&#34;id&#34;</span><span class="p">],</span> <span class="n">defaults</span><span class="o">=</span><span class="p">{</span><span class="o">...</span><span class="p">})</span>
</span></span><span class="line"><span class="cl">        <span class="k">for</span> <span class="n">asset_data</span> <span class="ow">in</span> <span class="n">data</span><span class="p">[</span><span class="s2">&#34;assets&#34;</span><span class="p">]:</span>
</span></span><span class="line"><span class="cl">            <span class="n">ExpoUpdateAsset</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">update_or_create</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># Clean up the import JSON</span>
</span></span><span class="line"><span class="cl">    <span class="n">s3_client</span><span class="o">.</span><span class="n">delete_object</span><span class="p">(</span><span class="n">Bucket</span><span class="o">=</span><span class="n">bucket_name</span><span class="p">,</span> <span class="n">Key</span><span class="o">=</span><span class="n">s3_key</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">Response</span><span class="p">({</span><span class="s2">&#34;update_id&#34;</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">update</span><span class="o">.</span><span class="n">id</span><span class="p">)})</span></span></span></code></pre></div></div>

<h3 class="relative group">让应用指向自己的服务器
    <div id="让应用指向自己的服务器" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%ae%a9%e5%ba%94%e7%94%a8%e6%8c%87%e5%90%91%e8%87%aa%e5%b7%b1%e7%9a%84%e6%9c%8d%e5%8a%a1%e5%99%a8" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>在 <code>app.json</code> 里配置更新地址和运行时版本：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;expo&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;runtimeVersion&#34;</span><span class="p">:</span> <span class="s2">&#34;1.0.0&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;updates&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;url&#34;</span><span class="p">:</span> <span class="s2">&#34;https://api.example.com/api/expo-updates/manifest/&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p><code>runtimeVersion</code> 必须在应用和服务器之间严格对齐。改了原生代码或者升级了 Expo SDK，就把运行时版本加一，然后针对新版本重新发布更新。</p>

<h2 class="relative group">Tigris 存储
    <div id="tigris-存储" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#tigris-%e5%ad%98%e5%82%a8" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>Tigris 是 S3 兼容的对象存储，比 AWS S3 便宜得多，还自带全球边缘缓存。考虑到用户要下载好几 MB 的 bundle，这一点很实在。Django 侧的配置：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># settings.py</span>
</span></span><span class="line"><span class="cl"><span class="n">BUCKET_NAME</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;BUCKET_NAME&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">AWS_ENDPOINT_URL_S3</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;AWS_ENDPOINT_URL_S3&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">AWS_ACCESS_KEY_ID</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;AWS_ACCESS_KEY_ID&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">AWS_SECRET_ACCESS_KEY</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;AWS_SECRET_ACCESS_KEY&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">AWS_REGION</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;AWS_REGION&#34;</span><span class="p">,</span> <span class="s2">&#34;auto&#34;</span><span class="p">)</span></span></span></code></pre></div></div>
<p>客户端就是普通的 boto3：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">boto3</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">create_s3_client</span><span class="p">(</span><span class="n">endpoint_url</span><span class="p">,</span> <span class="n">region</span><span class="p">,</span> <span class="n">access_key</span><span class="p">,</span> <span class="n">secret_key</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">boto3</span><span class="o">.</span><span class="n">client</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;s3&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">endpoint_url</span><span class="o">=</span><span class="n">endpoint_url</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">region_name</span><span class="o">=</span><span class="n">region</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">aws_access_key_id</span><span class="o">=</span><span class="n">access_key</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">aws_secret_access_key</span><span class="o">=</span><span class="n">secret_key</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span></span></span></code></pre></div></div>
<p>下载走预签名 URL，应用直接从 CDN 拉取：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">presigned_url</span> <span class="o">=</span> <span class="n">s3_client</span><span class="o">.</span><span class="n">generate_presigned_url</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;get_object&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">Params</span><span class="o">=</span><span class="p">{</span><span class="s2">&#34;Bucket&#34;</span><span class="p">:</span> <span class="n">bucket_name</span><span class="p">,</span> <span class="s2">&#34;Key&#34;</span><span class="p">:</span> <span class="n">asset</span><span class="o">.</span><span class="n">file_path</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="n">ExpiresIn</span><span class="o">=</span><span class="mi">3600</span><span class="p">,</span>  <span class="c1"># 1 hour</span>
</span></span><span class="line"><span class="cl"><span class="p">)</span></span></span></code></pre></div></div>

<h2 class="relative group">安全
    <div id="安全" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%ae%89%e5%85%a8" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>清单接口是故意不做鉴权的，因为应用在用户登录之前就需要拿更新。导入接口则完全不同：它能写生产数据库，所以要求共享密钥，并用常数时间比较来防时序攻击：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">IMPORT_TOKEN</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;IMPORT_TOKEN&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Constant-time comparison prevents timing attacks</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="ow">not</span> <span class="n">hmac</span><span class="o">.</span><span class="n">compare_digest</span><span class="p">(</span><span class="n">token</span><span class="p">,</span> <span class="n">IMPORT_TOKEN</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">Response</span><span class="p">({</span><span class="s2">&#34;error&#34;</span><span class="p">:</span> <span class="s2">&#34;Invalid token&#34;</span><span class="p">},</span> <span class="n">status</span><span class="o">=</span><span class="mi">401</span><span class="p">)</span></span></span></code></pre></div></div>
<p>资源完整性是这套设计白送的：所有资源都按 SHA-256 哈希校验，被篡改的资源直接失败。预签名 URL 一小时过期，bundle 也就不会被长期盗链。</p>

<h2 class="relative group">性能
    <div id="性能" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%80%a7%e8%83%bd" aria-label="锚点">#</a>
    </span>
    
</h2>
<p><code>(runtime_version, platform, is_active, -created_at)</code> 这个联合索引保证清单查询不会随着更新数量增长变慢：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">class</span> <span class="nc">Meta</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="n">indexes</span> <span class="o">=</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">        <span class="n">models</span><span class="o">.</span><span class="n">Index</span><span class="p">(</span><span class="n">fields</span><span class="o">=</span><span class="p">[</span><span class="s2">&#34;runtime_version&#34;</span><span class="p">,</span> <span class="s2">&#34;platform&#34;</span><span class="p">,</span> <span class="s2">&#34;is_active&#34;</span><span class="p">,</span> <span class="s2">&#34;-created_at&#34;</span><span class="p">])</span>
</span></span><span class="line"><span class="cl">    <span class="p">]</span></span></span></code></pre></div></div>
<p>发布脚本用线程池并行上传资源：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">with</span> <span class="n">ThreadPoolExecutor</span><span class="p">(</span><span class="n">max_workers</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span> <span class="k">as</span> <span class="n">executor</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="n">futures</span> <span class="o">=</span> <span class="p">{</span><span class="n">executor</span><span class="o">.</span><span class="n">submit</span><span class="p">(</span><span class="n">upload_asset</span><span class="p">,</span> <span class="n">asset</span><span class="p">):</span> <span class="n">asset</span> <span class="k">for</span> <span class="n">asset</span> <span class="ow">in</span> <span class="n">assets</span><span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">future</span> <span class="ow">in</span> <span class="n">as_completed</span><span class="p">(</span><span class="n">futures</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="c1"># Track progress</span></span></span></code></pre></div></div>
<p>以一次 50 个资源左右的典型更新为例，发布时间从大约 2 分钟缩到了 15 秒。分发这边什么都不用做，Tigris 会自动把资源缓存到离用户近的边缘节点。</p>

<h2 class="relative group">日常流程
    <div id="日常流程" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%97%a5%e5%b8%b8%e6%b5%81%e7%a8%8b" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">开发时
    <div id="开发时" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%bc%80%e5%8f%91%e6%97%b6" aria-label="锚点">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># 1. Make code changes in the app</span>
</span></span><span class="line"><span class="cl">git commit -am <span class="s2">&#34;Fix bug&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># 2. Publish OTA update to local environment</span>
</span></span><span class="line"><span class="cl">./publish.sh ios
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># 3. Test on device</span>
</span></span><span class="line"><span class="cl"><span class="c1"># App automatically downloads and applies update</span></span></span></code></pre></div></div>

<h3 class="relative group">发布到生产
    <div id="发布到生产" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%8f%91%e5%b8%83%e5%88%b0%e7%94%9f%e4%ba%a7" aria-label="锚点">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># 1. Publish to production</span>
</span></span><span class="line"><span class="cl">./publish.sh ios --production
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># 2. Monitor</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Check Django admin for update records</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Verify assets in Tigris dashboard</span></span></span></code></pre></div></div>

<h3 class="relative group">回滚
    <div id="回滚" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%9b%9e%e6%bb%9a" aria-label="锚点">#</a>
    </span>
    
</h3>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Mark problematic update as inactive in Django admin</span>
</span></span><span class="line"><span class="cl"><span class="c1"># or via management shell:</span>
</span></span><span class="line"><span class="cl">python manage.py shell
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">&gt;&gt;&gt; from updates.models import ExpoUpdate
</span></span><span class="line"><span class="cl">&gt;&gt;&gt; <span class="nv">bad_update</span> <span class="o">=</span> ExpoUpdate.objects.get<span class="o">(</span><span class="nv">id</span><span class="o">=</span><span class="s2">&#34;uuid-here&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">&gt;&gt;&gt; bad_update.is_active <span class="o">=</span> False
</span></span><span class="line"><span class="cl">&gt;&gt;&gt; bad_update.save<span class="o">()</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Clients will now receive the previous active update</span></span></span></code></pre></div></div>

<h2 class="relative group">成本
    <div id="成本" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%90%e6%9c%ac" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>这个应用大约有 500 个活跃用户。Tigris 上，约 200 MB 的历史更新每月大概 0.02 美元，更新下载带来的每月约 50 GB 流出流量大概 1 美元。Django 这边跑在原本就承载 API 的服务器上，没有额外成本。加起来每月一美元左右。同样的用量放到 EAS Update 上，一年大概要 300 到 500 美元，所以这套东西基本上立刻就回本了。</p>

<h2 class="relative group">监控与调试
    <div id="监控与调试" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%9b%91%e6%8e%a7%e4%b8%8e%e8%b0%83%e8%af%95" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>没什么花哨的。ViewSet 会把每个清单请求记进日志：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;Manifest request: platform=</span><span class="si">{</span><span class="n">platform</span><span class="si">}</span><span class="s2">, runtime=</span><span class="si">{</span><span class="n">runtime_version</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span></span></span></code></pre></div></div>
<p>Django admin 就是事实上的控制台，把模型注册进去，查看、筛选都很方便：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="nd"><span>@</span>admin.register</span><span class="p">(</span><span class="n">ExpoUpdate</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="k">class</span> <span class="nc">ExpoUpdateAdmin</span><span class="p">(</span><span class="n">admin</span><span class="o">.</span><span class="n">ModelAdmin</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">list_display</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&#34;platform&#34;</span><span class="p">,</span> <span class="s2">&#34;runtime_version&#34;</span><span class="p">,</span> <span class="s2">&#34;is_active&#34;</span><span class="p">,</span> <span class="s2">&#34;created_at&#34;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">    <span class="n">list_filter</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&#34;platform&#34;</span><span class="p">,</span> <span class="s2">&#34;is_active&#34;</span><span class="p">,</span> <span class="s2">&#34;runtime_version&#34;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">    <span class="n">search_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&#34;description&#34;</span><span class="p">]</span></span></span></code></pre></div></div>
<p>客户端这边，<code>expo-updates</code> 会告诉你它看到了什么：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="o">*</span> <span class="kr">as</span> <span class="nx">Updates</span> <span class="kr">from</span> <span class="s1">&#39;expo-updates&#39;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nx">Updates</span><span class="p">.</span><span class="nx">checkForUpdateAsync</span><span class="p">().</span><span class="nx">then</span><span class="p">(</span><span class="nx">update</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Update available:&#39;</span><span class="p">,</span> <span class="nx">update</span><span class="p">.</span><span class="nx">isAvailable</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">  <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;Manifest:&#39;</span><span class="p">,</span> <span class="nx">update</span><span class="p">.</span><span class="nx">manifest</span><span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="p">});</span></span></span></code></pre></div></div>

<h2 class="relative group">踩过的坑
    <div id="踩过的坑" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%b8%a9%e8%bf%87%e7%9a%84%e5%9d%91" aria-label="锚点">#</a>
    </span>
    
</h2>

<h3 class="relative group">运行时版本不匹配
    <div id="运行时版本不匹配" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%bf%90%e8%a1%8c%e6%97%b6%e7%89%88%e6%9c%ac%e4%b8%8d%e5%8c%b9%e9%85%8d" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>最常见的故障也最安静：客户端只下载和自己运行时版本一致的更新。装机版本还在 <code>1.0.0</code>，你却按 <code>1.0.1</code> 发布，那就什么都收不到，也没有任何报错。运行时版本要和构建保持同步，只在原生代码变化时才递增。</p>

<h3 class="relative group">createdAt 时间戳
    <div id="createdat-时间戳" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#createdat-%e6%97%b6%e9%97%b4%e6%88%b3" aria-label="锚点">#</a>
    </span>
    
</h3>
<p><code>expo-updates</code> 客户端会拿清单的 <code>createdAt</code> 和内置 bundle 的 <code>commitTime</code> 比较，只有 <code>createdAt</code> 更新的才会被应用。ViewSet 里用数据库时间戳覆盖它：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">manifest_data</span><span class="p">[</span><span class="s2">&#34;createdAt&#34;</span><span class="p">]</span> <span class="o">=</span> <span class="n">update</span><span class="o">.</span><span class="n">created_at</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">&#34;%Y-%m-</span><span class="si">%d</span><span class="s2">T%H:%M:%S.</span><span class="si">%f</span><span class="s2">Z&#34;</span><span class="p">)</span></span></span></code></pre></div></div>
<p>本地开发时，如果你在发布 OTA <em>之后</em>又构建了二进制包，就重新发布一次 OTA，保证时间戳更新。</p>

<h3 class="relative group">清单里的资源 <code>key</code>
    <div id="清单里的资源-key" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%b8%85%e5%8d%95%e9%87%8c%e7%9a%84%e8%b5%84%e6%ba%90-key" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>清单中每个资源的 <code>key</code> 字段是 <code>expo-updates</code> 用来做缓存的，它必须是确定性哈希（比如文件名的 MD5），不能是随机 UUID 或随便一个字符串。搞错了，客户端可能无法正确缓存和读取资源，更新会在第一次成功加载之后悄悄失效。感谢读者 Raphael Mutschler 指出这个问题。在找到原因之前，他的更新恰好只成功过一次。</p>

<h3 class="relative group"><code>expoClient</code> 里的应用配置
    <div id="expoclient-里的应用配置" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#expoclient-%e9%87%8c%e7%9a%84%e5%ba%94%e7%94%a8%e9%85%8d%e7%bd%ae" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>如果应用用到 <code>Linking</code>、<code>Constants</code> 或其他在运行时读取应用配置的东西，清单的 <code>extra.expoClient</code> 字段里就必须带上应用配置。少了它，应用第一次可能启动正常，关掉之后再打开就崩溃或干脆打不开。原因是 <code>expo-updates</code> 会用 OTA 的清单替换内置清单，<code>expoClient</code> 一缺，这些 API 依赖的配置就没了。这个坑也是 Raphael Mutschler 发现的。</p>

<h3 class="relative group">清理旧资源
    <div id="清理旧资源" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%b8%85%e7%90%86%e6%97%a7%e8%b5%84%e6%ba%90" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>旧更新会在 Tigris 里越积越多。目前我还是手动清理：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># Delete updates older than 30 days</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">timedelta</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">django.utils</span> <span class="kn">import</span> <span class="n">timezone</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">cutoff</span> <span class="o">=</span> <span class="n">timezone</span><span class="o">.</span><span class="n">now</span><span class="p">()</span> <span class="o">-</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">30</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">old_updates</span> <span class="o">=</span> <span class="n">ExpoUpdate</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">created_at__lt</span><span class="o">=</span><span class="n">cutoff</span><span class="p">,</span> <span class="n">is_active</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">for</span> <span class="n">update</span> <span class="ow">in</span> <span class="n">old_updates</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Delete assets from S3</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">asset</span> <span class="ow">in</span> <span class="n">update</span><span class="o">.</span><span class="n">assets</span><span class="o">.</span><span class="n">all</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">        <span class="n">s3_client</span><span class="o">.</span><span class="n">delete_object</span><span class="p">(</span><span class="n">Bucket</span><span class="o">=</span><span class="n">bucket_name</span><span class="p">,</span> <span class="n">Key</span><span class="o">=</span><span class="n">asset</span><span class="o">.</span><span class="n">file_path</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Delete DB records</span>
</span></span><span class="line"><span class="cl">    <span class="n">update</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span></span></span></code></pre></div></div>
<p>按理说应该放进定时任务，我还没顾上。</p>

<h2 class="relative group">接下来想加的
    <div id="接下来想加的" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%8e%a5%e4%b8%8b%e6%9d%a5%e6%83%b3%e5%8a%a0%e7%9a%84" aria-label="锚点">#</a>
    </span>
    
</h2>
<p><em>（2026 年 9 月：这三样 Patch 现在都有了，还不止，见<a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-13-moving-to-codemagic-patch/" >迁移记录</a>。）</em></p>

<h3 class="relative group">灰度发布
    <div id="灰度发布" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%81%b0%e5%ba%a6%e5%8f%91%e5%b8%83" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>加一个 <code>rollout_percentage</code> 字段，就能先放量给一部分用户：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">rollout_percentage</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">IntegerField</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># In the manifest view:</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="n">update</span><span class="o">.</span><span class="n">rollout_percentage</span> <span class="o">&lt;</span> <span class="mi">100</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Hash user ID and check if they&#39;re in rollout group</span>
</span></span><span class="line"><span class="cl">    <span class="n">user_hash</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">hashlib</span><span class="o">.</span><span class="n">sha256</span><span class="p">(</span><span class="n">user_id</span><span class="o">.</span><span class="n">encode</span><span class="p">())</span><span class="o">.</span><span class="n">hexdigest</span><span class="p">(),</span> <span class="mi">16</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="p">(</span><span class="n">user_hash</span> <span class="o">%</span> <span class="mi">100</span><span class="p">)</span> <span class="o">&gt;=</span> <span class="n">update</span><span class="o">.</span><span class="n">rollout_percentage</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">Response</span><span class="p">(</span><span class="n">status</span><span class="o">=</span><span class="mi">204</span><span class="p">)</span>  <span class="c1"># No update</span></span></span></code></pre></div></div>

<h3 class="relative group">区分预发环境
    <div id="区分预发环境" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%8c%ba%e5%88%86%e9%a2%84%e5%8f%91%e7%8e%af%e5%a2%83" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>加一个 <code>environment</code> 字段，预发构建和生产就能收到不同的更新：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">environment</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">20</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s2">&#34;production&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Client sends environment in custom header</span>
</span></span><span class="line"><span class="cl"><span class="n">environment</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">META</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;HTTP_X_UPDATE_ENVIRONMENT&#34;</span><span class="p">,</span> <span class="s2">&#34;production&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">update</span> <span class="o">=</span> <span class="n">ExpoUpdate</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">environment</span><span class="o">=</span><span class="n">environment</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span><span class="o">.</span><span class="n">first</span><span class="p">()</span></span></span></code></pre></div></div>

<h3 class="relative group">下载统计
    <div id="下载统计" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%8b%e8%bd%bd%e7%bb%9f%e8%ae%a1" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>再加一个小模型，就能认真回答“这次更新到底有没有人收到”：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">class</span> <span class="nc">ExpoUpdateDownload</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">update</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">ExpoUpdate</span><span class="p">,</span> <span class="n">on_delete</span><span class="o">=</span><span class="n">models</span><span class="o">.</span><span class="n">CASCADE</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">user_id</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">255</span><span class="p">,</span> <span class="n">null</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">platform</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">downloaded_at</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">DateTimeField</span><span class="p">(</span><span class="n">auto_now_add</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></span></span></code></pre></div></div>

<h2 class="relative group">写在最后
    <div id="写在最后" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%86%99%e5%9c%a8%e6%9c%80%e5%90%8e" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>整套系统就是两个 Django 模型、几个视图、一个发布脚本，外加每月一美元的基础设施。比我动手前预想的要小，而且从那以后一直安安静静地支撑着这个应用的两个平台。</p>
<p>上面的代码是从那个生产应用简化出来的示例，按自己的项目改改就能用。读者 Raphael Mutschler 还发布了一个独立实现 <a href="https://github.com/mutschler/expo-ota-server"  target="_blank" rel="noreferrer">expo-ota-server</a>，想从能直接跑的代码开始的话可以去看看。</p>

<h3 class="relative group">如果你不想自己写服务器
    <div id="如果你不想自己写服务器" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%a6%82%e6%9e%9c%e4%bd%a0%e4%b8%8d%e6%83%b3%e8%87%aa%e5%b7%b1%e5%86%99%e6%9c%8d%e5%8a%a1%e5%99%a8" aria-label="锚点">#</a>
    </span>
    
</h3>
<p>这篇写完之后出现了两样东西，不用 Django 也能覆盖同样的地盘。第一个是上面提到的 Raphael 的 <code>expo-ota-server</code>。第二个是 <a href="https://patch.codemagic.io/"  target="_blank" rel="noreferrer sponsored">Codemagic Patch</a>：<a href="https://github.com/codemagic-ci-cd/codemagic-patch"  target="_blank" rel="noreferrer sponsored">开源</a>，通过 Docker Compose 安装跑在你自己的机器上，走的是 CodePush 协议而不是 Expo Updates 协议，所以你要把 <code>expo-updates</code> 换成它的 SDK，把 <code>eas update</code> 换成 <code>cmpatch release-react</code>。它能用 S3 兼容存储，所以本文这样的 Tigris 桶也照样能用。</p>
<p>它开箱就带着我在“接下来想加的”里列出来、却一直没做的那些：Staging 和 Production 两套 deployment、按百分比灰度、每个 release 的下载和安装数字、强制更新、二进制 patch、代码签名，以及新 bundle 在应用报告就绪之前崩溃时设备端的回滚。代价是，在任何人收到 Patch 更新之前先要发一个新的原生二进制，因为 SDK 得进到应用里；还有一台要跑的服务器，取代了一条管理命令。</p>
<p>我把自己的一个应用，连同已提交的原生工程和真实的发布流水线，从本文这套方案迁到了 Patch。<a href="https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-09-13-moving-to-codemagic-patch/" >那篇记录</a>写了哪些顺利、哪些不顺，以及到底有多难。Codemagic 赞助了那项工作，并对它做了一轮事实审阅，不是编辑审阅。</p>
<hr>
<p><em>完整规范见 <a href="https://docs.expo.dev/technical-specs/expo-updates-1/"  target="_blank" rel="noreferrer">Expo Updates Protocol Specification</a>。</em></p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-02-22-self-hosted-ota-updates/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>React Native 端侧大模型：用 llama.rn 和 llama.cpp 在手机上离线运行 Qwen</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-01-30-on-device-ai/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-01-30-on-device-ai/</guid>
      <pubDate>Fri, 30 Jan 2026 00:00:00 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>React Native</category>
      <category>AI</category>
      <category>LLM</category>
      <category>llama.cpp</category>
      <category>Qwen</category>
      <category>On-Device AI</category>
      <category>Privacy</category>
      <category>Mobile Development</category>
      <description>我怎么在 React Native 和 Expo 应用里把一个小型 LLM 完全放在手机上离线运行：llama.rn、Q4_K_M 量化的 Qwen GGUF 模型、流式输出、小模型也能应付的工具调用，以及 iPhone 和 Galaxy S23 上的实测数据。</description>
      <content:encoded><![CDATA[<p>我做的一个报价应用里有个 AI 助手，完全跑在手机上。数据一个字节都不出设备。用户用自然语言就能创建工作单、搜索客户、管理项目，开了飞行模式照样能用。</p>
<p>这篇文章讲讲我是怎么用 <strong>llama.rn</strong>（llama.cpp 的 React Native 绑定）和 <strong>Qwen 1.7B</strong> 把它做出来的。这个尺寸的模型，能干的活比我预想的多得多。</p>
<p>简单来说：装上 llama.rn，应用第一次打开时下载一个 4 位量化的 GGUF 模型（1 GB 左右），用 <code>initLlama</code> 加载，然后流式生成就行。在 iPhone 14 Pro 上，完全不联网也能跑到每秒 15 个 token 左右。这篇剩下的内容，讲的是让它真正派上用场花了哪些功夫：选模型，让它稳定地吐出工具调用，还有把内存控制住。</p>
<blockquote><p><strong>📝 更新：</strong> 现在的实现已经换成 <a href="https://huggingface.co/unsloth/Qwen3.5-2B-GGUF"  target="_blank" rel="noreferrer">Qwen3.5-2B-GGUF</a>，替代了最初的 Qwen3-1.7B。另外我也不再用 <code>/no_think</code> 消息这种土办法，改用 <code>chat_template_kwargs</code> 参数正式关闭思考模式：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">chat_response</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">chat</span><span class="o">.</span><span class="n">completions</span><span class="o">.</span><span class="n">create</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="n">model</span><span class="o">=</span><span class="s2">&#34;Qwen/Qwen3.5-27B&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">messages</span><span class="o">=</span><span class="n">messages</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">max_tokens</span><span class="o">=</span><span class="mi">32768</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">temperature</span><span class="o">=</span><span class="mf">0.7</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">top_p</span><span class="o">=</span><span class="mf">0.8</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">presence_penalty</span><span class="o">=</span><span class="mf">1.5</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">extra_body</span><span class="o">=</span><span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;top_k&#34;</span><span class="p">:</span> <span class="mi">20</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;chat_template_kwargs&#34;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&#34;enable_thinking&#34;</span><span class="p">:</span> <span class="kc">False</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl"><span class="p">)</span></span></span></code></pre></div></div>
<p>比在提示词里塞开关干净多了。</p>
</blockquote><figure><div class="film-pair">
  <div class="mc-film film-dark">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film-poster.jpg" style="background:url('data:image/webp;base64,UklGRnAAAABXRUJQVlA4IGQAAACwBACdASogABIAPw1uqUemIyIYBABjEMT0gAFRZzp3IyiSND5CxppNutGcCYkAAP7ixmKvS+0H/fAThx4cbifiH8PzygNYbl6sJuQFubAi+gzkxN3eXPGHfroT5K82AG+x8AAA') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <div class="mc-film film-light">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film-light-poster.jpg" style="background:url('data:image/webp;base64,UklGRoIAAABXRUJQVlA4IHYAAACwBACdASogABIAPw1uqUemIyIYBABjEMT0gAFRZY2mogaLUpH79C93CfzUrxKAAP7vul6EGA0ytD4npxsGq682/6nTvmGx0/XY0S/eONnq1STOt/i7tLHFRM4DTibTbGueLxPoaxVrlM6FoYdfCU8gCNqwAAAA') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film-light.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/on-device-ai-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <script>window.mcFilm && window.mcFilm()</script></div><figcaption>这篇文章的九分钟视频版。旁白是英文，配有中文字幕。</figcaption>
</figure>


<h2 class="relative group">我为什么不想用云端 AI
    <div id="我为什么不想用云端-ai" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e4%b8%ba%e4%bb%80%e4%b9%88%e4%b8%8d%e6%83%b3%e7%94%a8%e4%ba%91%e7%ab%af-ai" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>移动应用里的 AI 功能，套路基本一样：用户输入消息，应用发给云端的模型服务商，响应回来，账单往上涨。</p>
<p>但这是一个施工商家拿来做生意的应用。照这个套路走，客户的姓名、地址、电话就交给了第三方，项目细节、报价、备注躺在别人的服务器上，还得操心 GDPR 和数据驻留这些我根本不想碰的问题。API 账单也随着用户数一路上涨。</p>
<p>另一条路是把模型直接放到用户手机上跑。我选了这条。</p>

<h2 class="relative group">为什么现在做得成了
    <div id="为什么现在做得成了" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e7%8e%b0%e5%9c%a8%e5%81%9a%e5%be%97%e6%88%90%e4%ba%86" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>放在一年前我不会碰这个，但有三件事几乎同时起了变化。一是量化模型变小了：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、串起多步推理。业务逻辑要的正是这些能力，又没人指望它写诗。</p>

<h2 class="relative group">选模型
    <div id="选模型" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e9%80%89%e6%a8%a1%e5%9e%8b" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>定下 Qwen3-1.7B 之前，我试了四个小模型。</p>
<p><strong>TinyLlama 1.1B</strong>（637 MB）最快，但结构化输出始终不稳，动不动就编造客户 ID、漏掉必填字段。<strong>Phi-3-mini</strong>（1.8 GB）推理不错，可惜话太多，20 个字能说清的事非要写 200 字的小作文。<strong>Gemma-2B</strong>（1.2 GB）做分类又快又准，但函数调用不行，我的工具系统需要的 <code>&lt;action&gt;</code> 标签它输出不稳定。<strong>Qwen3-1.7B</strong>（1.1 GB）正好卡在甜点位：结构化输出可靠，指令遵循精确，还支持用 <code>&lt;think&gt;</code> 标签做思维链。</p>
<p>Q4_K_M 是 llama.cpp 的 k-quant 量化格式之一：权重按块存成 4 位数值，每一块带着自己的缩放系数，M 这一档还会把少数几个敏感的张量保留在 6 位。这样文件比 16 位权重小约 70%，质量只损失一点点。</p>

<h2 class="relative group">配置 llama.rn
    <div id="配置-llamarn" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e9%85%8d%e7%bd%ae-llamarn" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>llama.rn 把 llama.cpp 封装给 React Native 用，安装是整件事里最简单的部分：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npm install llama.rn
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> ios <span class="o">&amp;&amp;</span> pod install</span></span></code></pre></div></div>
<p>用 Expo 的话，llama.rn 是原生模块，在 Expo Go 里跑不起来。要加上它的 config plugin，改用 development build：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-js" data-lang="js"><span class="line"><span class="cl"><span class="c1">// app.config.js
</span></span></span><span class="line"><span class="cl"><span class="kr">export</span> <span class="k">default</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">expo</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">plugins</span><span class="o">:</span> <span class="p">[</span><span class="s2">&#34;llama.rn&#34;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">  <span class="p">},</span>
</span></span><span class="line"><span class="cl"><span class="p">};</span></span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npx expo install llama.rn
</span></span><span class="line"><span class="cl">npx expo run:ios</span></span></code></pre></div></div>
<p>打生产包时，这个插件还会顺手加上 llama.rn 为大模型推荐的两项 iOS entitlement（Extended Virtual Addressing 和 Increased Memory Limit，也就是扩展虚拟寻址和提高内存上限）。</p>
<p>模型本体在首次使用时下载：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">MODEL_URL</span> <span class="o">=</span> <span class="s2">&#34;https://huggingface.co/unsloth/Qwen3-1.7B-GGUF/resolve/main/Qwen3-1.7B-Q4_K_M.gguf&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">MODEL_PATH</span> <span class="o">=</span> <span class="nx">FileSystem</span><span class="p">.</span><span class="nx">documentDirectory</span> <span class="o">+</span> <span class="s2">&#34;llama-models/Qwen3-1.7B-Q4_K_M.gguf&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">downloadModel</span> <span class="o">=</span> <span class="kr">async</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">downloadResumable</span> <span class="o">=</span> <span class="nx">FileSystem</span><span class="p">.</span><span class="nx">createDownloadResumable</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="nx">MODEL_URL</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="nx">MODEL_PATH</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="p">{},</span>
</span></span><span class="line"><span class="cl">    <span class="p">(</span><span class="nx">progress</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="kr">const</span> <span class="nx">pct</span> <span class="o">=</span> <span class="nx">progress</span><span class="p">.</span><span class="nx">totalBytesWritten</span> <span class="o">/</span> <span class="nx">progress</span><span class="p">.</span><span class="nx">totalBytesExpectedToWrite</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">      <span class="nx">setDownloadProgress</span><span class="p">(</span><span class="nx">pct</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">);</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">await</span> <span class="nx">downloadResumable</span><span class="p">.</span><span class="nx">downloadAsync</span><span class="p">();</span>
</span></span><span class="line"><span class="cl"><span class="p">};</span></span></span></code></pre></div></div>
<p>WiFi 下两三分钟，LTE 大概五到八分钟。下载完成后，开着 GPU 加速加载：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">ctx</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">initLlama</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">model</span>: <span class="kt">MODEL_PATH</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">n_ctx</span>: <span class="kt">8192</span><span class="p">,</span>      <span class="c1">// 8K context window
</span></span></span><span class="line"><span class="cl">  <span class="nx">n_gpu_layers</span>: <span class="kt">99</span><span class="p">,</span> <span class="c1">// Use GPU for all layers
</span></span></span><span class="line"><span class="cl"><span class="p">});</span></span></span></code></pre></div></div>
<p><code>n_gpu_layers: 99</code> 千万别省。把计算从 CPU 挪到 Metal 或 OpenCL 上，速度能提 5 倍左右。</p>

<h2 class="relative group">流式推理
    <div id="流式推理" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%b5%81%e5%bc%8f%e6%8e%a8%e7%90%86" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>没人愿意盯着加载动画看十秒钟，所以响应按 token 逐个流出：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kd">let</span> <span class="nx">fullResponse</span> <span class="o">=</span> <span class="s2">&#34;&#34;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">await</span> <span class="nx">llamaContext</span><span class="p">.</span><span class="nx">completion</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">  <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">messages</span><span class="o">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">      <span class="p">{</span> <span class="nx">role</span><span class="o">:</span> <span class="s2">&#34;system&#34;</span><span class="p">,</span> <span class="nx">content</span>: <span class="kt">systemPrompt</span> <span class="p">},</span>
</span></span><span class="line"><span class="cl">      <span class="p">{</span> <span class="nx">role</span><span class="o">:</span> <span class="s2">&#34;user&#34;</span><span class="p">,</span> <span class="nx">content</span><span class="o">:</span> <span class="s2">&#34;Create a job for John Smith&#34;</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">    <span class="p">],</span>
</span></span><span class="line"><span class="cl">    <span class="nx">n_predict</span>: <span class="kt">512</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="nx">temperature</span>: <span class="kt">0.7</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="nx">top_p</span>: <span class="kt">0.8</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="p">},</span>
</span></span><span class="line"><span class="cl">  <span class="p">(</span><span class="nx">data</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="c1">// Called for each token
</span></span></span><span class="line"><span class="cl">    <span class="nx">fullResponse</span> <span class="o">+=</span> <span class="nx">data</span><span class="p">.</span><span class="nx">token</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">    <span class="nx">setStreamingText</span><span class="p">(</span><span class="nx">fullResponse</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">);</span></span></span></code></pre></div></div>
<p>在近几年的手机上，首个 token 约 200ms（这是提示词处理的时间），之后每个 token 50-80ms。跟走网络的 API 一比，体感就是即时的。</p>

<h2 class="relative group">小模型也玩得转的函数调用
    <div id="小模型也玩得转的函数调用" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%b0%8f%e6%a8%a1%e5%9e%8b%e4%b9%9f%e7%8e%a9%e5%be%97%e8%bd%ac%e7%9a%84%e5%87%bd%e6%95%b0%e8%b0%83%e7%94%a8" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>大型云端模型那套函数调用靠 JSON schema，小模型在这里会栽跟头：JSON 格式坏掉、必填字段丢失。所以我用了个更简单的 XML 协议：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">systemPrompt</span> <span class="o">=</span> <span class="sb">`You are an AI assistant. When you need to take an action, output:
</span></span></span><span class="line"><span class="cl"><span class="sb">&lt;action&gt;{&#34;type&#34;:&#34;search_customers&#34;,&#34;query&#34;:&#34;Smith&#34;}&lt;/action&gt;
</span></span></span><span class="line"><span class="cl"><span class="sb">
</span></span></span><span class="line"><span class="cl"><span class="sb">Available actions:
</span></span></span><span class="line"><span class="cl"><span class="sb">- search_customers: {&#34;type&#34;:&#34;search_customers&#34;,&#34;query&#34;:&#34;John&#34;}
</span></span></span><span class="line"><span class="cl"><span class="sb">- create_job: {&#34;type&#34;:&#34;create_job&#34;,&#34;customer_id&#34;:5,&#34;alias&#34;:&#34;Living Room&#34;}
</span></span></span><span class="line"><span class="cl"><span class="sb">- update_job: {&#34;type&#34;:&#34;update_job&#34;,&#34;job_id&#34;:&#34;J-0042&#34;,&#34;status&#34;:&#34;quoting&#34;}
</span></span></span><span class="line"><span class="cl"><span class="sb">
</span></span></span><span class="line"><span class="cl"><span class="sb">Rules:
</span></span></span><span class="line"><span class="cl"><span class="sb">1. ONE action tag per response, at the very end
</span></span></span><span class="line"><span class="cl"><span class="sb">2. When searching/creating → end with &lt;action&gt;
</span></span></span><span class="line"><span class="cl"><span class="sb">3. When just chatting → no action tag
</span></span></span><span class="line"><span class="cl"><span class="sb">`</span><span class="p">;</span></span></span></code></pre></div></div>
<p>选 XML 标签的理由都很朴素：<code>&lt;action&gt;</code> 和 <code>&lt;/action&gt;</code> 的起止毫不含糊，解析只要一条正则，提示词里的示例本身就是格式说明，而且就算模型在标签前后多说几句废话也不影响。</p>
<p>解析代码简单到不好意思展示：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kd">function</span> <span class="nx">parseAction</span><span class="p">(</span><span class="nx">text</span>: <span class="kt">string</span><span class="p">)</span><span class="o">:</span> <span class="nx">Action</span> <span class="o">|</span> <span class="kc">null</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">match</span> <span class="o">=</span> <span class="nx">text</span><span class="p">.</span><span class="nx">match</span><span class="p">(</span><span class="sr">/&lt;action&gt;([\s\S]*?)&lt;\/action&gt;/</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">match</span><span class="p">)</span> <span class="k">return</span> <span class="kc">null</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">try</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">parse</span><span class="p">(</span><span class="nx">match</span><span class="p">[</span><span class="mi">1</span><span class="p">].</span><span class="nx">trim</span><span class="p">());</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span> <span class="k">catch</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="kc">null</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>解析出 action 就执行，再把结果塞回对话里：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">action</span> <span class="o">=</span> <span class="nx">parseAction</span><span class="p">(</span><span class="nx">modelResponse</span><span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="p">(</span><span class="nx">action</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">result</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">executeAction</span><span class="p">(</span><span class="nx">action</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="c1">// Inject result as a system message
</span></span></span><span class="line"><span class="cl">  <span class="nx">conversationHistory</span><span class="p">.</span><span class="nx">push</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">    <span class="nx">role</span><span class="o">:</span> <span class="s2">&#34;user&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="nx">content</span><span class="o">:</span> <span class="sb">`[TOOL_RESULT] </span><span class="si">${</span><span class="nx">result</span><span class="p">.</span><span class="nx">message</span><span class="si">}</span><span class="err">\</span><span class="sb">n</span><span class="err">\</span><span class="sb">n→ NEXT: Tell the user what happened.`</span>
</span></span><span class="line"><span class="cl">  <span class="p">});</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="c1">// Continue generation
</span></span></span><span class="line"><span class="cl">  <span class="k">await</span> <span class="nx">generateNextResponse</span><span class="p">();</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>就这么点东西，多步工作流已经能顺畅跑起来了：</p>
<p><strong>用户</strong>：&ldquo;Create a job for Smith&rdquo;</p>
<ol>
<li><strong>模型</strong>：<code>&lt;action&gt;{&quot;type&quot;:&quot;search_customers&quot;,&quot;query&quot;:&quot;Smith&quot;}&lt;/action&gt;</code></li>
<li><strong>系统</strong>：<code>[TOOL_RESULT] Found: Jane Smith (id:42), Bob Smith (id:89)</code></li>
<li><strong>模型</strong>：&ldquo;找到两位 Smith：Jane 和 Bob。您要哪一位？&rdquo;</li>
<li><strong>用户</strong>：&ldquo;Jane&rdquo;</li>
<li><strong>模型</strong>：<code>&lt;action&gt;{&quot;type&quot;:&quot;create_job&quot;,&quot;customer_id&quot;:42}&lt;/action&gt;</code></li>
<li><strong>系统</strong>：<code>[TOOL_RESULT] Job J-0073 created</code></li>
<li><strong>模型</strong>：&ldquo;完成！已为 Jane Smith 创建工作单 J-0073。&rdquo;</li>
</ol>

<h2 class="relative group">用 &lt;think&gt; 标签做思维链
    <div id="用-think-标签做思维链" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%94%a8-think-%e6%a0%87%e7%ad%be%e5%81%9a%e6%80%9d%e7%bb%b4%e9%93%be" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>让小模型把推理&quot;说出来&quot;，稳定性会肉眼可见地提高。Qwen 自带思考模式：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">systemPrompt</span> <span class="o">=</span> <span class="sb">`Before each response, wrap your reasoning in &lt;think&gt; tags:
</span></span></span><span class="line"><span class="cl"><span class="sb">
</span></span></span><span class="line"><span class="cl"><span class="sb">&lt;think&gt;
</span></span></span><span class="line"><span class="cl"><span class="sb">INTENT: what does the user want?
</span></span></span><span class="line"><span class="cl"><span class="sb">HAVE: what data do I already have?
</span></span></span><span class="line"><span class="cl"><span class="sb">NEED: what&#39;s still missing?
</span></span></span><span class="line"><span class="cl"><span class="sb">DECISION: call tool | ask user | just respond
</span></span></span><span class="line"><span class="cl"><span class="sb">&lt;/think&gt;
</span></span></span><span class="line"><span class="cl"><span class="sb">
</span></span></span><span class="line"><span class="cl"><span class="sb">Then output your actual response.`</span><span class="p">;</span></span></span></code></pre></div></div>
<p>模型内部大概是这样运转的：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">&lt;think&gt;
</span></span><span class="line"><span class="cl">INTENT: create a job
</span></span><span class="line"><span class="cl">HAVE: customer query &#34;Smith&#34;
</span></span><span class="line"><span class="cl">NEED: exact customer_id
</span></span><span class="line"><span class="cl">DECISION: search first
</span></span><span class="line"><span class="cl">&lt;/think&gt;
</span></span><span class="line"><span class="cl">&lt;action&gt;{&#34;type&#34;:&#34;search_customers&#34;,&#34;query&#34;:&#34;Smith&#34;}&lt;/action&gt;</span></span></code></pre></div></div>
<p><code>&lt;think&gt;</code> 标签在进 UI 之前会被剥掉，开发阶段我会留着它们调试。效果非常明显：模型会先把逻辑捋顺，再决定动手。</p>

<h2 class="relative group">把长对话塞进 8K 上下文
    <div id="把长对话塞进-8k-上下文" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%8a%8a%e9%95%bf%e5%af%b9%e8%af%9d%e5%a1%9e%e8%bf%9b-8k-%e4%b8%8a%e4%b8%8b%e6%96%87" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>工具结果一多，8K 上下文窗口比想象中满得快。我这边大约 30 轮就顶到上限了。</p>
<p>我的办法是对话压缩，让模型自己总结自己：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">compactPrompt</span> <span class="o">=</span> <span class="sb">`Summarize this conversation in under 200 words.
</span></span></span><span class="line"><span class="cl"><span class="sb">Include: user&#39;s goal, customers/jobs created (with IDs), and any unfinished tasks.
</span></span></span><span class="line"><span class="cl"><span class="sb">
</span></span></span><span class="line"><span class="cl"><span class="si">${</span><span class="nx">conversationHistory</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="nx">m</span> <span class="o">=&gt;</span> <span class="sb">`</span><span class="si">${</span><span class="nx">m</span><span class="p">.</span><span class="nx">role</span><span class="si">}</span><span class="sb">: </span><span class="si">${</span><span class="nx">m</span><span class="p">.</span><span class="nx">content</span><span class="si">}</span><span class="sb">`</span><span class="p">).</span><span class="nx">join</span><span class="p">(</span><span class="s1">&#39;\n\n&#39;</span><span class="p">)</span><span class="si">}</span><span class="sb">`</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">summary</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">chat</span><span class="p">([{</span> <span class="nx">role</span><span class="o">:</span> <span class="s2">&#34;user&#34;</span><span class="p">,</span> <span class="nx">content</span>: <span class="kt">compactPrompt</span> <span class="p">}]);</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1">// Replace history with summary
</span></span></span><span class="line"><span class="cl"><span class="nx">conversationHistory</span> <span class="o">=</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">  <span class="p">{</span> <span class="nx">role</span><span class="o">:</span> <span class="s2">&#34;user&#34;</span><span class="p">,</span> <span class="nx">content</span><span class="o">:</span> <span class="sb">`[CONTEXT SUMMARY]</span><span class="err">\</span><span class="sb">n</span><span class="si">${</span><span class="nx">summary</span><span class="si">}</span><span class="err">\</span><span class="sb">n[END SUMMARY]`</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">];</span></span></span></code></pre></div></div>
<p>50 条消息的对话能压到 150 个 token 左右，模型接着聊，也不会忘记之前建了哪些工作单、客户 ID 是多少。</p>

<h2 class="relative group">会话保存
    <div id="会话保存" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%bc%9a%e8%af%9d%e4%bf%9d%e5%ad%98" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>聊天会话也会存到应用的后端。值得借鉴的一点是：每条助手消息存两份，一份清理过、用于显示，一份保留 <code>&lt;think&gt;</code> 和 <code>&lt;action&gt;</code> 标签的原文。这样聊天记录在界面上回放时干干净净，恢复会话时又能拿回包含 action 在内的完整上下文。用户可以像用一般的聊天应用那样，在历史下拉菜单里切换对话。</p>

<h2 class="relative group">生产环境的性能数据
    <div id="生产环境的性能数据" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%94%9f%e4%ba%a7%e7%8e%af%e5%a2%83%e7%9a%84%e6%80%a7%e8%83%bd%e6%95%b0%e6%8d%ae" aria-label="锚点">#</a>
    </span>
    
</h2>
<p><strong>iPhone 14 Pro</strong>（A16 Bionic，6GB RAM）：</p>
<ul>
<li>模型加载：约 3 秒</li>
<li>首个 token：180-220ms</li>
<li>流式输出：14-16 tokens/秒</li>
<li>内存：约 1.8 GB</li>
</ul>
<p><strong>Samsung Galaxy S23</strong>（Snapdragon 8 Gen 2，8GB RAM）：</p>
<ul>
<li>模型加载：约 4 秒</li>
<li>首个 token：250-300ms</li>
<li>流式输出：10-12 tokens/秒</li>
<li>内存：约 2.1 GB</li>
</ul>
<p><strong>iPhone 11</strong>（A13，4GB RAM）：</p>
<ul>
<li>模型加载：约 6 秒</li>
<li>首个 token：400-500ms</li>
<li>流式输出：6-8 tokens/秒</li>
<li>内存：约 2.2 GB（内存吃紧时偶尔崩溃）</li>
</ul>
<p>我的经验值：想用得顺畅，RAM 至少 6GB。4GB 也能跑，但应用退到后台时多半得把模型卸载掉。</p>

<h2 class="relative group">内存管理
    <div id="内存管理" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%86%85%e5%ad%98%e7%ae%a1%e7%90%86" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>应用占着太多内存，iOS 会毫不客气地把它杀掉，所以一离开前台我就释放模型：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="nx">useEffect</span><span class="p">(()</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="nx">subscription</span> <span class="o">=</span> <span class="nx">AppState</span><span class="p">.</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s2">&#34;change&#34;</span><span class="p">,</span> <span class="p">(</span><span class="nx">nextAppState</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="p">(</span><span class="nx">nextAppState</span> <span class="o">===</span> <span class="s2">&#34;background&#34;</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">llamaContext</span><span class="o">?</span><span class="p">.</span><span class="nx">release</span><span class="p">();</span> <span class="c1">// Free ~2 GB
</span></span></span><span class="line"><span class="cl">    <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="nx">nextAppState</span> <span class="o">===</span> <span class="s2">&#34;active&#34;</span><span class="p">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">loadModel</span><span class="p">();</span> <span class="c1">// Reload when foregrounded
</span></span></span><span class="line"><span class="cl">    <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">});</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="p">()</span> <span class="o">=&gt;</span> <span class="nx">subscription</span><span class="p">.</span><span class="nx">remove</span><span class="p">();</span>
</span></span><span class="line"><span class="cl"><span class="p">},</span> <span class="p">[]);</span></span></span></code></pre></div></div>

<h2 class="relative group">电量消耗
    <div id="电量消耗" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%94%b5%e9%87%8f%e6%b6%88%e8%80%97" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>端侧推理在电量上不是免费的。实测数据：</p>
<table>
	<thead>
			<tr>
					<th>使用模式</th>
					<th>额外电池消耗</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>轻度（每天 5-10 次查询）</td>
					<td>每天 &lt;1%</td>
			</tr>
			<tr>
					<td>中度（每天 20-30 次查询）</td>
					<td>每天约 3-4%</td>
			</tr>
			<tr>
					<td>重度（每天 50+ 次查询）</td>
					<td>每天约 6-8%</td>
			</tr>
	</tbody>
</table>
<p>GPU 推理比 CPU 费电，但快得多。用户明显更喜欢秒回，所以我保留了 GPU。</p>

<h2 class="relative group">上线两个月，约 200 名测试用户
    <div id="上线两个月约-200-名测试用户" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%8a%e7%ba%bf%e4%b8%a4%e4%b8%aa%e6%9c%88%e7%ba%a6-200-%e5%90%8d%e6%b5%8b%e8%af%95%e7%94%a8%e6%88%b7" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>查询的分布有点出乎意料：</p>
<ol>
<li>&ldquo;Create a job for [customer name]&rdquo; - 占查询的 68%</li>
<li>&ldquo;Find jobs for [customer]&rdquo; - 15%</li>
<li>&ldquo;Update job [ID] to [status]&rdquo; - 9%</li>
<li>关于应用本身的问题 - 8%</li>
</ol>
<p>91% 的查询一次就成功。失败的原因分三类：用户把客户名字拼错导致搜不到（4%），超长对话撑爆上下文（3%），模型自己编客户 ID（2%）。</p>
<p>最后这个编 ID 的毛病以前严重得多。后来我把工具结果从叙述句改成 <code>customer_id=42</code> 这样的显式字段，问题基本消失了。小模型就是需要把饭喂到这个程度。</p>

<h2 class="relative group">成本账
    <div id="成本账" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%90%e6%9c%ac%e8%b4%a6" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>端侧方案：基础设施 $0/月，除了首次那 1.1 GB 下载，每个用户的成本是 $0，用户再多也是这个数。</p>
<p>云端方案粗算一下：平均一次对话约 2,000 个 token，200 个用户每月 30 次对话就是 6,000 次，也就是每月 1200 万 token。便宜的云端模型大约 $18/月，顶级模型则要 $180 到 $360/月。这个规模不至于伤筋动骨，但端侧方案第一天就回了本，哪怕涨到一万用户，还是 $0。</p>

<h2 class="relative group">得心里有数的几个限制
    <div id="得心里有数的几个限制" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%be%97%e5%bf%83%e9%87%8c%e6%9c%89%e6%95%b0%e7%9a%84%e5%87%a0%e4%b8%aa%e9%99%90%e5%88%b6" aria-label="锚点">#</a>
    </span>
    
</h2>
<p><strong>模型能力。</strong> Qwen 1.7B 擅长结构化任务，但多跳的复杂推理、事实性知识（它不是搜索引擎）、创意写作、语言里的微妙之处，它都不行。围绕小模型擅长的事来设计功能，就不会失望。</p>
<p><strong>设备要求。</strong> 底线是 3 GB RAM 加 2 GB 可用存储；实际上你需要 6 GB RAM、64 位处理器和 GPU 支持。iPhone 8、Galaxy S9 这类老设备很吃力，记得做特性检测和体面的降级。</p>
<p><strong>模型更新。</strong> 换模型意味着用户要重新下载 1.1 GB。我把版本号写进了存储路径：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">MODEL_PATH</span> <span class="o">=</span> <span class="sb">`</span><span class="si">${</span><span class="nx">FileSystem</span><span class="p">.</span><span class="nx">documentDirectory</span><span class="si">}</span><span class="sb">llama-models/v2/Qwen3-1.7B-Q4_K_M.gguf`</span><span class="p">;</span></span></span></code></pre></div></div>
<p>发新模型时把路径版本号加一就行，旧模型在应用卸载时自动清掉。</p>

<h2 class="relative group">iOS 和 Android 的差异
    <div id="ios-和-android-的差异" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#ios-%e5%92%8c-android-%e7%9a%84%e5%b7%ae%e5%bc%82" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>走 Metal 的 iOS 比 Android 快 20% 左右，内存管理也更好，模型默认会备份到 iCloud（不想占用户备份空间的话，用 <code>NSURLIsExcludedFromBackupKey</code> 排除掉）。Android 机型间的差异则大得多：llama.rn 的 GPU 路径是高通 Adreno 700 系列 GPU 上的 OpenCL，没有这类 GPU 的手机就只能跑在 CPU 上；存储也不会自动备份。两个平台都得测。好安卓机和差安卓机之间的差距，比两个平台之间的差距还大。</p>

<h2 class="relative group">调试技巧
    <div id="调试技巧" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e8%b0%83%e8%af%95%e6%8a%80%e5%b7%a7" aria-label="锚点">#</a>
    </span>
    
</h2>
<p><strong>1. 打开详细日志</strong></p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">ctx</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">initLlama</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">model</span>: <span class="kt">MODEL_PATH</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">n_ctx</span>: <span class="kt">8192</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">n_gpu_layers</span>: <span class="kt">99</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">verbose</span>: <span class="kt">true</span><span class="p">,</span> <span class="c1">// Logs every token + timings
</span></span></span><span class="line"><span class="cl"><span class="p">});</span></span></span></code></pre></div></div>
<p><strong>2. 跟踪 token 数量</strong></p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">tokens</span> <span class="o">=</span> <span class="nx">fullResponse</span><span class="p">.</span><span class="nx">split</span><span class="p">(</span><span class="sr">/\s+/</span><span class="p">).</span><span class="nx">length</span> <span class="o">*</span> <span class="mf">1.3</span><span class="p">;</span> <span class="c1">// Rough estimate
</span></span></span><span class="line"><span class="cl"><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="sb">`Generated </span><span class="si">${</span><span class="nx">tokens</span><span class="si">}</span><span class="sb"> tokens in </span><span class="si">${</span><span class="nx">duration</span><span class="si">}</span><span class="sb">ms`</span><span class="p">);</span></span></span></code></pre></div></div>
<p><strong>3. 监控内存</strong></p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-typescript" data-lang="typescript"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">MemoryInfo</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;react-native-device-info&#39;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">memoryUsage</span> <span class="o">=</span> <span class="k">await</span> <span class="nx">MemoryInfo</span><span class="p">.</span><span class="nx">getUsedMemory</span><span class="p">();</span>
</span></span><span class="line"><span class="cl"><span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="sb">`Memory: </span><span class="si">${</span><span class="p">(</span><span class="nx">memoryUsage</span> <span class="o">/</span> <span class="mi">1024</span> <span class="o">/</span> <span class="mi">1024</span><span class="p">).</span><span class="nx">toFixed</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span><span class="si">}</span><span class="sb"> MB`</span><span class="p">);</span></span></span></code></pre></div></div>
<p><strong>4. 离线测试</strong></p>
<p>开飞行模式，认真把应用用一遍。模型应该从缓存加载，推理应该完整跑完，唯一失败的应该只有后端持久化，而且要败得体面。</p>

<h2 class="relative group">接下来想做的
    <div id="接下来想做的" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%8e%a5%e4%b8%8b%e6%9d%a5%e6%83%b3%e5%81%9a%e7%9a%84" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>llama.cpp 已经支持视觉模型，&ldquo;这是现场的照片，加到工作单里&quot;这种用法跟这个应用简直是天作之合。我还想拿过去的工作单描述和客户对话微调一个 LoRA 适配器，估计领域内查询的准确率能涨 20-30%。再远一点：配上端侧语音识别模型做完全离线的语音助手，以及在原始数据不出手机的前提下，用联邦学习让模型在所有用户间共同进步。</p>

<h2 class="relative group">值不值得做？
    <div id="值不值得做" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%80%bc%e4%b8%8d%e5%80%bc%e5%be%97%e5%81%9a" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>如果你在做处理敏感数据的业务应用，走离线优先的工作流，主要任务是分类、录入、搜索这类结构化工作，尤其是担心规模上去之后的 API 账单，那答案是值得，今天就能动手。</p>
<p>如果你要的是开放式聊天，用大型云端模型。知识密集型任务（小模型真的没什么见识）、必须支持低端设备、领域知识变化快过你更新模型的速度，这几种情况也一样。</p>
<p>整个实现花了我 12 个小时左右。每月运行成本 $0，飞机上照常工作，客户数据从头到尾没离开过客户的手机。挑不出毛病。</p>
<hr>
<p><em>有问题或想聊聊？我是 <a href="https://twitter.com/jaredlynskey"  target="_blank" rel="noreferrer">@jaredlynskey</a>。llama.rn 库在 <a href="https://github.com/mybigday/llama.rn"  target="_blank" rel="noreferrer">github.com/mybigday/llama.rn</a>。</em></p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-01-30-on-device-ai/featured.jpg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
