T3 Code 移动端开发实战指南:Expo Dev Client 三变体构建、iOS 本地打包与 EAS 云构建全流程
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_KEYT3CODE_CLERK_JWT_TEMPLATET3CODE_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。该文档揭示了几个重要的开发期约束:
- HMR 边界:connection runtime 通过 apps/mobile/src/lib/hot-swappable-atom-runtime.ts 保持稳定的 atom 运行时,并以可写 atom 替换 Effect layer;只有新 layer 安装成功后才接受更新,否则即使 Metro 提示刷新成功,导入方仍会沿用旧行为。
- 不要重置共享 atom 注册表:重置会移除已挂载消费者的监听器,而 Metro 并没有理由触发这些消费者重渲染。
- 环境 supervisor 的作用域:环境级 supervisor 是 registry scope 的子级(见 packages/client-runtime/src/connection/registry.ts),关闭的父作用域会连带关闭迟到的子级,避免中断的启动或运行时替换让 WebSocket 残留在新注册表之外。
- 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(个人团队),需要:
- 使用自己控制的 Bundle Identifier;
- 显式开启降级能力(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-]+)+$),否则配置解析直接抛错。同时,配置会:
- 关闭 sharing 扩展的 iOS 侧(
enabled: !isIosPersonalTeamBuild,见 app.config.ts),因为个人团队无法签署 App Group 与扩展目标; - 跳过 widget 插件(app.config.ts),并追加 plugins/withoutIosPersonalTeamCapabilities.cjs 移除多余 capability;
- 对 Clerk 关闭
appleSignIn(app.config.ts)。
七、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)为:
- 递归收集
apps/mobile下的 Swift(.swift)与 Kotlin(.kt/.kts)源码文件; - 自动跳过
.expo、.git、build、DerivedData、node_modules、Pods、Vendor等目录,以及生成的原生工程目录android/、ios/(见collectSources的排除集); - 依次执行工具(按源码可用性):
| 语言 | 工具 | 实际命令 |
|---|---|---|
| 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 下各原生模块源码。