1. 为什么我选择用 WorkBuddy 从零搭一个能上线的 App去年年底我接手了一个内部工具类 App 的从零搭建任务。需求很明确一个轻量的内容聚合客户端能跑在 Android 和 iOS 上有 WebView 承载的混合页面有本地缓存有推送能上架。团队只有我一个人时间给了六周。摆在面前的路无非三条纯原生双端各写一遍、React Native / Flutter 这类跨端框架、或者用 AI 辅助工具快速生成骨架再手工打磨。前两条我都走过纯原生双端意味着至少两套代码、两套构建、两套调试六周时间根本不够跨端框架虽然省事但 WebView 与原生桥接的坑、包体积、冷启动性能在真实上线场景里依然要一个个填。最后我选了 WorkBuddy 作为主力开发助手。原因很直接它不是那种生成一段代码就完事的工具而是能跟着你把项目从脚手架一路推到打包上线的协作型助手。你给它一个模块目标它能帮你把目录结构、依赖、关键实现、甚至构建脚本都铺出来你负责审、改、测。六周下来项目按时上线中间踩了十六个坑我把它们全部记了下来。这篇东西写给两类人一类是手里有个 App 想法、但被从哪开始卡住的独立开发者另一类是用过 AI 编程工具、但发现生成的代码跑不起来或者跑起来也上不了线的同行。我会把六个阶段拆开讲每个阶段里踩过的坑单独拎出来说清楚根因和修法。关键词里出现的 WorkBuddy、WebView、Android、AI、App 这些都会在对应章节里落到具体操作上。先说结论WorkBuddy 能帮你把从想法到可运行项目的时间压缩到原来的三分之一左右但从可运行到能上线这段路依然要靠你自己对平台规则、WebView 行为、构建配置的理解。工具替你省的是重复劳动不是替你思考。2. 第一阶段项目初始化与 WorkBuddy 的介入方式2.1 为什么不在第一步就让 AI 生成整个项目很多人用 WorkBuddy 的第一反应是帮我生成一个完整的 App 项目。我试过结果是一个能编译但结构混乱的工程Activity 和 Fragment 混在一起网络层直接写在 UI 里资源文件命名随意。它能跑但你没法在上面继续迭代。正确的做法是分两步走。第一步你自己定骨架用什么架构我选的是单 Activity 多 Fragment 的轻量 MVVM、用什么网络库、用什么本地存储、包名怎么定、最低支持版本定多少。第二步把这份骨架描述给 WorkBuddy让它按你的约束去填充具体实现。我当时的骨架描述大概是这样包名com.example.contenthub最低支持 Android 8.0API 26目标 API 34架构单 ActivityFragment 承载页面ViewModel LiveData 做状态网络OkHttp RetrofitJSON 解析用 Moshi本地Room 做结构化缓存SharedPreferences 存轻量配置WebView 页面独立 Fragment承载 H5 内容页构建Gradle Kotlin DSL开启 ViewBinding把这段丢给 WorkBuddy它生成的工程结构就规整多了。这里的关键认知是AI 擅长在约束下填充不擅长替你定约束。你给的约束越具体它生成的东西越接近可用。2.2 坑一Gradle 版本与 AGP 不匹配导致同步失败第一个坑来得很快。WorkBuddy 生成的build.gradle.kts里Android Gradle Plugin 版本写的是 8.1.0但 Gradle Wrapper 的版本是 7.5。同步直接报错Minimum supported Gradle version is 8.0. Current version is 7.5.这个坑的本质是AI 生成配置时各组件版本是各自最新拼在一起的但 AGP 和 Gradle 之间有严格的兼容矩阵。修法很简单查官方兼容表把 Gradle Wrapper 升到 8.0 以上。但如果你不知道有这张表可能会在升级 Gradle和降级 AGP之间反复横跳。我的经验是项目初始化完成后第一件事就是打开 Gradle 官方兼容性文档把 AGP、Gradle、Kotlin、JDK 四个版本对齐。这四个是连锁的错一个就同步失败。对齐之后后面所有构建问题都会少一大半。2.3 坑二WorkBuddy 生成的依赖没有锁版本第二个坑更隐蔽。WorkBuddy 生成的依赖声明是这样的implementation(com.squareup.retrofit2:retrofit:2.9.0) implementation(com.squareup.okhttp3:okhttp:4.9.0)看起来没问题但 OkHttp 4.9.0 和 Retrofit 2.9.0 之间对 OkHttp 的传递依赖版本可能冲突。项目跑起来没事一旦你引入别的库比如 Coil 图片加载它内部依赖的 OkHttp 版本可能又不一样构建时就会出现重复类或者方法找不到。修法是引入 BOMBill of Materials统一管理implementation(platform(com.squareup.okhttp3:okhttp-bom:4.12.0)) implementation(com.squareup.okhttp3:okhttp) implementation(com.squareup.retrofit2:retrofit:2.9.0)这样 OkHttp 相关依赖的版本由 BOM 统一决定不会打架。这个坑我踩了两次才记住因为第一次报错信息指向的是 Coil不是 OkHttp排查方向一开始就错了。3. 第二阶段WebView 混合页面的真实行为与适配3.1 WebView 不是嵌个网页那么简单这个 App 的核心页面有一半是 H5 承载的所以 WebView 是重头戏。我一开始的想法很朴素一个WebView控件loadUrl加载地址完事。实际做下来WebView 的行为差异、版本碎片化、与原生桥接的细节占了整个项目将近三分之一的工作量。先说一个最容易被忽略的点Android 系统 WebView 的版本是跟着系统或独立组件走的不同设备差异极大。关键词里出现的webview 历史版本合集android8.1 支持的 webview 版本这类搜索背后就是这个问题。Android 8.1 设备上WebView 可能是 60 多版而新设备上可能是 120 多版。同一个 H5 页面在老版本 WebView 上可能白屏、可能 JS 报错、可能 CSS 布局错乱。我的应对策略是在 App 启动时读取当前 WebView 的 UA 和版本号上报到日志同时在 H5 侧做特性检测而不是版本检测。特性检测的意思是H5 不判断你是不是 Chrome 60而是判断你支不支持这个 API。这样无论 WebView 版本怎么变逻辑都是稳的。3.2 坑三WebView 默认不允许混合内容加载H5 页面里有一张图片是 HTTP 的主页面是 HTTPS 的。在浏览器里能显示在 WebView 里直接空白。原因是 Android 从 5.0 开始WebView 默认阻止 HTTPS 页面加载 HTTP 资源mixed content。修法是在WebSettings里显式设置webView.settings.mixedContentMode WebSettings.MIXED_CONTENT_COMPATIBILITY_MODE但这里有个取舍COMPATIBILITY_MODE会放行部分混合内容ALWAYS_ALLOW会全部放行安全性最低。我的建议是能改成 HTTPS 的资源全部改掉实在改不了的比如第三方老接口再用COMPATIBILITY_MODE绝不用ALWAYS_ALLOW。这个坑的教训是WebView 的安全默认值比浏览器严格你不能拿浏览器的表现去推断 WebView。3.3 坑四WebView 与原生桥接的线程问题H5 要调用原生能力比如获取设备信息、触发下载用的是addJavascriptInterface。我写了一个桥接类方法里直接更新 UI。结果在部分设备上偶发崩溃日志指向在非 UI 线程操作 View。原因是addJavascriptInterface注入的方法默认在 WebView 的 JS 线程执行不是 UI 线程。修法是所有涉及 UI 的操作都runOnUiThread包一层或者用 Handler 切回主线程。JavascriptInterface fun showToast(msg: String) { runOnUiThread { Toast.makeText(context, msg, Toast.LENGTH_SHORT).show() } }这个坑的隐蔽之处在于它在你的测试机上可能永远不崩只在某些低端机或高负载时崩。所以桥接方法一律按非 UI 线程处理是更稳的习惯。3.4 坑五WebView 返回键与页面栈不同步用户按物理返回键期望是网页后退但实际是退出 App。原因是没处理onKeyDown或者没判断webView.canGoBack()。修法是在承载 WebView 的 Fragment 里拦截返回override fun onKeyDown(keyCode: Int, event: KeyEvent?): Boolean { if (keyCode KeyEvent.KEYCODE_BACK webView.canGoBack()) { webView.goBack() return true } return super.onKeyDown(keyCode, event) }但这里有个进阶问题如果 H5 内部有自己的路由比如单页应用canGoBack()可能返回 true 但后退的是 H5 内部状态用户感知是没反应。更稳的做法是 H5 通过桥接主动告诉原生当前是否可以后退原生据此决定。这个方案我最后用了虽然多写了一点桥接代码但返回行为完全可控。3.5 坑六WebView 缓存策略选错导致内容不更新WebView 默认的缓存策略是LOAD_DEFAULT它会根据 HTTP 缓存头决定是否用缓存。问题来了H5 页面更新了但用户看到的还是旧版因为缓存头没设对。我试过LOAD_NO_CACHE结果每次打开都重新下载流量和速度都受影响。最后用的是LOAD_DEFAULT配合 H5 侧的版本化 URL比如page.html?v20240101这样既利用了缓存又能在版本更新时强制刷新。这个坑的本质是WebView 缓存不是开或关的问题是缓存粒度的问题。静态资源JS、CSS、图片应该长缓存入口 HTML 应该短缓存或不缓存。这个策略要在 H5 侧配合光靠原生设置解决不了。4. 第三阶段原生功能模块的填充与 AI 协作边界4.1 哪些模块适合交给 WorkBuddy哪些必须自己写六周下来我对什么该让 WorkBuddy 做有了比较清晰的判断。适合交给它的样板代码Adapter、ViewHolder、数据类、标准网络请求封装、Room 的 Entity 和 DAO、简单的工具类。不适合交给它的涉及具体业务规则的逻辑、需要和第三方 SDK 深度交互的部分、性能敏感的代码。举个例子列表页的 Adapter我让 WorkBuddy 生成它给的代码规范、有 ViewBinding、有 DiffUtil我改改就能用。但列表的排序规则、分页触发时机、空状态处理这些必须我自己定因为 AI 不知道你的业务语义。4.2 坑七Room 数据库迁移没写导致升级崩溃App 第一版上线后第二版加了一个字段。我改了 Entity但忘了写 Migration。结果老用户升级后一打开就崩Room cannot verify the data integrity. Looks like youve changed schema but forgot to update the version number.修法是两步版本号加一写 Migration。val MIGRATION_1_2 object : Migration(1, 2) { override fun migrate(db: SupportSQLiteDatabase) { db.execSQL(ALTER TABLE article ADD COLUMN readCount INTEGER NOT NULL DEFAULT 0) } }这个坑的教训是Room 的 schema 变更必须配 Migration没有例外。如果你在开发阶段可以用fallbackToDestructiveMigration()偷懒但上线版本绝对不能这么干否则用户数据全丢。4.3 坑八网络请求没有统一错误处理WorkBuddy 生成的 Retrofit 接口很干净但错误处理是散的每个调用点自己 try-catch。结果就是超时、断网、服务器 500三种情况的提示文案不一样有的地方甚至没提示用户看到的是转圈转到天荒地老。我后来抽了一个统一的ApiResult封装sealed class ApiResultout T { data class SuccessT(val data: T) : ApiResultT() data class Error(val code: Int, val message: String) : ApiResultNothing() object Loading : ApiResultNothing() }所有网络调用返回ApiResultUI 层统一处理三种状态。这样错误提示一致加载状态可控代码也干净。这个重构花了我半天但后面所有页面都受益。4.4 坑九图片加载库选型时忽略了 WebView 场景图片加载我一开始用 Glide原生列表里没问题。但 H5 页面里的图片Glide 管不到WebView 自己加载。结果就是原生列表的图片有缓存、有占位图、有错误图H5 里的图片什么都没有加载慢、失败就空白。后来我做了两件事一是 H5 侧的图片加载交给 H5 自己处理用懒加载 占位图二是原生和 H5 共用一套图片 CDN 的缓存策略。这样两边的体验才一致。这个坑提醒我混合开发里原生和H5不是两个独立世界缓存、图片、网络策略要统一考虑。5. 第四阶段构建、签名与上架前的硬性检查5.1 从 debug 到 release 的鸿沟debug 包跑得好好的一打 release 包就出问题这是 Android 开发的经典场景。我遇到的第一个 release 问题是混淆。WorkBuddy 生成的proguard-rules.pro是空的release 构建开启混淆后Retrofit 的接口、Moshi 的数据类全被混淆运行时直接崩。修法是补混淆规则-keep class com.example.contenthub.data.model.** { *; } -keepattributes Signature -keepattributes *Annotation* -keep class retrofit2.** { *; }这里的关键是所有被反射用到的类都不能混淆。Retrofit 接口、Moshi 数据类、Room Entity这三类是重灾区。我的做法是给数据模型单独一个包整包 keep省得一个个加。5.2 坑十签名文件丢失导致无法更新这个坑很蠢但很致命。第一版上线用的签名文件我存在本地一个目录里没备份。第二版要更新时发现文件找不到了。Android 的规则是同一个包名必须用同一个签名否则无法覆盖安装。签名丢了要么换包名重新上架用户全丢要么找平台申诉流程漫长。我的补救是翻出了旧电脑的备份找回了签名。从那以后签名文件我存三个地方本地加密目录、私有 Git 仓库、离线移动硬盘。并且把签名密码单独记在密码管理器里。这个坑没有技术含量但代价极大值得单独拎出来说。5.3 坑十一targetSdkVersion 升级带来的行为变更Google Play 要求每年升级 targetSdkVersion。我从 33 升到 34 时遇到了两个行为变更一是前台服务类型必须显式声明二是PendingIntent必须指定FLAG_IMMUTABLE或FLAG_MUTABLE。这两个不处理App 在 Android 14 上直接崩。修法是在AndroidManifest.xml里给服务加foregroundServiceType在创建PendingIntent时加 flagPendingIntent.getActivity( context, 0, intent, PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT )这个坑的教训是每次升级 targetSdkVersion先去官方文档看行为变更那一节逐条对照。这些变更不是可选项是硬性要求不处理就崩。5.4 坑十二App 图标和启动图适配不全图标我一开始只放了mipmap-hdpi一套结果在高分辨率设备上模糊。Android 现在推荐用自适应图标Adaptive Icon需要前景层和背景层两套资源放在mipmap-anydpi-v26里。启动图Splash也有坑。Android 12 之后系统有默认的启动画面如果你还用老式的SplashActivity会出现双启动图的闪烁。正确做法是用SplashScreenAPI或者把启动图做成主题背景。这两个坑不影响功能但影响第一印象。用户打开 App 的第一秒看到的是模糊图标或者闪烁的启动图信任感就打了折扣。6. 第五阶段上线后的监控与迭代6.1 崩溃监控不是可选项App 上线第一天我就收到了几个崩溃反馈但用户描述很模糊打开就闪退。没有堆栈没法排查。我赶紧接入了崩溃监控 SDK第二天就定位到了问题某个机型的 WebView 在加载特定 H5 时崩溃。崩溃监控的选型上我用的是 Firebase Crashlytics接入简单堆栈清晰。关键是要在 release 包里也开启符号表上传否则堆栈全是混淆后的a.b.c没法看。6.2 坑十三WebView 崩溃无法被常规崩溃监控捕获WebView 的崩溃有时候是渲染进程崩溃不会走 Java 层的UncaughtExceptionHandler常规崩溃监控抓不到。表现是App 没闪退但 WebView 区域白屏。修法是给 WebView 设置WebViewClient重写onRenderProcessGoneoverride fun onRenderProcessGone(view: WebView, detail: RenderProcessGoneDetail): Boolean { // 销毁当前 WebView重建 view.destroy() recreateWebView() return true }返回 true 表示我处理了系统不会杀掉整个 App。这个坑很隐蔽因为不崩溃、不报错只是白屏用户可能以为是网络问题。6.3 坑十四H5 与原生版本不兼容App 发版后H5 也在持续更新。有一次 H5 用了一个新的桥接方法但老版本 App 没有这个方法调用直接报错。用户看到的是功能不可用。修法是在桥接层做版本协商H5 调用前先问原生你支持哪些方法原生返回一个能力列表H5 据此决定用哪个方案。这个机制叫能力探测是混合开发的标配。我后来把它做成了一个BridgeManager所有桥接方法注册在里面H5 通过getSupportedMethods()获取列表。6.4 坑十五日志上报把用户隐私带出去了有一次排查问题我让用户开了详细日志结果日志里包含了用户的搜索关键词。这属于隐私数据不该上报。虽然是自己排查用但流程上不规范。修法是日志上报前做脱敏手机号、邮箱、关键词这类字段统一替换成占位符。并且日志分级debug 日志只在开发版开启release 版只上报 error 级别。这个坑不是技术问题是意识问题。任何要离开设备的数据都要先问一句这里面有没有用户隐私7. 第六阶段把十六个坑沉淀成可复用的检查清单7.1 坑十六没有检查清单同样的坑会踩第二次最后一个坑是关于坑本身的。项目做完我复盘时发现有些坑我在上一个项目里踩过这个项目又踩了一遍。原因是没有沉淀成清单。所以我把这十六个坑整理成了一份上线前检查清单每次发版前过一遍。清单分四块检查块检查项对应坑构建配置AGP/Gradle/Kotlin/JDK 版本对齐坑一构建配置依赖用 BOM 锁版本坑二构建配置混淆规则覆盖反射类坑十相关构建配置签名文件三处备份坑十WebView混合内容模式设置坑三WebView桥接方法线程安全坑四WebView返回键与页面栈同步坑五WebView缓存策略与 H5 版本化配合坑六WebViewonRenderProcessGone 处理坑十三数据层Room Migration 完整坑七数据层网络错误统一封装坑八数据层图片缓存策略统一坑九平台适配targetSdk 行为变更逐条对照坑十一平台适配自适应图标与启动图坑十二上线运维崩溃监控接入并上传符号表坑十三相关上线运维桥接能力探测机制坑十四上线运维日志脱敏与分级坑十五这份清单我现在每个项目都用新项目踩新坑的概率明显下降。7.2 WorkBuddy 在复盘阶段的价值复盘时我又用了一次 WorkBuddy把十六个坑的描述丢给它让它帮我归类、找共性。它给出的归类和我自己想的差不多但它补充了一点这十六个坑里有九个属于配置类七个属于运行时行为类。配置类的坑可以在项目初始化时一次性规避运行时行为类的坑需要靠测试覆盖。这个视角对我很有用。后来我调整了策略初始化阶段花更多时间把配置做扎实测试阶段重点覆盖运行时行为。资源配置变了效率就上来了。7.3 关于AI 能不能替代开发者这件事做完这个项目我对这个问题的答案更清晰了AI 能替代的是写代码这个动作替代不了做决策这个过程。WorkBuddy 帮我省了大量敲键盘的时间但每一个架构选择、每一个版本对齐、每一个安全设置都需要我自己判断。关键词里有很多关于 WorkBuddy 使用教程、国际版、从入门到精通的搜索说明很多人正在尝试这类工具。我的建议是把它当成一个执行力极强但需要明确指令的初级工程师你给它的约束越清晰它交付的质量越高。别指望它替你想清楚需求那是你的活。7.4 给准备用 WorkBuddy 搭 App 的人几条实操建议第一项目初始化时先把技术栈和版本矩阵定死再让 WorkBuddy 生成代码。版本对齐这件事AI 不会主动帮你做。第二WebView 相关的代码一律按最坏情况写混合内容、线程、返回键、渲染进程崩溃四个都要处理。第三数据层的 Migration、混淆规则、签名备份这三件事在项目第一天就做好别拖到上线前。第四上线后第一时间接崩溃监控并且确保符号表上传。没有监控的线上版本等于闭着眼睛开车。第五把踩过的坑记下来形成自己的清单。工具会更新平台会更新但配置要对齐、行为要验证、隐私要脱敏这些原则不会变。我在这个项目里最大的体会是能上线的 App 和能跑的 Demo 之间隔着的不是代码量是那十六个坑。WorkBuddy 帮你快速跨过从零到能跑但从能跑到能上线这段路得你自己一步步走。走完之后把路标记下来下次就快了。 
长河君 · 2026/10/15 8:37:53 · 阅读 1.2k WorkBuddy 从零搭建可上线 App 的十六个坑与实战复盘
1. 为什么我选择用 WorkBuddy 从零搭一个能上线的 App去年年底我接手了一个内部工具类 App 的从零搭建任务。需求很明确一个轻量的内容聚合客户端能跑在 Android 和 iOS 上有 WebView 承载的混合页面有本地缓存有推送能上架。团队只有我一个人时间给了六周。摆在面前的路无非三条纯原生双端各写一遍、React Native / Flutter 这类跨端框架、或者用 AI 辅助工具快速生成骨架再手工打磨。前两条我都走过纯原生双端意味着至少两套代码、两套构建、两套调试六周时间根本不够跨端框架虽然省事但 WebView 与原生桥接的坑、包体积、冷启动性能在真实上线场景里依然要一个个填。最后我选了 WorkBuddy 作为主力开发助手。原因很直接它不是那种生成一段代码就完事的工具而是能跟着你把项目从脚手架一路推到打包上线的协作型助手。你给它一个模块目标它能帮你把目录结构、依赖、关键实现、甚至构建脚本都铺出来你负责审、改、测。六周下来项目按时上线中间踩了十六个坑我把它们全部记了下来。这篇东西写给两类人一类是手里有个 App 想法、但被从哪开始卡住的独立开发者另一类是用过 AI 编程工具、但发现生成的代码跑不起来或者跑起来也上不了线的同行。我会把六个阶段拆开讲每个阶段里踩过的坑单独拎出来说清楚根因和修法。关键词里出现的 WorkBuddy、WebView、Android、AI、App 这些都会在对应章节里落到具体操作上。先说结论WorkBuddy 能帮你把从想法到可运行项目的时间压缩到原来的三分之一左右但从可运行到能上线这段路依然要靠你自己对平台规则、WebView 行为、构建配置的理解。工具替你省的是重复劳动不是替你思考。2. 第一阶段项目初始化与 WorkBuddy 的介入方式2.1 为什么不在第一步就让 AI 生成整个项目很多人用 WorkBuddy 的第一反应是帮我生成一个完整的 App 项目。我试过结果是一个能编译但结构混乱的工程Activity 和 Fragment 混在一起网络层直接写在 UI 里资源文件命名随意。它能跑但你没法在上面继续迭代。正确的做法是分两步走。第一步你自己定骨架用什么架构我选的是单 Activity 多 Fragment 的轻量 MVVM、用什么网络库、用什么本地存储、包名怎么定、最低支持版本定多少。第二步把这份骨架描述给 WorkBuddy让它按你的约束去填充具体实现。我当时的骨架描述大概是这样包名com.example.contenthub最低支持 Android 8.0API 26目标 API 34架构单 ActivityFragment 承载页面ViewModel LiveData 做状态网络OkHttp RetrofitJSON 解析用 Moshi本地Room 做结构化缓存SharedPreferences 存轻量配置WebView 页面独立 Fragment承载 H5 内容页构建Gradle Kotlin DSL开启 ViewBinding把这段丢给 WorkBuddy它生成的工程结构就规整多了。这里的关键认知是AI 擅长在约束下填充不擅长替你定约束。你给的约束越具体它生成的东西越接近可用。2.2 坑一Gradle 版本与 AGP 不匹配导致同步失败第一个坑来得很快。WorkBuddy 生成的build.gradle.kts里Android Gradle Plugin 版本写的是 8.1.0但 Gradle Wrapper 的版本是 7.5。同步直接报错Minimum supported Gradle version is 8.0. Current version is 7.5.这个坑的本质是AI 生成配置时各组件版本是各自最新拼在一起的但 AGP 和 Gradle 之间有严格的兼容矩阵。修法很简单查官方兼容表把 Gradle Wrapper 升到 8.0 以上。但如果你不知道有这张表可能会在升级 Gradle和降级 AGP之间反复横跳。我的经验是项目初始化完成后第一件事就是打开 Gradle 官方兼容性文档把 AGP、Gradle、Kotlin、JDK 四个版本对齐。这四个是连锁的错一个就同步失败。对齐之后后面所有构建问题都会少一大半。2.3 坑二WorkBuddy 生成的依赖没有锁版本第二个坑更隐蔽。WorkBuddy 生成的依赖声明是这样的implementation(com.squareup.retrofit2:retrofit:2.9.0) implementation(com.squareup.okhttp3:okhttp:4.9.0)看起来没问题但 OkHttp 4.9.0 和 Retrofit 2.9.0 之间对 OkHttp 的传递依赖版本可能冲突。项目跑起来没事一旦你引入别的库比如 Coil 图片加载它内部依赖的 OkHttp 版本可能又不一样构建时就会出现重复类或者方法找不到。修法是引入 BOMBill of Materials统一管理implementation(platform(com.squareup.okhttp3:okhttp-bom:4.12.0)) implementation(com.squareup.okhttp3:okhttp) implementation(com.squareup.retrofit2:retrofit:2.9.0)这样 OkHttp 相关依赖的版本由 BOM 统一决定不会打架。这个坑我踩了两次才记住因为第一次报错信息指向的是 Coil不是 OkHttp排查方向一开始就错了。3. 第二阶段WebView 混合页面的真实行为与适配3.1 WebView 不是嵌个网页那么简单这个 App 的核心页面有一半是 H5 承载的所以 WebView 是重头戏。我一开始的想法很朴素一个WebView控件loadUrl加载地址完事。实际做下来WebView 的行为差异、版本碎片化、与原生桥接的细节占了整个项目将近三分之一的工作量。先说一个最容易被忽略的点Android 系统 WebView 的版本是跟着系统或独立组件走的不同设备差异极大。关键词里出现的webview 历史版本合集android8.1 支持的 webview 版本这类搜索背后就是这个问题。Android 8.1 设备上WebView 可能是 60 多版而新设备上可能是 120 多版。同一个 H5 页面在老版本 WebView 上可能白屏、可能 JS 报错、可能 CSS 布局错乱。我的应对策略是在 App 启动时读取当前 WebView 的 UA 和版本号上报到日志同时在 H5 侧做特性检测而不是版本检测。特性检测的意思是H5 不判断你是不是 Chrome 60而是判断你支不支持这个 API。这样无论 WebView 版本怎么变逻辑都是稳的。3.2 坑三WebView 默认不允许混合内容加载H5 页面里有一张图片是 HTTP 的主页面是 HTTPS 的。在浏览器里能显示在 WebView 里直接空白。原因是 Android 从 5.0 开始WebView 默认阻止 HTTPS 页面加载 HTTP 资源mixed content。修法是在WebSettings里显式设置webView.settings.mixedContentMode WebSettings.MIXED_CONTENT_COMPATIBILITY_MODE但这里有个取舍COMPATIBILITY_MODE会放行部分混合内容ALWAYS_ALLOW会全部放行安全性最低。我的建议是能改成 HTTPS 的资源全部改掉实在改不了的比如第三方老接口再用COMPATIBILITY_MODE绝不用ALWAYS_ALLOW。这个坑的教训是WebView 的安全默认值比浏览器严格你不能拿浏览器的表现去推断 WebView。3.3 坑四WebView 与原生桥接的线程问题H5 要调用原生能力比如获取设备信息、触发下载用的是addJavascriptInterface。我写了一个桥接类方法里直接更新 UI。结果在部分设备上偶发崩溃日志指向在非 UI 线程操作 View。原因是addJavascriptInterface注入的方法默认在 WebView 的 JS 线程执行不是 UI 线程。修法是所有涉及 UI 的操作都runOnUiThread包一层或者用 Handler 切回主线程。JavascriptInterface fun showToast(msg: String) { runOnUiThread { Toast.makeText(context, msg, Toast.LENGTH_SHORT).show() } }这个坑的隐蔽之处在于它在你的测试机上可能永远不崩只在某些低端机或高负载时崩。所以桥接方法一律按非 UI 线程处理是更稳的习惯。3.4 坑五WebView 返回键与页面栈不同步用户按物理返回键期望是网页后退但实际是退出 App。原因是没处理onKeyDown或者没判断webView.canGoBack()。修法是在承载 WebView 的 Fragment 里拦截返回override fun onKeyDown(keyCode: Int, event: KeyEvent?): Boolean { if (keyCode KeyEvent.KEYCODE_BACK webView.canGoBack()) { webView.goBack() return true } return super.onKeyDown(keyCode, event) }但这里有个进阶问题如果 H5 内部有自己的路由比如单页应用canGoBack()可能返回 true 但后退的是 H5 内部状态用户感知是没反应。更稳的做法是 H5 通过桥接主动告诉原生当前是否可以后退原生据此决定。这个方案我最后用了虽然多写了一点桥接代码但返回行为完全可控。3.5 坑六WebView 缓存策略选错导致内容不更新WebView 默认的缓存策略是LOAD_DEFAULT它会根据 HTTP 缓存头决定是否用缓存。问题来了H5 页面更新了但用户看到的还是旧版因为缓存头没设对。我试过LOAD_NO_CACHE结果每次打开都重新下载流量和速度都受影响。最后用的是LOAD_DEFAULT配合 H5 侧的版本化 URL比如page.html?v20240101这样既利用了缓存又能在版本更新时强制刷新。这个坑的本质是WebView 缓存不是开或关的问题是缓存粒度的问题。静态资源JS、CSS、图片应该长缓存入口 HTML 应该短缓存或不缓存。这个策略要在 H5 侧配合光靠原生设置解决不了。4. 第三阶段原生功能模块的填充与 AI 协作边界4.1 哪些模块适合交给 WorkBuddy哪些必须自己写六周下来我对什么该让 WorkBuddy 做有了比较清晰的判断。适合交给它的样板代码Adapter、ViewHolder、数据类、标准网络请求封装、Room 的 Entity 和 DAO、简单的工具类。不适合交给它的涉及具体业务规则的逻辑、需要和第三方 SDK 深度交互的部分、性能敏感的代码。举个例子列表页的 Adapter我让 WorkBuddy 生成它给的代码规范、有 ViewBinding、有 DiffUtil我改改就能用。但列表的排序规则、分页触发时机、空状态处理这些必须我自己定因为 AI 不知道你的业务语义。4.2 坑七Room 数据库迁移没写导致升级崩溃App 第一版上线后第二版加了一个字段。我改了 Entity但忘了写 Migration。结果老用户升级后一打开就崩Room cannot verify the data integrity. Looks like youve changed schema but forgot to update the version number.修法是两步版本号加一写 Migration。val MIGRATION_1_2 object : Migration(1, 2) { override fun migrate(db: SupportSQLiteDatabase) { db.execSQL(ALTER TABLE article ADD COLUMN readCount INTEGER NOT NULL DEFAULT 0) } }这个坑的教训是Room 的 schema 变更必须配 Migration没有例外。如果你在开发阶段可以用fallbackToDestructiveMigration()偷懒但上线版本绝对不能这么干否则用户数据全丢。4.3 坑八网络请求没有统一错误处理WorkBuddy 生成的 Retrofit 接口很干净但错误处理是散的每个调用点自己 try-catch。结果就是超时、断网、服务器 500三种情况的提示文案不一样有的地方甚至没提示用户看到的是转圈转到天荒地老。我后来抽了一个统一的ApiResult封装sealed class ApiResultout T { data class SuccessT(val data: T) : ApiResultT() data class Error(val code: Int, val message: String) : ApiResultNothing() object Loading : ApiResultNothing() }所有网络调用返回ApiResultUI 层统一处理三种状态。这样错误提示一致加载状态可控代码也干净。这个重构花了我半天但后面所有页面都受益。4.4 坑九图片加载库选型时忽略了 WebView 场景图片加载我一开始用 Glide原生列表里没问题。但 H5 页面里的图片Glide 管不到WebView 自己加载。结果就是原生列表的图片有缓存、有占位图、有错误图H5 里的图片什么都没有加载慢、失败就空白。后来我做了两件事一是 H5 侧的图片加载交给 H5 自己处理用懒加载 占位图二是原生和 H5 共用一套图片 CDN 的缓存策略。这样两边的体验才一致。这个坑提醒我混合开发里原生和H5不是两个独立世界缓存、图片、网络策略要统一考虑。5. 第四阶段构建、签名与上架前的硬性检查5.1 从 debug 到 release 的鸿沟debug 包跑得好好的一打 release 包就出问题这是 Android 开发的经典场景。我遇到的第一个 release 问题是混淆。WorkBuddy 生成的proguard-rules.pro是空的release 构建开启混淆后Retrofit 的接口、Moshi 的数据类全被混淆运行时直接崩。修法是补混淆规则-keep class com.example.contenthub.data.model.** { *; } -keepattributes Signature -keepattributes *Annotation* -keep class retrofit2.** { *; }这里的关键是所有被反射用到的类都不能混淆。Retrofit 接口、Moshi 数据类、Room Entity这三类是重灾区。我的做法是给数据模型单独一个包整包 keep省得一个个加。5.2 坑十签名文件丢失导致无法更新这个坑很蠢但很致命。第一版上线用的签名文件我存在本地一个目录里没备份。第二版要更新时发现文件找不到了。Android 的规则是同一个包名必须用同一个签名否则无法覆盖安装。签名丢了要么换包名重新上架用户全丢要么找平台申诉流程漫长。我的补救是翻出了旧电脑的备份找回了签名。从那以后签名文件我存三个地方本地加密目录、私有 Git 仓库、离线移动硬盘。并且把签名密码单独记在密码管理器里。这个坑没有技术含量但代价极大值得单独拎出来说。5.3 坑十一targetSdkVersion 升级带来的行为变更Google Play 要求每年升级 targetSdkVersion。我从 33 升到 34 时遇到了两个行为变更一是前台服务类型必须显式声明二是PendingIntent必须指定FLAG_IMMUTABLE或FLAG_MUTABLE。这两个不处理App 在 Android 14 上直接崩。修法是在AndroidManifest.xml里给服务加foregroundServiceType在创建PendingIntent时加 flagPendingIntent.getActivity( context, 0, intent, PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT )这个坑的教训是每次升级 targetSdkVersion先去官方文档看行为变更那一节逐条对照。这些变更不是可选项是硬性要求不处理就崩。5.4 坑十二App 图标和启动图适配不全图标我一开始只放了mipmap-hdpi一套结果在高分辨率设备上模糊。Android 现在推荐用自适应图标Adaptive Icon需要前景层和背景层两套资源放在mipmap-anydpi-v26里。启动图Splash也有坑。Android 12 之后系统有默认的启动画面如果你还用老式的SplashActivity会出现双启动图的闪烁。正确做法是用SplashScreenAPI或者把启动图做成主题背景。这两个坑不影响功能但影响第一印象。用户打开 App 的第一秒看到的是模糊图标或者闪烁的启动图信任感就打了折扣。6. 第五阶段上线后的监控与迭代6.1 崩溃监控不是可选项App 上线第一天我就收到了几个崩溃反馈但用户描述很模糊打开就闪退。没有堆栈没法排查。我赶紧接入了崩溃监控 SDK第二天就定位到了问题某个机型的 WebView 在加载特定 H5 时崩溃。崩溃监控的选型上我用的是 Firebase Crashlytics接入简单堆栈清晰。关键是要在 release 包里也开启符号表上传否则堆栈全是混淆后的a.b.c没法看。6.2 坑十三WebView 崩溃无法被常规崩溃监控捕获WebView 的崩溃有时候是渲染进程崩溃不会走 Java 层的UncaughtExceptionHandler常规崩溃监控抓不到。表现是App 没闪退但 WebView 区域白屏。修法是给 WebView 设置WebViewClient重写onRenderProcessGoneoverride fun onRenderProcessGone(view: WebView, detail: RenderProcessGoneDetail): Boolean { // 销毁当前 WebView重建 view.destroy() recreateWebView() return true }返回 true 表示我处理了系统不会杀掉整个 App。这个坑很隐蔽因为不崩溃、不报错只是白屏用户可能以为是网络问题。6.3 坑十四H5 与原生版本不兼容App 发版后H5 也在持续更新。有一次 H5 用了一个新的桥接方法但老版本 App 没有这个方法调用直接报错。用户看到的是功能不可用。修法是在桥接层做版本协商H5 调用前先问原生你支持哪些方法原生返回一个能力列表H5 据此决定用哪个方案。这个机制叫能力探测是混合开发的标配。我后来把它做成了一个BridgeManager所有桥接方法注册在里面H5 通过getSupportedMethods()获取列表。6.4 坑十五日志上报把用户隐私带出去了有一次排查问题我让用户开了详细日志结果日志里包含了用户的搜索关键词。这属于隐私数据不该上报。虽然是自己排查用但流程上不规范。修法是日志上报前做脱敏手机号、邮箱、关键词这类字段统一替换成占位符。并且日志分级debug 日志只在开发版开启release 版只上报 error 级别。这个坑不是技术问题是意识问题。任何要离开设备的数据都要先问一句这里面有没有用户隐私7. 第六阶段把十六个坑沉淀成可复用的检查清单7.1 坑十六没有检查清单同样的坑会踩第二次最后一个坑是关于坑本身的。项目做完我复盘时发现有些坑我在上一个项目里踩过这个项目又踩了一遍。原因是没有沉淀成清单。所以我把这十六个坑整理成了一份上线前检查清单每次发版前过一遍。清单分四块检查块检查项对应坑构建配置AGP/Gradle/Kotlin/JDK 版本对齐坑一构建配置依赖用 BOM 锁版本坑二构建配置混淆规则覆盖反射类坑十相关构建配置签名文件三处备份坑十WebView混合内容模式设置坑三WebView桥接方法线程安全坑四WebView返回键与页面栈同步坑五WebView缓存策略与 H5 版本化配合坑六WebViewonRenderProcessGone 处理坑十三数据层Room Migration 完整坑七数据层网络错误统一封装坑八数据层图片缓存策略统一坑九平台适配targetSdk 行为变更逐条对照坑十一平台适配自适应图标与启动图坑十二上线运维崩溃监控接入并上传符号表坑十三相关上线运维桥接能力探测机制坑十四上线运维日志脱敏与分级坑十五这份清单我现在每个项目都用新项目踩新坑的概率明显下降。7.2 WorkBuddy 在复盘阶段的价值复盘时我又用了一次 WorkBuddy把十六个坑的描述丢给它让它帮我归类、找共性。它给出的归类和我自己想的差不多但它补充了一点这十六个坑里有九个属于配置类七个属于运行时行为类。配置类的坑可以在项目初始化时一次性规避运行时行为类的坑需要靠测试覆盖。这个视角对我很有用。后来我调整了策略初始化阶段花更多时间把配置做扎实测试阶段重点覆盖运行时行为。资源配置变了效率就上来了。7.3 关于AI 能不能替代开发者这件事做完这个项目我对这个问题的答案更清晰了AI 能替代的是写代码这个动作替代不了做决策这个过程。WorkBuddy 帮我省了大量敲键盘的时间但每一个架构选择、每一个版本对齐、每一个安全设置都需要我自己判断。关键词里有很多关于 WorkBuddy 使用教程、国际版、从入门到精通的搜索说明很多人正在尝试这类工具。我的建议是把它当成一个执行力极强但需要明确指令的初级工程师你给它的约束越清晰它交付的质量越高。别指望它替你想清楚需求那是你的活。7.4 给准备用 WorkBuddy 搭 App 的人几条实操建议第一项目初始化时先把技术栈和版本矩阵定死再让 WorkBuddy 生成代码。版本对齐这件事AI 不会主动帮你做。第二WebView 相关的代码一律按最坏情况写混合内容、线程、返回键、渲染进程崩溃四个都要处理。第三数据层的 Migration、混淆规则、签名备份这三件事在项目第一天就做好别拖到上线前。第四上线后第一时间接崩溃监控并且确保符号表上传。没有监控的线上版本等于闭着眼睛开车。第五把踩过的坑记下来形成自己的清单。工具会更新平台会更新但配置要对齐、行为要验证、隐私要脱敏这些原则不会变。我在这个项目里最大的体会是能上线的 App 和能跑的 Demo 之间隔着的不是代码量是那十六个坑。WorkBuddy 帮你快速跨过从零到能跑但从能跑到能上线这段路得你自己一步步走。走完之后把路标记下来下次就快了。