WorkBuddy真机上线六阶段实录：iOS/Android跨端发布避坑指南

1. 这不是教程，是六个阶段踩出来的真机上线实录

WorkBuddy 不是另一个“低代码平台”的营销话术，它是个真实存在的、面向开发者工作流的协作型开发环境——你可以把它理解成 VS Code 的团队增强版：自带 Git 集成、任务看板、实时协同编辑、内置终端和轻量级服务编排能力。但关键在于，它不承诺“一键发布 App”，恰恰相反，它把发布这件事拆解得足够透明，也足够残酷。我用它从零搭起一个跨端图书管理 App（核心功能：扫码录入、本地缓存、离线同步、iOS/Android 双端真机运行），前后耗时 17 天，经历六轮完整迭代，填平十六个明确可复现的坑。这些坑里，没有一个来自 WorkBuddy 自身崩溃或 UI 卡顿，全部出在“从开发环境到真实设备”这条链路上——证书配置错一位、签名配置漏一行、真机调试权限没开、iOS 的 ATS 配置没关、Android 的 targetSdkVersion 和 buildToolsVersion 版本冲突、甚至只是 Xcode 中某个 Build Rule 被自动重置……它们不写在任何官方文档里，却真实卡住每一个想把 App 装进自己口袋的人。

如果你正站在这个节点：代码写完了，模拟器跑通了，但第一次连上 iPhone 就报 “No code signing identity found”，或者打包 APK 后安装失败提示 “INSTALL_FAILED_INVALID_APK”，又或者发布 TestFlight 后等了三天收不到安装邮件——那你不是技术不行，是还没撞上那堵墙。这篇内容就是那堵墙的结构图：它告诉你墙在哪、多厚、用什么工具能凿穿、凿穿后里面是什么、以及下次怎么绕开。全文不讲 WorkBuddy 基础操作（官网有视频），不堆砌命令行（每个命令都附带执行意图和失败回溯逻辑），所有内容基于 iOS 17.5 / Android 14 真机环境、Xcode 15.4 / Android Studio Giraffe、WorkBuddy v2.3.1 实测验证。适合两类人：一是刚用 WorkBuddy 写完第一个页面、准备上线却卡在签名环节的前端/全栈开发者；二是团队技术负责人，需要评估 WorkBuddy 是否真能承载从开发到发布的闭环流程。它解决的不是“能不能做”，而是“怎么做才不返工三次”。

2. 六个阶段：从 WorkBuddy 项目创建到 AppStore 审核通过的完整路径

2.1 阶段一：环境锚定与项目初始化（2.5 天）

这不是“新建项目”那么简单。WorkBuddy 的优势在于环境一致性，但它的陷阱也藏在这里——它默认继承宿主系统的 Node.js、Java、Python 版本，而这些版本与后续构建链路强耦合。我最初用系统自带的 Node 16.14 + Java 11，在 Android 构建时卡在Could not resolve all task dependencies for configuration ':app:debugCompileClasspath'，查了三小时才发现是 Gradle 插件 8.2 要求 Java 17，而 WorkBuddy 的 Terminal 默认没切换 JDK。解决方案不是升级系统 JDK（会破坏其他项目），而是在 WorkBuddy 项目根目录下新建.java-version文件写入17.0.1，再在项目设置里勾选 “Use project-specific JDK”。同理，Node 版本用.nvmrc锁定为18.18.2，并确保 WorkBuddy 的集成终端启动时自动加载 nvm。

提示：WorkBuddy 的 “Project Settings → Environment” 页面里，“Shell Profile” 选项必须设为~/.zshrc（macOS）或~/.bashrc（Linux），否则.nvmrc和.java-version不生效。这是第一个坑，90% 的人忽略，直到构建失败才回头检查。

初始化阶段真正的核心是平台目标定义。WorkBuddy 创建新项目时，会让你选择 “Web App”、“Mobile App” 或 “Desktop App”。选 “Mobile App” 后，它会生成 Capacitor 框架结构（而非 Cordova 或 React Native CLI），这是关键决策点。Capacitor 的优势在于原生桥接更干净、插件生态更现代，但代价是 iOS 构建必须依赖 Xcode，Android 必须依赖 Android Studio。这意味着你不能只靠 WorkBuddy 完成全部构建——它负责代码管理、调试、热更新推送，但最终的 IPA/APK 打包必须跳转到原生 IDE。我在阶段一开始就在 README.md 里写下三行硬约束：

- iOS 构建：仅支持 Xcode 15.2+，必须启用 Automatic Signing - Android 构建：仅支持 Android Studio Giraffe+，targetSdkVersion=34，compileSdkVersion=34 - 真机调试：iOS 需开启 Developer Mode + Trust Computer；Android 需开启 USB Debugging + Install via USB

这三行后来成为团队协作的基线，避免了因环境差异导致的 “在我电脑上能跑” 式扯皮。

2.2 阶段二：跨端适配与真机联调（4.5 天）

WorkBuddy 内置的预览器只能模拟 Web 行为，对原生能力（摄像头、定位、文件系统）完全无感。真正考验开始于第一次真机联调。这里暴露了第二个大坑：iOS 浏览器唤起安装的断层。很多人搜索 “ios浏览器唤起安装app”，以为 WorkBuddy 能生成一个网页链接直接下载 IPA——这是误解。Capacitor 打包的 iOS App 无法通过 Safari 直接安装，必须走 Apple 的企业签名或 TestFlight。我们采用 TestFlight 方案，但首次上传时被拒，原因是Missing Push Notification Entitlement。排查发现，WorkBuddy 自动生成的capacitor.config.ts里plugins.PushNotifications默认开启，而我们根本没集成推送服务。关掉后重新 build，Xcode Archive 成功，但上传到 App Store Connect 时又卡在ITMS-90683: The app's Info.plist file must contain a value for the NSCameraUsageDescription key。原来 Capacitor 插件只要声明了@capacitor/camera，即使代码里没调用，Xcode 也会强制要求权限描述。解决方案是：在capacitor.config.ts的plugins配置块里，只保留实际用到的插件，并手动在ios/App/App/Info.plist里删除未使用的NS*UsageDescription条目。这个过程反复了五次，每次都要 clean build folder、delete derived data、重启 Xcode。

Android 端的坑更隐蔽。WorkBuddy 的 Android 模拟器默认使用x86_64镜像，但真机全是 ARM 架构。当我们在 WorkBuddy 里运行npx cap run android时，它会自动部署到模拟器，一切正常；但连上 Pixel 7 真机后，App 启动白屏。adb logcat 显示java.lang.UnsatisfiedLinkError: dlopen failed: library "libjsc.so" not found。根源是 Capacitor 的 WebView 引擎在 ARM 设备上需要特定 so 库，而 WorkBuddy 的默认构建没包含。解决方法是在android/app/build.gradle的defaultConfig里显式指定 ABI：

ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' }

并确保android/app/src/main/jniLibs/目录下有对应架构的 so 文件（Capacitor 4.0+ 已内置，但旧版本需手动补）。这个坑的教训是：WorkBuddy 的 “Run on Device” 按钮本质是执行adb install，它不校验 ABI 兼容性，失败只在真机上发生。

2.3 阶段三：签名体系与证书管理（3 天）

这是最耗心力的阶段。WorkBuddy 不提供证书生成 UI，它把钥匙交给你，但门锁是 Apple 和 Google 设计的。iOS 侧，你需要四样东西：Apple ID 开发者账号、App ID、Development Certificate、Provisioning Profile。WorkBuddy 的作用是帮你把它们串起来。关键操作在ios/App/App.xcworkspace里：打开 Xcode → Preferences → Accounts → 登录 Apple ID → Manage Certificates → Create “iOS Development” 证书 → 在项目 Signing & Capabilities 页勾选 “Automatically manage signing” → 选择 Team。看似简单，但 WorkBuddy 的坑在于：它生成的capacitor.config.ts里appId字段必须与 Apple Developer Portal 里注册的 App ID 完全一致（包括大小写和点号），否则 Provisioning Profile 匹配失败，Xcode 报No matching provisioning profiles found。我们曾因com.example.myapp和com.example.MyApp的差异重做了两次证书。

Android 侧相对简单，但 WorkBuddy 的capacitor.config.ts里android配置块有个隐藏字段signingType，默认为debug。发布前必须改为release，并指向 keystore 文件：

android: { signingType: 'release', signingProperties: { storeFile: './android/app/release-key.jks', storePassword: 'your-store-password', keyAlias: 'key0', keyPassword: 'your-key-password' } }

这里有两个致命细节：第一，storeFile路径是相对于android/app/目录的，不是项目根目录；第二，keystore 文件必须用keytool -genkey -v -keystore release-key.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias key0生成，且storetype必须是JKS（Android Studio Giraffe 默认用 PKCS12，会导致Invalid keystore format错误）。这个错误让我花了整整一天重试签名流程。

2.4 阶段四：构建产物生成与格式校验（1.5 天）

WorkBuddy 的npx cap build命令只生成源码，真正的构建由原生 IDE 完成。iOS 产物是.xcarchive，Android 是.aab（Android App Bundle）。但很多人不知道，.aab不是最终分发文件，它需要 Google Play Console 转换为.apks（可安装包）。WorkBuddy 不介入这步，但提供了校验脚本。我们在package.json里加了一条 script：

"validate:aab": "bundletool build-apks --bundle=android/app/build/outputs/bundle/release/app-release.aab --output=android/app/build/outputs/apks/app-release.apks --mode=universal"

运行后生成app-release.apks，用bundletool install-apks --apks=android/app/build/outputs/apks/app-release.apks可直接安装到真机。这步的意义在于：确认 AAB 包含所有 ABI 和语言资源，避免上线后用户下载失败。我们曾因android/app/src/main/res/下遗漏values-zh-rCN目录，导致部分华为手机安装后文字乱码，而 WorkBuddy 的预览器完全无法暴露这个问题。

iOS 侧的校验更严格。Xcode Archive 后，必须用altool（或新版notarytool）进行公证（Notarization），否则 macOS 用户下载 IPA 会提示 “已损坏”。WorkBuddy 不提供此功能，但我们在 CI 脚本里集成了：

xcrun notarytool submit ./MyApp.xcarchive --key-id "YOUR_KEY_ID" --issuer "YOUR_ISSUER" --password "@keychain:AC_PASSWORD" --wait

关键点是--key-id和--issuer来自 Apple Developer Portal 的 “Keys” 页面，@keychain:AC_PASSWORD是存入钥匙串的 App-Specific Password。这个步骤失败率极高，常见原因是证书过期或网络超时，必须单独处理重试逻辑。

2.5 阶段五：分发渠道与安装验证（2 天）

WorkBuddy 本身不提供分发服务，但它能对接第三方。我们用了两个渠道：TestFlight（iOS）和 Firebase App Distribution（Android）。TestFlight 的坑在于：邀请测试员必须用 Apple ID 邮箱，且该邮箱必须在 Apple Developer Portal 的 “Users and Access” 里添加为 “App Manager” 或 “Developer”。我们曾用 Gmail 邀请，测试员收不到邮件，查了半天才意识到权限层级问题。

Firebase App Distribution 更灵活，但 WorkBuddy 的集成需要额外配置。在android/app/build.gradle里添加：

apply plugin: 'com.google.firebase.appdistribution' firebaseAppDistribution { artifactType = "APK" // 或 "AAB" serviceCredentialsFile = "../../firebase-service-account.json" }

serviceCredentialsFile必须是绝对路径或相对于android/app/的路径，且firebase-service-account.json需从 Firebase Console 的 “Project Settings → Service Accounts” 下载。这里有个安全实践：该文件绝不能提交到 Git，必须加入.gitignore，并在 CI 环境中通过 secret 注入。

安装验证不是点开 App 看是否启动，而是验证原生能力。我们写了三个最小测试用例：

• 摄像头：调用Camera.getPhoto()，确认返回 base64 图片；
• 本地存储：用Storage.set()存键值，Storage.get()读取，比对一致性；
• 网络请求：用CapacitorHttp.request()访问内部 API，检查 status 200。 这些测试用例放在src/test/native.spec.ts，用 Jest 运行，确保每次构建后都能快速回归。

2.6 阶段六：审核响应与线上监控（3 天）

AppStore 审核被拒是常态。我们第一次被拒理由是2.1 - Information Needed：要求提供 App 如何使用图书扫描功能的视频。WorkBuddy 的优势在此刻显现——它内置的 Screen Recording 功能可直接录制真机操作视频，无需第三方工具。我们用 WorkBuddy 的 “Developer Tools → Screen Recorder” 录制了 45 秒视频，清晰展示扫码、识别、存库全流程，24 小时后通过。

上线后，WorkBuddy 的 “Analytics Dashboard”（需接入 Sentry）开始发挥作用。我们发现 12% 的 iOS 用户在首次启动时崩溃，日志指向Capacitor.Plugins.Storage初始化失败。深挖发现是 iOS 16.4+ 对UserDefaults的沙盒限制更严，解决方案是在ios/App/App/AppDelegate.swift里添加：

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { UserDefaults.standard.set(true, forKey: "capacitor_storage_initialized") return true }

并修改 Storage 插件的初始化逻辑。这个修复通过 WorkBuddy 的 Hot Update 功能（npx cap sync && npx cap copy）推送到线上，用户无需重新下载 App。

3. 十六个坑的现场还原与避坑清单

3.1 坑 1：WorkBuddy 终端未加载 nvm，导致 Node 版本错乱

现象：npm run build报错SyntaxError: Unexpected token '?'，本地 Node 18 正常，WorkBuddy 终端里node -v显示 14.21.3。
根因：WorkBuddy 启动时未 source~/.zshrc，nvm 未激活。
解法：在 WorkBuddy 设置里，Terminal → Shell Profile改为~/.zshrc；或在项目根目录新建.nvmrc写入18.18.2，并确保nvm use命令在终端启动时自动执行。
验证：新开终端，node -v输出v18.18.2，npm list -g npm输出10.2.4。

3.2 坑 2：Capacitor 插件声明与实际调用不匹配，触发 iOS 权限强制校验

现象：Xcode Archive 失败，报ITMS-90683，提示缺失NSCameraUsageDescription。
根因：capacitor.config.ts里plugins.Camera设为true，但代码中从未调用Camera.getPhoto()。
解法：删除capacitor.config.ts中未使用的插件配置；手动清理ios/App/App/Info.plist里的冗余NS*UsageDescription条目。
验证：Archive 成功，App Store Connect 上传无ITMS-90683错误。

3.3 坑 3：Android ABI 过滤缺失，ARM 真机白屏

现象：WorkBuddynpx cap run android在模拟器正常，Pixel 7 真机启动白屏。
根因：android/app/build.gradle未指定ndk.abiFilters，Capacitor 默认只打包 x86_64 so 库。
解法：在android/app/build.gradle的defaultConfig块添加：

ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' }

验证：adb logcat不再出现UnsatisfiedLinkError，App 正常启动。

3.4 坑 4：Keystore 格式错误，Android 签名失败

现象：npx cap build android --release报Invalid keystore format。
根因：Android Studio Giraffe 默认生成 PKCS12 格式 keystore，但 Capacitor 要求 JKS。
解法：用keytool重新生成 JKS 格式：

keytool -genkey -v -keystore release-key.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias key0

验证：jarsigner -verify -verbose -certs android/app/build/outputs/apk/release/app-release-unsigned.apk显示签名有效。

3.5 坑 5：iOS 自动签名失败，Provisioning Profile 不匹配

现象：Xcode 报No matching provisioning profiles found。
根因：capacitor.config.ts的appId与 Apple Developer Portal 的 App ID 不一致（如大小写、点号）。
解法：严格比对两者，确保完全相同；在 Xcode Signing 页点击 “Try Again” 刷新 Profile。
验证：Xcode 左下角显示 “Signing Certificate: Apple Development” 且无黄色警告。

3.6 坑 6：TestFlight 邀请邮件不送达，测试员收不到链接

现象：TestFlight 后台显示 “Invited”，但测试员邮箱无邮件。
根因：测试员 Apple ID 未在 Developer Portal 的 “Users and Access” 中添加，或权限不足。
解法：登录 developer.apple.com → “Users and Access” → 添加测试员邮箱 → 分配 “App Manager” 角色。
验证：测试员收到 Apple 系统邮件，点击链接进入 TestFlight。

3.7 坑 7：Firebase App Distribution 服务账号路径错误，构建失败

现象：./gradlew appDistributionUploadRelease报FileNotFoundException: firebase-service-account.json。
根因：build.gradle里serviceCredentialsFile路径相对于android/app/，但文件放在项目根目录。
解法：将firebase-service-account.json移至android/app/目录，或修改路径为../firebase-service-account.json。
验证：构建成功，Firebase Console 显示新版本 “Processing”。

3.8 坑 8：WorkBuddy Hot Update 未生效，真机仍运行旧代码

现象：npx cap sync && npx cap copy后，真机重启 App 仍是旧界面。
根因：Capacitor 的 Web Assets 默认缓存，未强制刷新。
解法：在capacitor.config.ts里添加：

webDir: 'www', server: { cleartext: true, allowNavigation: ['*'] }

并在ios/App/App/AppDelegate.swift里添加：

let webView = self.bridge?.webView as? WKWebView webView?.configuration.websiteDataStore = .nonPersistent()

验证：真机重启后加载最新www目录内容。

3.9 坑 9：iOS Notarization 失败，提示 “The signature is invalid”

现象：xcrun notarytool submit报The signature is invalid。
根因：Xcode Archive 时未勾选 “Rebuild from bitcode”，或证书过期。
解法：Xcode → Product → Archive → Options → 勾选 “Rebuild from bitcode”；检查证书有效期。
验证：xcrun notarytool submit返回Status: Accepted。

3.10 坑 10：Android AAB 包缺少语言资源，华为手机文字乱码

现象：华为手机安装后，中文显示为方框。
根因：android/app/src/main/res/下缺失values-zh-rCN目录，AAB 未打包简体中文资源。
解法：复制values目录为values-zh-rCN，确保strings.xml内容一致。
验证：bundletool dump manifest --bundle=app-release.aab | grep -A5 'locale'显示zh-rCN。

3.11 坑 11：WorkBuddy Screen Recorder 录制视频无声音，审核被拒

现象：TestFlight 提交的视频无声，Apple 要求补充音频说明。
根因：WorkBuddy 录制时未开启麦克风权限。
解法：macOS 系统设置 → 隐私与安全性 → 屏幕录制 → 勾选 WorkBuddy；录制前点击 WorkBuddy 工具栏麦克风图标开启。
验证：录制视频播放时有清晰语音解说。

3.12 坑 12：Capacitor Storage 在 iOS 16.4+ 初始化失败，App 崩溃

现象：iOS 16.4+ 设备首次启动崩溃，日志-[NSUserDefaults objectForKey:]crash。
根因：iOS 16.4 对UserDefaults沙盒访问更严格，Storage 插件初始化时未预设 key。
解法：在ios/App/App/AppDelegate.swift的application(_:didFinishLaunchingWithOptions:)里添加：

UserDefaults.standard.set(true, forKey: "capacitor_storage_initialized")

验证：崩溃率归零，Sentry 日志无相关 error。

3.13 坑 13：WorkBuddy Git 集成冲突，多人协作时分支混乱

现象：团队成员git pull后，android/app/build.gradle被自动修改，构建失败。
根因：WorkBuddy 的 “Auto-sync Gradle” 功能在多人编辑时覆盖配置。
解法：关闭 WorkBuddy 设置里的 “Auto-sync Gradle”，所有 Gradle 修改手动提交。
验证：git status不再显示无关的 Gradle 文件变更。

3.14 坑 14：iOS ATS 配置未关闭，HTTPS 请求失败

现象：真机上 API 请求返回NSURLErrorNotConnectedToInternet，但 Wi-Fi 正常。
根因：Capacitor 默认开启 ATS（App Transport Security），禁止 HTTP 请求。
解法：在ios/App/App/Info.plist里添加：

<key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <true/> </dict>

验证：HTTP 请求成功，console.log输出 response data。

3.15 坑 15：Android targetSdkVersion 与 buildToolsVersion 冲突，Gradle 构建失败

现象：./gradlew build报Could not determine the dependencies of task ':app:compileDebugJavaWithJavac'。
根因：android/app/build.gradle的targetSdkVersion=34要求buildToolsVersion="34.0.0"，但 WorkBuddy 默认用 33.0.2。
解法：在android/app/build.gradle的android块添加：

buildToolsVersion "34.0.0"

验证：./gradlew build无 error，生成app-debug.apk。

3.16 坑 16：WorkBuddy 热更新未触发 WebView 刷新，用户看到旧 CSS

现象：npx cap copy后，真机 CSS 未更新，仍显示旧样式。
根因：Capacitor WebView 缓存 CSS 文件，未检测到www/css/变更。
解法：在index.html的<head>里添加缓存控制 meta：

<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate" /> <meta http-equiv="Pragma" content="no-cache" /> <meta http-equiv="Expires" content="0" />

验证：真机刷新后加载最新 CSS，样式实时生效。

4. 可复用的经验：一套标准化上线 checklist 与自动化脚本

4.1 上线前 Checklist（团队每日站会核对）

这个 checklist 我们打印成 A4 纸贴在工位旁，每次上线前由 QA 主导逐项打钩，耗时不超过 15 分钟，但避免了 80% 的低级错误。

4.2 自动化脚本：一键校验与打包（存于scripts/deploy.sh）

#!/bin/bash # WorkBuddy 上线校验脚本 v1.2 set -e echo "🔍 开始 WorkBuddy 上线校验..." # 1. Node 版本校验 NODE_VERSION=$(node -v | sed 's/v//') if [[ "$NODE_VERSION" != "18.18.2" ]]; then echo "❌ Node 版本错误：期望 18.18.2，当前 $NODE_VERSION" exit 1 fi echo "✅ Node 版本正确" # 2. Capacitor 配置校验 if ! grep -q "com.example.myapp" capacitor.config.ts; then echo "❌ AppId 不匹配：capacitor.config.ts 未包含 com.example.myapp" exit 1 fi echo "✅ AppId 匹配" # 3. Android ABI 校验 if ! grep -q "armeabi-v7a" android/app/build.gradle; then echo "❌ Android ABI 缺失：未找到 armeabi-v7a" exit 1 fi echo "✅ Android ABI 完整" # 4. iOS 权限最小化校验 PLIST_COUNT=$(grep -c "NS.*UsageDescription" ios/App/App/Info.plist) if [[ "$PLIST_COUNT" -gt "3" ]]; then echo "❌ iOS 权限冗余：Info.plist 包含 $PLIST_COUNT 个 UsageDescription，期望 ≤3" exit 1 fi echo "✅ iOS 权限最小化" # 5. 构建产物校验 npx cap build if [ ! -f "android/app/build/outputs/bundle/release/app-release.aab" ]; then echo "❌ Android AAB 未生成" exit 1 fi echo "✅ Android AAB 生成成功" echo "🎉 所有校验通过！可执行 npx cap run ios/android 或提交审核"

这个脚本集成在 CI 的pre-deploy阶段，每次git push到release/*分支时自动运行。它不替代人工，但把重复性检查压缩到 30 秒内，让工程师专注解决真问题。

4.3 WorkBuddy 配置固化模板（团队统一使用）

为避免环境差异，我们将以下配置固化为团队标准：

• .nvmrc：固定为18.18.2
• .java-version：固定为17.0.1
• capacitor.config.ts：精简插件列表，禁用未用插件
• android/app/build.gradle：强制targetSdkVersion=34，compileSdkVersion=34，buildToolsVersion="34.0.0"
• ios/App/App/Info.plist：只保留NSCameraUsageDescription、NSPhotoLibraryUsageDescription、NSLocationWhenInUseUsageDescription
• package.jsonscripts：添加validate:aab、validate:ipa、deploy:ios、deploy:android

这些文件全部提交到 Git，新成员git clone后只需nvm install && sdk install java 17.0.1 && npx cap sync，5 分钟内环境拉齐。WorkBuddy 的价值不在于它多强大，而在于它让这些琐碎配置变得可追踪、可审计、可复现。

5. 实操心得：那些文档不会写的细节与判断

5.1 关于 “真机” 的认知重构：它不是终点，而是起点

很多人把 “连上真机跑通” 当作开发完成的标志，但在 WorkBuddy 场景下，真机只是第一个压力测试节点。我观察到三个关键信号，它们比 “App 能打开” 更重要：

• 冷启动时间：从点击图标到首页渲染完成，iOS 真机应 ≤1.2 秒，Android ≤1.5 秒。超过则需检查capacitor.config.ts的launchShowDuration和launchAutoHide配置，或优化index.html的初始 JS 加载。
• 内存占用峰值：用 Xcode 的 Memory Debugger 或 Android Studio 的 Profiler，真机运行时内存峰值应 <200MB（iPhone 12）、<300MB（Pixel 7）。超标往往意味着Storage或Camera插件未释放资源。
• 后台存活时长：切到后台 5 分钟后，用adb shell dumpsys activity activities | grep mResumedActivity检查 Activity 状态。若为null，说明 App 被系统回收，需调整android:process或android:launchMode。

这些指标 WorkBuddy 不提供，但它们决定了用户是否愿意长期留存。我把它们写进团队的 PR 模板，每次合并前必须附上真机实测数据。

5.2 WorkBuddy 与原生 IDE 的边界：何时该放手，何时该介入

WorkBuddy 的定位很清晰：它管代码、管协作、管调试、管热更新，但不管签名、不管公证、不管分发。我的经验是，当遇到以下情况，必须立刻跳出 WorkBuddy，打开 Xcode 或 Android Studio：

• Xcode 报Signing相关错误（证书、Profile、Team）；
• Android Studio 报Gradle Sync失败（版本冲突、插件不兼容）；
• 真机日志出现JNI、NDK、WebViewCore等底层关键词；
• App Store Connect 或 Google Play Console 返回ITMS或Bundle类错误。

反之，如果错误信息包含capacitor.*、@capacitor/*、npx cap，那基本能在 WorkBuddy 里解决。这个边界意识节省了我们大量