T3 Code 移动端开发实战指南:Expo Dev Client 三变体构建、iOS 本地打包与 EAS 云构建全流程

原创2026-09-15 14:41:021,968 阅读
文章标签:AI Agent代码智能体人工智能桌面应用前端后端移动开发CLI交互助手版本控制远程访问

T3 Code 移动端开发实战指南:Expo Dev Client 三变体构建、iOS 本地打包与 EAS 云构建全流程

导读

本文基于 T3 Code 仓库的 apps/mobile/README.md 成文,系统讲解该项目移动端(Expo / React Native)的完整开发与发布工作流:从 development、preview、production 三种构建变体的定位差异,到本地 Metro 开发、iOS 模拟器/真机构建、Personal Team 降级构建、原生代码静态检查,再到基于 Expo 指纹(fingerprinting)的 EAS 云构建与 OTA 更新策略。读完本文,你将掌握这套移动端工程的启动命令、环境变量体系、变体配置原理与云构建参数,并理解仓库中对应源码与配置之间的映射关系,可直接照搬到自己的 Expo 工程。

需要先说明的是:T3 Code Mobile 目前仍处于开发阶段,尚未对外分发(见 apps/mobile/README.md 顶部警告)。想体验它只能从源码自行构建,本文所有命令均以此为前提。


一、工程概况与前置条件

T3 Code 移动端位于 apps/mobile 目录,是一个基于 Expo SDK 57(expo@~57.0.18)与 React Native 0.86 的 iOS / Android 双端工程。从 apps/mobile/package.json 可以看到其技术栈特征:

  • 核心依赖:expo-dev-client、expo-updates、@clerk/expo(认证)、@t3tools/client-runtime、@t3tools/contracts、@t3tools/shared 等 workspace 内包;
  • 原生模块:通过 file: 依赖引入 modules/ 下的 7 个本地原生模块(modules 目录):t3-agent-notifications、t3-composer-editor、t3-markdown-text、t3-native-controls、t3-review-diff、t3-subscription-widget、t3-terminal,涉及 Nitro 模块、Kotlin/Swift 双端实现;
  • 渲染与样式:uniwind(Tailwind 风格)、react-native-nitro-markdown、@shikijs/*(代码高亮)、react-native-reanimated。

为什么不能使用 Expo Go

[!NOTE] 由于工程使用原生模块(native modules),Expo Go 不受支持,必须使用 Expo Dev Client(expo-dev-client)。这是因为本地原生模块需要在构建阶段编译进 App 二进制,Expo Go 的沙箱环境无法加载自定义原生代码。

仓库级命令运行器 vp

README 中的示例命令均以 vp run <script> 形式出现(如 vp run dev:client),其实际执行体是 apps/mobile/package.json 的 scripts 字段。例如:

"dev:client": "APP_VARIANT=development expo start --dev-client --scheme t3code-dev --lan",
"ios:dev": "APP_VARIANT=development EXPO_NO_GIT_STATUS=1 expo prebuild --clean --platform ios && expo run:ios"

因此 vp run dev:client 等价于在 apps/mobile 目录下执行上述带环境变量的 expo start 命令。仓库根 t3.json 的 Setup Worktree 脚本也使用了 vp i 来安装依赖,说明 vp 是仓库统一封装的任务运行入口。


二、三种构建变体:development / preview / production

该 App 在同一份源码上维护三种构建变体(variant),通过环境变量 APP_VARIANT 区分,用于隔离开发、内测与发布场景:

变体 App 显示名 URL Scheme 用途
development T3 Code Dev t3code-dev Expo Dev Client 本地开发,可与正式版并排安装(side-by-side)
preview T3 Code Preview t3code-preview 持久化的内部预览包,同样并排安装
production T3 Code t3code 面向商店 / 正式发布的构建

上述映射定义在 apps/mobile/app.config.ts 的 VARIANT_CONFIG 中,每个变体还包含独立的 iOS Bundle Identifier 与 Android Package:

  • development:com.t3tools.t3code.dev
  • preview:com.t3tools.t3code.preview
  • production:com.t3tools.t3code

三套变体还各自绑定一套品牌资源(App 图标、启动图、Android 自适应图标与通知图标等),由 app.config.ts 中 DEVELOPMENT_ASSETS、PREVIEW_ASSETS、RELEASE_ASSETS 三组配置按变体注入。APP_VARIANT 未设置时,resolveAppVariant 默认回退为 production。

变体的启动命令

在 apps/mobile/package.json 中可以看到每个变体对应的本地启动脚本:

"start:dev": "APP_VARIANT=development expo start",
"start:preview": "APP_VARIANT=preview expo start",
"start:prod": "APP_VARIANT=production expo start"

三、环境变量与公共配置

T3 Connect 与配置放置位置

T3 Connect(连接中继服务)在全新克隆的仓库中是可选且默认关闭的。公共配置应放在仓库根目录的 .env 或 .env.local,而不是 apps/mobile/.env。参考模板见 .env.example。

该加载逻辑由 scripts/lib/public-config.ts 的 loadRepoEnv 实现:它会依次读取仓库根 .env、.env.local 以及当前进程环境,并遵循 进程环境 > .env.local > .env 的优先级覆盖规则(firstNonEmpty 逐个取第一个非空值)。

关键映射逻辑在于:public-config.ts 会把 T3CODE_CLERK_PUBLISHABLE_KEY 同步映射为 EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY、把 T3CODE_RELAY_URL 映射为 VITE_T3CODE_RELAY_URL 等,从而让 Expo 与 Web 端共用同一份公共配置。随后 app.config.ts 在加载配置时调用 loadRepoEnv() 并把结果注入 process.env,供 Expo 配置解析使用。

关键公共环境变量(来自 .env.example)

变量 说明
T3CODE_CLERK_PUBLISHABLE_KEY 生产环境 Clerk 实例的公开发布密钥(非机密);.env.example 中已内置官方发布构建所用的值
T3CODE_CLERK_JWT_TEMPLATE Clerk JWT 模板名,默认 t3-relay
T3CODE_RELAY_URL 中继服务地址,默认 https://relay.t3.codes;自托管 relay 见 infra/relay
T3CODE_CLERK_CLI_OAUTH_CLIENT_ID CLI 的 OAuth Client ID
T3CODE_MOBILE_OTLP_TRACES_URL / _DATASET / _TOKEN 移动端 OpenTelemetry 追踪(只读 ingest 配置,可选)

注意:.env.example 明确标注这些是"官方发布构建中硬编码的公共标识符,而非密钥",不要把服务端机密写入该文件。

云构建环境变量

对于 preview / production 的 EAS 构建环境,需要设置以下三个变量(以 EAS 环境变量形式传入):

  • T3CODE_CLERK_PUBLISHABLE_KEY
  • T3CODE_CLERK_JWT_TEMPLATE
  • T3CODE_RELAY_URL

它们会被 Expo 配置映射为移动端构建中的规范值(见 app.config.ts 的 extra.clerk 与 extra.relay 字段)。


四、本地开发:Metro、Dev Client 与热更新

启动 Metro(Dev Client)

vp run dev:client

等价于 APP_VARIANT=development expo start --dev-client --scheme t3code-dev --lan:以 development 变体、t3code-dev scheme 启动带 dev client 的 Metro,并通过 --lan 走局域网。

清除 Metro 缓存启动

Metro 在常规启动之间会保留 transform 缓存。当缓存本身导致输出过期或不正确时,可清空缓存启动一次:

vp run dev:client:reset

对应脚本为 expo start --dev-client --scheme t3code-dev --clear --lan。README 特别提醒:

安装或修改 Uniwind 依赖补丁之后,必须执行一次 reset 启动。 否则缓存中的 transform 可能仍引用 Uniwind 上一个 pnpm 包路径。普通 Metro 启动仍会保留缓存。

这一点与 patches/uniwind@1.11.0.patch 以及 metro.config.js 中通过 withUniwindConfig(config, { cssEntryFile: "./global.css", extraThemes, polyfills: { rem: 14 } }) 接入 Uniwind 的配置直接相关:Metro 缓存的模块路径一旦因 pnpm 补丁哈希变化而失效,就会产出陈旧结果。

Fast Refresh 与 HMR 边界

普通组件编辑直接走 Fast Refresh。但如果要改动运行时所有权或刷新行为(例如 connection runtime 的 Effect 层替换),务必先阅读 docs/internals/mobile-development.md。该文档揭示了几个重要的开发期约束:

  1. HMR 边界:connection runtime 通过 apps/mobile/src/lib/hot-swappable-atom-runtime.ts 保持稳定的 atom 运行时,并以可写 atom 替换 Effect layer;只有新 layer 安装成功后才接受更新,否则即使 Metro 提示刷新成功,导入方仍会沿用旧行为。
  2. 不要重置共享 atom 注册表:重置会移除已挂载消费者的监听器,而 Metro 并没有理由触发这些消费者重渲染。
  3. 环境 supervisor 的作用域:环境级 supervisor 是 registry scope 的子级(见 packages/client-runtime/src/connection/registry.ts),关闭的父作用域会连带关闭迟到的子级,避免中断的启动或运行时替换让 WebSocket 残留在新注册表之外。
  4. Uniwind 补丁行为:补丁在 Metro 更新时仍会编译 CSS 以发现新类;只有生成的样式表和主题列表都未变化时才跳过全局样式失效。

原生模块开发的特殊注意点

modules/ 下的原生模块以 file: 依赖引入,pnpm 会将其复制进虚拟 store 而非软链接,Metro 打包的是副本。因此:

修改某个原生模块的 TypeScript 源码后,正在运行的 dev client 不会立即生效,需要先 vp i 重新同步;而 Gradle 与 CocoaPods 编译的则是工作区目录本身。如果你在真机上修改 JS 后"毫无效果",通常就是这个原因。


五、iOS 本地构建

1. 构建并运行本地 iOS Dev Client

vp run ios:dev

等价于 APP_VARIANT=development expo prebuild --clean --platform ios && expo run:ios:先清理生成原生工程(--clean),再构建运行。EXPO_NO_GIT_STATUS=1 用于跳过 git 状态检查。

2. 修改原生依赖补丁后必须先重跑 CocoaPods

每次改动原生依赖补丁后,重新构建既有 iOS 工程前必须先重跑 CocoaPods。因为 pnpm 会为每个补丁哈希分配新的包路径,Pods 可能仍在编译旧目录。

3. 构建并安装不依赖 Metro 的自包含 Release 包

vp run ios:release

对应脚本 APP_VARIANT=production expo prebuild --clean --platform ios && expo run:ios --configuration Release --no-bundler。--no-bundler 表示不打 Metro bundle 即可独立运行(发布包)。

4. 构建并运行本地 iOS Preview 包

vp run ios:preview

即 APP_VARIANT=preview expo prebuild --clean --platform ios && expo run:ios。

5. 检查解析后的 Expo 配置

vp run config:dev
vp run config:preview

分别对应 APP_VARIANT=development expo config 与 APP_VARIANT=preview expo config,用于检查某个变体最终解析出的 Expo 配置(含插件、图标、权限描述等)。


六、Personal Team 降级构建(无付费开发者账号场景)

如果 Xcode 账号只有 Personal Team(个人团队),需要:

  1. 使用自己控制的 Bundle Identifier;
  2. 显式开启降级能力(reduced-capability)的本地构建。

开启后,Personal Team 构建会省略以下能力:

  • Widget 与 Share Extension(扩展目标)
  • Push(推送)entitlement
  • 原生 Sign in with Apple entitlement

而未开启此选项的构建不受影响。对应的本地开发构建命令:

T3CODE_IOS_PERSONAL_TEAM=1 \
T3CODE_IOS_PERSONAL_TEAM_BUNDLE_ID=com.example.t3code.dev \
vp run ios:dev

自包含 Release 构建同样需要唯一 Bundle Identifier:

T3CODE_IOS_PERSONAL_TEAM=1 \
T3CODE_IOS_PERSONAL_TEAM_BUNDLE_ID=com.example.t3code \
vp run ios:release

其底层逻辑在 app.config.ts 中:当 T3CODE_IOS_PERSONAL_TEAM === "1" 时,iosBundleIdentifier 被替换为 T3CODE_IOS_PERSONAL_TEAM_BUNDLE_ID,且该值必须通过反向 DNS 格式校验(正则 ^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$),否则配置解析直接抛错。同时,配置会:


七、Review Diff 高亮引擎选择

T3 Code 的 review diff 界面支持两种代码高亮引擎,通过公共环境变量切换:

EXPO_PUBLIC_REVIEW_HIGHLIGHTER_ENGINE=javascript vp run ios:dev
  • javascript:默认且推荐,用于 review diff 界面;
  • native:仅在明确想测试原生 Shiki 引擎(react-native-shiki-engine)时设置。

这与 apps/mobile/package.json 中同时依赖 @shikijs/engine-javascript、@shikijs/core 等 Shiki 系包,以及 metro.config.js 将 shiki、@shikijs/* 系列解析到统一根目录的配置相呼应。


八、原生代码静态检查

运行移动端原生静态检查

node ../../scripts/mobile-native-static-check.ts

该脚本位于 scripts/mobile-native-static-check.ts,其核心逻辑(runNativeStaticChecks)为:

  1. 递归收集 apps/mobile 下的 Swift(.swift)与 Kotlin(.kt / .kts)源码文件;
  2. 自动跳过 .expo、.git、build、DerivedData、node_modules、Pods、Vendor 等目录,以及生成的原生工程目录 android/、ios/(见 collectSources 的排除集);
  3. 依次执行工具(按源码可用性):
语言 工具 实际命令
Swift SwiftLint swiftlint lint --config .swiftlint.yml --strict
Kotlin ktlint ktlint <相对源码路径...>
Kotlin detekt detekt --config detekt.yml --input <路径> --build-upon-default-config

缺失工具时的行为

若本机缺少 SwiftLint / ktlint / detekt,脚本会以 warning 形式报告并跳过对应检查,不会阻塞本地开发。CI 则会先从 apps/mobile/Brewfile 安装默认工具集再执行检查:

brew "swiftlint"
brew "ktlint"
brew "detekt"

本地也可按脚本提示执行 brew bundle install --file apps/mobile/Brewfile 补齐工具。


九、EAS 云构建与 OTA 更新策略

Expo 指纹(Fingerprinting)机制

Preview 与 production 变体使用 Expo fingerprinting(原生指纹),确保 OTA 更新只投递给原生依赖、config plugins 与补丁完全匹配的二进制。CI 使用 preview:dev profile 以便在可能的情况下复用兼容的原生构建。

MOBILE_VERSION_POLICY 版本策略

不同变体采用不同的 runtimeVersion 策略(定义于 app.config.ts 与 runtimeVersion.policy 字段):

变体 默认策略 原因
development appVersion 每次启动都会解析 development manifest,避免为每个 Metro 启动清单重复计算昂贵的原生指纹
preview / production fingerprint 保持指纹化,确保 OTA 只到达原生工程匹配的二进制

MOBILE_VERSION_POLICY 可覆盖任一变体的默认值。特别提醒:

如果你用 development 身份分发自定义 Release 构建,并向其发布 OTA 更新,必须在构建与更新两侧都设置 MOBILE_VERSION_POLICY=fingerprint。修改运行时策略后,OTA 匹配需要一次原生重建;已存在的 dev client 仍可加载本地 Metro bundle。

EAS Profiles(来自 apps/mobile/eas.json)

Profile 变体 关键配置
development development channel: development,developmentClient: true,distribution: internal
preview preview channel: preview,environment: preview,distribution: internal
preview:dev preview channel: preview,强制 MOBILE_VERSION_POLICY=fingerprint,developmentClient: true,Android 侧 buildType: apk
production production channel: production,autoIncrement: true

所有 profile 均启用 corepack 并设置 NODE_OPTIONS=--max-old-space-size=4096 以应对大内存构建。另外注意 eas.json 的 cli.appVersionSource: "remote",以及 submit.production 中已配置的 App Store Connect App ID(ascAppId: "6787819824")与 Android internal track。

常用 EAS 构建命令

创建 PR 预览用的 dev-client 构建(手动):

vp run eas:ios:preview:dev

创建云端 dev-client 构建:

vp run eas:ios:dev

创建持久化 preview 构建:

vp run eas:ios:preview

Android 对应命令:

vp run eas:android:dev
vp run eas:android:preview:dev
vp run eas:android:preview

这些命令在 apps/mobile/package.json 中均映射为 eas build --profile <profile> -p <platform>(另有不带平台的 eas:dev / eas:preview / eas:preview:dev / eas:prod 变体)。


十、常见问题速查

现象 处理方式
修改原生模块 TS 后设备上无变化 执行 vp i 重新同步(pnpm 复制而非软链接)
安装/修改 Uniwind 补丁后构建异常 执行一次 vp run dev:client:reset 清缓存启动
修改原生依赖补丁后 iOS 构建失败 重新运行 CocoaPods 后再构建
只有 Personal Team 账号 设置 T3CODE_IOS_PERSONAL_TEAM=1 与合法反向 DNS 的 T3CODE_IOS_PERSONAL_TEAM_BUNDLE_ID
想用 Expo Go 打开 不支持,改用 Dev Client(vp run dev:client)
OTA 更新投递不到自定义 Release 构建与更新两侧统一设置 MOBILE_VERSION_POLICY=fingerprint

结语

T3 Code 移动端通过"三变体 + 单源码树"的工程组织,把本地开发(dev client)、内部预览(preview)与商店发布(production)统一在一套 Expo 配置之下;配合仓库根的公共配置加载(scripts/lib/public-config.ts)、EAS 指纹化 OTA(eas.json)与原生静态检查流水线(scripts/mobile-native-static-check.ts),形成了一条从源码构建到云发布、前后端联动的完整链路。若你希望进一步了解移动端运行时生命周期与原生模块维护细节,可继续阅读 docs/internals/mobile-development.md 与 apps/mobile 下各原生模块源码。

登录后查看全文
t3code