1. 从零到上线为什么我选择 WorkBuddy 作为主力开发工具去年年底我接了一个私活客户要求两周内出一个能装到手机上的 App功能不复杂——用户注册登录、发帖、看图、简单聊天。预算不高但要求“看起来像个正经产品”。我手里没有原生开发团队自己写 Android 和 iOS 两套代码时间根本不够。试了几条路之后我最终用 WorkBuddy 配合 Supabase 把这件事跑通了从搭建到上架测试版一共花了十一天。WorkBuddy 在这类场景里的定位很清晰它把 AI 辅助编码、项目脚手架、常用能力封装这几件事揉在一起让你用接近写脚本的方式产出一个可安装的 App。配合 Supabase 做后端WebView 做混合渲染整个链路是通的。这篇文章我会把六个阶段完整拆开把中间踩过的十六个坑一个一个标出来包括 Supabase 连接报read ECONNRESET、WebView 在 Android 上不打印日志、iOS 浏览器唤起安装 App 失败这些具体问题。如果你也是一个人或者小团队要快速交付一个能上线的 App这篇内容可以直接抄作业。先说清楚适合谁看。第一类是有前端基础、想往移动端延伸的开发者你会 HTML、JavaScript但对 Android 和 iOS 的打包流程不熟。第二类是用过 AI 编程工具、但没完整走过上线流程的人你可能让 AI 生成过页面但不知道怎么把它变成能安装的包。第三类是做外包或者接私活的独立开发者时间紧、预算有限需要一个能快速复用的技术组合。如果你属于这三类中的任何一类接下来的内容会对你有直接帮助。整个项目我用的技术栈是WorkBuddy 做项目生成和 AI 辅助编码Supabase 做数据库、认证和存储WebView 做混合页面的承载容器最后用 WorkBuddy 自带的打包能力出安装包。这个组合的核心逻辑是——把重活交给后端服务把界面交给 Web 技术把胶水代码交给 AI 生成。你不需要精通原生开发但需要理解每个环节在干什么否则出了问题你连排查方向都没有。2. 六个阶段拆解从项目初始化到可安装包2.1 阶段一环境准备与 WorkBuddy 初始化这一步看起来简单但坑最多。我第一次装 WorkBuddy 的时候在 Linux 环境下直接卡在了依赖安装上。WorkBuddy 对 Node 版本有要求我当时系统里是 Node 16它需要 18 以上。版本不对不会给你明确报错而是安装到一半卡住日志里只有一行模糊的提示。后来我换成 Node 20 LTS 才顺利跑通。安装流程我整理成可直接执行的步骤# 确认 Node 版本必须 18 以上 node -v # 如果版本不对用 nvm 切换 nvm install 20 nvm use 20 # 全局安装 WorkBuddy CLI npm install -g workbuddy-cli # 初始化项目 workbuddy init my-app初始化的时候会让你选项目模板。这里有个选择逻辑如果你要做的是内容型 App选带 WebView 容器的基础模板如果要做工具型 App选带原生能力桥接的模板。我选的是 WebView 基础模板因为我的界面全部用 HTML 写只需要一个壳来承载。注意WorkBuddy 初始化时会生成一个workbuddy.config.json文件里面的appId和appName必须和后面打包时填写的一致否则安装包会装不上或者覆盖安装失败。这个细节文档里没写我是踩了一次才发现的。环境准备阶段还有一个容易忽略的点Android SDK 和 JDK 的路径配置。WorkBuddy 打包 Android 包的时候会调用本地的 Gradle如果你的ANDROID_HOME没配好打包会直接失败报错信息是SDK location not found。解决办法是在项目根目录建一个local.properties文件写入sdk.dir/your/path/to/android-sdk这个文件不要提交到 Git因为每个人的路径不一样。我一般会把它加到.gitignore里然后在 README 里写清楚怎么配置。2.2 阶段二Supabase 后端搭建与连接配置Supabase 在这个项目里承担了数据库、用户认证、文件存储三个角色。选它的原因很直接免费额度够用自带 REST API 和实时订阅不需要自己写后端接口。对于我这种一个人干活的情况省掉后端开发至少省了三四天。创建项目之后你会在 Supabase 控制台拿到两个关键信息Project URL和Anon Key。这两个东西要填到 WorkBuddy 项目的环境变量里。我建议建一个.env文件SUPABASE_URLhttps://xxxxx.supabase.co SUPABASE_ANON_KEYeyJhbGciOi...然后在代码里通过process.env.SUPABASE_URL读取。这里有个坑WorkBuddy 打包的时候不会自动读取.env文件你需要在workbuddy.config.json里显式声明环境变量或者在构建脚本里注入。我第一次打包后发现 App 里读不到环境变量排查了半天才发现是这个问题。数据库表的设计我走了弯路。一开始我想把所有字段都塞到一张posts表里结果查询越来越慢代码也越来越乱。后来拆成三张表users存用户信息posts存帖子内容files存文件元信息。Supabase 自带auth.users表你只需要建一张profiles表来存额外信息通过id关联。-- 用户扩展信息表 create table profiles ( id uuid references auth.users on delete cascade primary key, nickname text, avatar_url text, created_at timestamp default now() ); -- 帖子表 create table posts ( id bigint generated by default as identity primary key, user_id uuid references profiles(id), content text, image_url text, created_at timestamp default now() );权限方面Supabase 的行级安全策略RLS一定要开。我一开始图省事没开结果任何人拿到 Anon Key 就能读写所有数据。开启 RLS 之后你需要为每张表写策略。比如posts表的策略是所有人可读只有登录用户可以插入只有作者可以删除自己的帖子。实操心得Supabase 的 RLS 策略写起来有点绕我建议先在控制台的 SQL Editor 里测试确认策略生效后再写到代码里。测试方法是用 Anon Key 发一个请求看能不能拿到不该拿的数据。连接 Supabase 的时候我遇到了read ECONNRESET这个报错。这个问题的原因是 Supabase 的免费项目在一段时间不活动后会进入休眠状态第一次连接需要唤醒如果超时时间设得太短就会报这个错。解决办法是在 Supabase 客户端初始化时把超时时间调大import { createClient } from supabase/supabase-js const supabase createClient( process.env.SUPABASE_URL, process.env.SUPABASE_ANON_KEY, { auth: { persistSession: true }, global: { fetch: (...args) { // 把超时时间从默认的 10 秒调到 30 秒 const controller new AbortController() const timeout setTimeout(() controller.abort(), 30000) return fetch(...args, { signal: controller.signal }) .finally(() clearTimeout(timeout)) } } } )这个改动之后read ECONNRESET的出现频率明显下降。如果还是偶尔出现可以在 App 启动时先发一个轻量请求“预热”一下连接。2.3 阶段三WebView 容器搭建与页面通信WebView 是这个项目里最关键的环节也是最容易出问题的地方。我的方案是用 WorkBuddy 生成一个原生壳里面放一个全屏 WebView加载本地的 HTML 文件。这样界面用 Web 技术写原生能力通过桥接调用。WebView 的配置有几个关键参数// Android 端 WebView 配置 WebView webView findViewById(R.id.webview); WebSettings settings webView.getSettings(); settings.setJavaScriptEnabled(true); settings.setDomStorageEnabled(true); settings.setAllowFileAccess(true); settings.setAllowContentAccess(true); settings.setMediaPlaybackRequiresUserGesture(false); webView.setWebChromeClient(new WebChromeClient()); webView.setWebViewClient(new WebViewClient()); webView.loadUrl(file:///android_asset/www/index.html);setDomStorageEnabled(true)必须开否则 localStorage 用不了Supabase 的会话持久化会失效。setMediaPlaybackRequiresUserGesture(false)是为了让音频和视频能自动播放如果你的 App 不需要这个能力可以不开。WebView 和原生之间的通信我用的是addJavascriptInterfacewebView.addJavascriptInterface(new WebAppInterface(this), AndroidBridge);然后在 HTML 里这样调用// 调用原生方法 window.AndroidBridge.showToast(操作成功); // 原生调用网页方法 // Android 端webView.evaluateJavascript(javascript:onNativeCallback(data), null)这里有个坑addJavascriptInterface在 Android 4.2 以下有安全漏洞虽然现在最低版本都高于这个但如果你要兼容老设备需要做版本判断。另外注入的对象名不要用window或者document这种会冲突。WebView 不打印日志这个问题我卡了整整一个下午。现象是网页里的console.log在 Android Studio 的 Logcat 里完全看不到。原因是 WebView 默认不把 console 输出转发到原生日志。解决办法是重写WebChromeClient的onConsoleMessage方法webView.setWebChromeClient(new WebChromeClient() { Override public boolean onConsoleMessage(ConsoleMessage consoleMessage) { Log.d(WebView, consoleMessage.message() -- From line consoleMessage.lineNumber() of consoleMessage.sourceId()); return true; } });加上这段之后网页里的日志就能在 Logcat 里看到了。这个技巧在调试 WebView 页面时非常有用建议一开始就加上。还有一个问题是 WebView 的历史版本兼容。不同 Android 版本自带的 WebView 内核不一样老设备上的内核可能不支持某些 ES6 语法。我的做法是在 WorkBuddy 的构建配置里开启 Babel 转译把代码降级到 ES5。这样虽然包体积会大一点但兼容性有保障。2.4 阶段四AI 辅助编码与 WorkBuddy Skill 使用WorkBuddy 的 AI 辅助编码能力是我用它的主要原因之一。它和普通的代码补全不一样你可以用自然语言描述需求它直接生成可运行的代码块。比如我说“帮我写一个用户登录页面包含邮箱和密码输入框点击登录调用 Supabase 认证”它会生成完整的 HTML、CSS 和 JavaScript。但 AI 生成的东西不能直接用必须过一遍。我总结了几类常见问题第一类是环境变量引用错误。AI 不知道你的环境变量名是什么它会用YOUR_SUPABASE_URL这种占位符。你需要全局替换成实际的变量名。第二类是 API 版本不匹配。Supabase 的 JavaScript 客户端从 v1 到 v2 有破坏性变更AI 可能生成 v1 的写法。你需要检查createClient的调用方式v2 的写法是createClient(url, key)v1 是createClient(url, key, options)。第三类是缺少错误处理。AI 生成的代码通常只写成功路径网络请求失败、用户输入非法这些情况它不管。你需要自己补上try-catch和表单校验。WorkBuddy Skill 是它的自定义指令功能。你可以把常用的操作写成 Skill之后直接调用。我建了几个常用的create-page生成一个带导航栏和内容区的基础页面supabase-query生成一个带错误处理的 Supabase 查询函数webview-bridge生成 WebView 和原生通信的桥接代码Skill 的写法是在项目根目录建一个skills文件夹里面每个.md文件就是一个 Skill。文件开头用 YAML 写元信息后面写指令内容。比如--- name: supabase-query description: 生成带错误处理的 Supabase 查询函数 --- 请生成一个 Supabase 查询函数要求 1. 使用 async/await 语法 2. 包含 try-catch 错误处理 3. 错误时返回 { data: null, error } 4. 成功时返回 { data, error: null }这个功能用熟了之后编码效率提升很明显。但要注意Skill 的指令要写得具体越具体生成的结果越可用。模糊的指令会得到模糊的代码。2.5 阶段五打包与签名配置打包是上线前的最后一道关卡也是坑最密集的地方。WorkBuddy 支持打包 Android APK 和 iOS IPA我主要说 Android 的流程因为 iOS 需要苹果开发者账号流程更复杂。Android 打包分两步生成签名密钥然后打包。签名密钥用keytool生成keytool -genkeypair -v \ -keystore my-release-key.keystore \ -alias my-key-alias \ -keyalg RSA \ -keysize 2048 \ -validity 10000执行后会让你输入密码和一堆信息密码一定要记住后面打包和上架都要用。validity设 10000 天差不多 27 年够用了。然后在workbuddy.config.json里配置签名信息{ android: { signing: { keystore: my-release-key.keystore, alias: my-key-alias, password: your-password } } }注意密码不要直接写在配置文件里提交到 Git。我一般用环境变量的方式注入或者在 CI 里配置。本地开发可以用一个keystore.properties文件然后加到.gitignore。打包命令workbuddy build android --release打包过程中最常见的错误是资源文件缺失。WorkBuddy 会把www目录下的文件打包进 APK如果你的 HTML 里引用了外部 CDN 的资源打包后可能加载不出来。解决办法是把所有依赖下载到本地或者确保 App 有网络权限。另一个坑是appId冲突。如果你之前用同一个appId装过测试版再装正式版会提示签名不一致。解决办法是卸载旧版本再装或者换一个appId。我一般会在测试阶段用com.example.myapp.debug正式版用com.example.myapp这样两个可以共存。2.6 阶段六上线前的检查与 iOS 唤起安装Android 包打出来之后不要急着分发。先做一轮检查安装到真机上确认能正常启动测试注册、登录、发帖、看图这些核心流程断网测试看错误提示是否友好检查权限申请是否合理不要一上来就要一堆权限iOS 这边如果你没有开发者账号可以用 TestFlight 做内测或者用 Ad Hoc 分发。但 Ad Hoc 需要收集设备 UDID比较麻烦。我用的方案是先出 Android 包给客户看效果iOS 等确认后再走正式流程。iOS 浏览器唤起安装 App 这个需求实现方式是在网页里放一个链接指向 IPA 文件的下载地址然后通过itms-services协议唤起安装a hrefitms-services://?actiondownload-manifesturlhttps://your-server.com/manifest.plist 安装 iOS 版 /a这个manifest.plist文件需要包含 IPA 的下载地址、Bundle ID、版本号等信息。而且这个链接必须在 Safari 里打开才有效微信内置浏览器不行。所以通常的做法是引导用户“在 Safari 中打开”。这里有个坑iOS 对itms-services的链接有证书要求你的下载地址必须是 HTTPS而且证书要受信任。自签证书不行。我用的是 Supabase Storage 存 IPA 文件它自带 HTTPS省去了配证书的麻烦。3. 十六个坑的完整清单与排查方法3.1 环境与依赖类问题坑 1Node 版本不匹配导致安装卡住。现象是npm install -g workbuddy-cli执行到一半没反应也不报错。解决办法是确认 Node 版本在 18 以上推荐 20 LTS。坑 2Android SDK 路径未配置导致打包失败。报错信息是SDK location not found。解决办法是在项目根目录建local.properties写入sdk.dir路径。坑 3JDK 版本不兼容。WorkBuddy 打包需要 JDK 17如果你系统里是 JDK 8 或 11会报Unsupported class file major version。解决办法是安装 JDK 17 并设置JAVA_HOME。坑 4Gradle 下载超时。第一次打包会下载 Gradle 依赖网络不好的话会卡住。解决办法是配置国内镜像源在build.gradle里把仓库地址换成阿里云镜像。3.2 Supabase 连接类问题坑 5read ECONNRESET报错。原因是 Supabase 免费项目休眠后首次连接超时。解决办法是调大 fetch 超时时间并在 App 启动时预热连接。坑 6RLS 策略未开启导致数据泄露。现象是未登录用户也能读写数据。解决办法是为每张表开启 RLS 并编写策略。坑 7环境变量打包后丢失。现象是 App 里读不到SUPABASE_URL。解决办法是在workbuddy.config.json里显式声明环境变量。坑 8Supabase 认证会话不持久。现象是每次打开 App 都要重新登录。解决办法是确保 WebView 的setDomStorageEnabled(true)已开启并且 Supabase 客户端配置了persistSession: true。3.3 WebView 类问题坑 9WebView 不打印日志。现象是console.log在 Logcat 里看不到。解决办法是重写WebChromeClient.onConsoleMessage。坑 10WebView 加载本地文件失败。现象是白屏。原因是文件路径不对Android 的本地文件路径是file:///android_asset/www/index.html注意是三个斜杠。坑 11WebView 和原生通信失败。现象是window.AndroidBridge是 undefined。原因是addJavascriptInterface在页面加载完成后才注入需要在onPageFinished里调用或者确保注入的对象名不冲突。坑 12老设备 WebView 内核不支持 ES6。现象是页面报语法错误。解决办法是开启 Babel 转译把代码降级到 ES5。3.4 打包与上线类问题坑 13签名不一致导致安装失败。现象是提示“应用未安装”。解决办法是卸载旧版本或者确保签名密钥一致。坑 14appId冲突。现象是两个 App 互相覆盖。解决办法是测试版和正式版用不同的appId。坑 15iOSitms-services链接无效。现象是点击没反应。原因是链接必须在 Safari 打开且下载地址必须是受信任的 HTTPS。坑 16打包后资源文件缺失。现象是图片或样式加载不出来。解决办法是把 CDN 资源下载到本地或者确保 App 有网络权限。4. 可复用的经验与后续扩展方向这套方案跑通之后我把它整理成了一个项目模板下次接类似需求可以直接复用。模板里包含了 WorkBuddy 的基础配置、Supabase 的建表 SQL、WebView 的桥接代码、以及打包脚本。新项目只需要改appId、appName和 Supabase 的连接信息就能在一天内出一个可安装的测试包。有几个经验我觉得值得单独拿出来说。第一Supabase 的 RLS 策略一定要在项目初期就配好不要等到上线前才补因为后期改策略会影响已有数据。第二WebView 的日志转发一定要在开发阶段就加上否则调试效率极低。第三打包签名密钥一定要备份丢了就没办法给已安装的用户推送更新。后续如果要扩展我建议从两个方向入手。一是加推送通知Supabase 支持 Edge Functions可以配合第三方推送服务实现。二是加离线缓存用 Service Worker 把核心页面缓存到本地弱网环境下也能打开。这两个方向我都试过推送的坑主要在证书配置离线缓存的坑主要在缓存更新策略后面有机会再单独写。最后分享一个我常用的调试技巧在 WebView 里注入一个全局的错误捕获把错误信息通过桥接发给原生原生再写到日志里。这样即使页面崩溃你也能知道是哪一行出的问题。window.onerror function(message, source, lineno, colno, error) { if (window.AndroidBridge) { window.AndroidBridge.logError( JSON.stringify({ message, source, lineno, colno }) ); } return false; };这个技巧帮我定位过好几次只在真机上出现的诡异问题。网页在浏览器里跑得好好的一到 WebView 里就白屏加上这个之后就能看到具体的报错信息了。