1. 从零到上线：为什么我选择用 WorkBuddy 走完整个 App 开发链路
去年年底我接了一个内部工具类的项目，需求很明确：做一个能在 Android 和 iOS 上跑起来的轻量级应用，核心功能是数据看板加消息推送，团队一共两个人，排期给到六周。按传统路子走，原生 Android 加 iOS 双端开发，光环境搭建和基础框架就得吃掉两周，后面联调、打包、上架又是一堆事。我当时就在想，有没有一种方式能把重复劳动压到最低，让两个人也能把产品完整推上线。
WorkBuddy 就是在这个背景下进入我的视野的。简单说，它是一套面向应用开发全流程的协作与构建工具链，覆盖了从项目初始化、页面搭建、逻辑编排，到打包签名、渠道分发、版本管理的完整环节。它不是一个单纯的代码编辑器插件，也不是一个低代码拖拽平台，更像是把 App 开发过程中那些琐碎但必须做的环节，用一套统一的工程化方案串了起来。你可以在里面管理多个 App 项目，每个项目有独立的构建配置、资源目录和发布通道，同时又能共享公共组件和工具函数。
这篇文章适合谁看？如果你是一个独立开发者，或者小团队里负责移动端的技术负责人，手头有明确的产品需求但不想在工程配置上耗费太多精力，那这篇内容应该能帮到你。如果你已经用过 WorkBuddy 但只停留在“能跑起来”的阶段，想把它真正用到生产环境，那后面关于构建优化、WebView 调优、签名管理和上架避坑的部分，应该也有参考价值。我会把整个过程中踩过的十六个坑逐一拆开讲，每个坑都附上我实际用的解决方案和排查思路。
需要提前说明的是，WorkBuddy 本身在迭代，不同版本的操作路径可能有细微差异。我用的版本是去年 Q4 的稳定版，如果你用的是更新版本，部分菜单名称或配置项位置可能变了，但核心逻辑和工程思路是通用的。另外，文中涉及的所有配置和代码片段，都是我在实际项目中验证过的，你可以直接拿去改改就用，但记得根据自己的包名、签名信息和渠道要求做替换。
2. 六个阶段拆解：从项目初始化到正式上线的完整路径
2.1 阶段一：项目初始化与工程结构设计
很多人拿到 WorkBuddy 的第一反应是直接新建项目然后开始写页面，我一开始也这么干，结果做到第三个页面的时候发现资源引用路径乱成一团，公共组件散落在各个目录里，改一个按钮样式要翻五六个文件。后来我重新梳理了一套工程结构，核心原则是“按功能分层，按业务分模块”。
具体来说，项目根目录下我分了这么几个顶层目录：app放主入口和全局配置，modules放各业务模块，每个模块内部再分pages、components、services、assets，shared放跨模块复用的工具函数和基础组件，build放构建脚本和渠道配置。这样分的好处是，当你需要把某个模块单独抽出来做插件化或者分包加载时，直接整个目录移走就行，不会牵连其他代码。
WorkBuddy 在初始化项目时会生成一个默认的workbuddy.config.json，这个文件是整个工程的枢纽。我建议在项目一开始就把里面的moduleAlias配好，比如把@shared映射到shared目录，把@modules映射到modules目录。这样在代码里引用的时候写import { formatDate } from '@shared/utils/date'，不管文件在哪个层级都不会出错。我见过太多项目因为相对路径写得太深，重构目录时改到崩溃。
还有一个容易被忽略的点是.gitignore的配置。WorkBuddy 在构建过程中会生成一些中间产物，比如build/cache、build/output、node_modules这些都不应该进版本库。但build/channel下面的渠道配置文件是要提交的，因为那是团队共享的发布配置。我建议在项目初始化完成后，先花十分钟把忽略规则理清楚，不然后面仓库体积会膨胀得很快。
2.2 阶段二：页面搭建与组件化开发
WorkBuddy 的页面搭建支持两种模式：一种是传统的代码编写，另一种是可视化编排加代码混合。我的经验是，对于交互复杂的页面，纯代码写更可控；对于表单类、列表类这种结构重复度高的页面，用可视化编排能省不少时间。但不管用哪种方式，组件化的思路必须贯穿始终。
我一般会把组件分成三类：基础组件、业务组件和页面级组件。基础组件就是按钮、输入框、卡片这种，放在shared/components下面，全局复用。业务组件是跟具体业务逻辑绑定的，比如“订单状态标签”、“用户头像组”，放在对应模块的components目录下。页面级组件就是整个页面的容器，负责数据获取和状态管理，放在pages目录下。
这里有个坑我踩得很深：一开始我把所有组件都放在一个components目录里，结果基础组件和业务组件混在一起，后来想抽一个基础组件库给另一个项目用，发现根本抽不出来，因为业务组件里引用了太多模块特有的东西。所以从项目初期就要把边界划清楚，基础组件里绝对不能出现任何业务相关的 API 调用或状态引用。
WorkBuddy 在组件注册方面提供了一套自动扫描机制，你只需要在组件文件里按照约定导出，构建时会自动注册到全局组件表里。但这个机制有个限制：它只扫描shared/components和当前模块的components目录。如果你把组件放在其他位置，就需要手动在workbuddy.config.json的componentPaths里追加路径。我建议尽量遵循默认约定，减少配置复杂度。
2.3 阶段三：数据层与接口联调
数据层这块，WorkBuddy 本身不强制你用某种方案，但它在模板里预置了一套基于请求拦截器的 HTTP 客户端封装。我的做法是在此基础上再包一层services层，每个业务模块有自己的 service 文件，里面定义该模块所有的接口调用方法。这样做的好处是，当后端接口地址变更或者参数结构调整时，你只需要改 service 文件，页面代码不用动。
接口联调阶段最耗时的往往不是写代码，而是等后端。我的经验是，在接口还没完全就绪的时候，先用 WorkBuddy 的 Mock 功能把数据假造出来，页面先跑通交互逻辑。WorkBuddy 支持在mock目录下按照接口路径定义模拟数据，构建时如果检测到mock目录存在且当前是开发模式，就会自动拦截请求返回模拟数据。这个功能在前后端并行开发时特别有用，我试过整个前端页面都做完了，后端接口才刚定义好字段，但因为 Mock 数据一直在用，切换真实接口时只改了一个配置项。
还有一个细节是错误处理。很多人在联调阶段只关注成功回调，忽略了异常分支。我建议在 service 层统一处理网络错误、超时、业务错误码这三种情况，页面层只关心成功数据的渲染。WorkBuddy 的请求拦截器支持注册多个错误处理器，你可以按错误类型分别注册，比如网络错误弹全局提示，业务错误码跳转到对应处理页面。
2.4 阶段四：构建配置与多渠道打包
构建配置是 WorkBuddy 比较强大的部分，也是坑比较集中的地方。它支持多环境配置，你可以在build/env目录下定义dev、staging、prod三套环境变量，构建时通过--env参数指定。环境变量里可以定义 API 地址、资源 CDN 前缀、日志级别这些跟环境相关的东西。
多渠道打包是另一个重点。国内 Android 市场渠道众多，每个渠道可能需要不同的统计 SDK 配置或者启动图。WorkBuddy 的做法是在build/channel目录下为每个渠道建一个配置文件，里面可以覆盖workbuddy.config.json中的任意字段。构建时通过--channel参数指定渠道，工具会自动合并配置。我一般会把渠道配置分成两类：一类是只改统计 ID 的，直接继承主配置；另一类是需要改包名或签名的，单独写完整配置。
这里有个坑：渠道配置的合并是浅合并还是深合并，取决于 WorkBuddy 的版本。我用的版本是深合并，也就是说如果你在渠道配置里写了一个对象，它会跟主配置里的同名对象逐字段合并，而不是整个替换。这个行为在大多数情况下是符合预期的，但如果你想把主配置里的某个数组完全替换掉，就需要用特殊语法标记。我建议在渠道配置里尽量只覆盖必要的字段，减少合并行为带来的不确定性。
2.5 阶段五：WebView 容器调优与混合开发
这个项目里有一部分页面是嵌入的 H5，所以 WebView 的调优花了我不少时间。WorkBuddy 默认使用系统 WebView，但在 Android 上，系统 WebView 的版本碎片化非常严重，不同厂商、不同系统版本的 WebView 内核差异很大。我遇到过一个典型问题：在某个品牌的手机上，H5 页面的localStorage写入失败，导致登录态丢失。排查后发现是该机型系统 WebView 版本过低，不支持某些存储 API。
解决方案是在 WorkBuddy 的 WebView 配置里开启domStorageEnabled和databaseEnabled，同时在前端代码里做特性检测，不支持localStorage时降级到sessionStorage或者通过 JSBridge 存到原生侧。WorkBuddy 的 WebView 容器支持注入自定义的 JSBridge 方法，你可以在原生侧实现一套存储接口，H5 通过约定好的协议调用。
另一个常见问题是 WebView 的历史版本兼容。有些 H5 页面用了较新的 CSS 特性或者 JS API，在旧版 WebView 上会白屏。我的做法是在 WebView 加载前先通过 UserAgent 判断内核版本，低于某个阈值就跳转到一个提示页，引导用户升级系统 WebView 或者使用其他浏览器打开。WorkBuddy 支持在 WebView 配置里设置minimumWebViewVersion，低于这个版本时自动触发降级逻辑。
2.6 阶段六：签名、上架与版本管理
签名这块，WorkBuddy 支持在构建配置里指定 keystore 文件路径和别名密码。我建议不要把密码明文写在配置文件里，而是通过环境变量传入。WorkBuddy 在构建时会读取WORKBUDDY_KEYSTORE_PASSWORD和WORKBUDDY_KEY_ALIAS_PASSWORD这两个环境变量，你可以在 CI 系统里配置这些变量，本地开发时用.env文件加载。
上架流程每个平台要求不同，但核心材料是固定的：应用图标、截图、描述文案、隐私政策链接、权限说明。WorkBuddy 在构建产物里会自动生成一个release目录，里面包含 APK 或 IPA 文件以及一份release-notes.md，你可以把版本更新说明写在这里，上架时直接复制。我一般会在workbuddy.config.json里配置versionName和versionCode的生成规则，比如versionName用语义化版本，versionCode用构建时间戳，这样每次构建的版本号都是唯一的，避免上架时因为版本号重复被拒。
版本管理方面，WorkBuddy 支持在构建时自动生成版本变更日志，它会对比当前版本和上一个版本的 Git 提交记录，提取出跟当前构建相关的提交信息。这个功能在团队协作时很有用，但前提是提交信息要规范。我建议团队统一用feat:、fix:、chore:这样的前缀，WorkBuddy 在生成日志时会按类型分组，可读性会好很多。
3. 十六个坑逐一拆解：从环境配置到上架审核的避坑指南
3.1 环境与依赖相关的五个坑
第一个坑是 Node 版本不匹配。WorkBuddy 的构建脚本依赖 Node 的某些特性，我一开始用 Node 14 跑构建，结果在解析配置文件时一直报语法错误。后来查文档才发现需要 Node 16 以上。这个问题的隐蔽性在于，WorkBuddy 本身能启动，但构建到某个阶段才会报错，容易误以为是配置问题。建议在项目根目录放一个.nvmrc文件，写明推荐的 Node 版本，团队成员用 nvm 切换时就不会搞错。
第二个坑是依赖包版本冲突。WorkBuddy 的模板项目里预置了一些依赖，如果你再手动安装其他版本的同一个包，可能会导致构建时模块解析失败。我遇到过一次，项目里同时存在两个版本的lodash，构建时 WorkBuddy 的插件系统加载了错误版本，导致某个工具函数行为异常。解决方案是在package.json里用resolutions字段强制指定统一版本，或者在 WorkBuddy 配置里开启strictDependencyCheck，构建时会检测重复依赖并给出警告。
第三个坑是 Android SDK 路径配置。WorkBuddy 在构建 Android 包时需要知道 SDK 和 NDK 的位置。如果你用的是 Android Studio 自带的 SDK，路径通常在用户目录下，但 WorkBuddy 默认可能去读系统环境变量。我建议在workbuddy.config.json里显式配置androidSdkPath和androidNdkPath，避免因为环境变量不一致导致构建失败。另外，SDK 的版本也要注意，WorkBuddy 对compileSdkVersion和targetSdkVersion有最低要求，太低会报错，太高可能跟某些依赖不兼容。
第四个坑是 iOS 构建证书问题。如果你在 macOS 上构建 iOS 包，WorkBuddy 需要访问钥匙串里的证书和描述文件。我遇到过一次，证书明明在钥匙串里，但 WorkBuddy 就是找不到，后来发现是因为证书的信任设置被改成了“始终信任”而不是“使用系统默认”。改回来之后就好了。另外，描述文件的 UUID 要跟证书匹配，WorkBuddy 在构建时会校验这一点，不匹配会直接报错。
第五个坑是网络代理导致的依赖下载失败。这个坑比较特殊，因为不同网络环境下表现不一样。我的做法是在 WorkBuddy 配置里设置registry为国内镜像源，同时在 CI 环境里配置好对应的网络策略。如果你在本地开发时遇到依赖下载慢或者超时，可以先检查npm config get registry和 WorkBuddy 自己的registry配置是否一致。
3.2 页面与组件相关的四个坑
第六个坑是组件命名冲突。WorkBuddy 的自动组件注册机制是按文件名注册的，如果你在两个不同目录下有同名组件文件，后扫描到的会覆盖先扫描到的。我建议在组件文件名里加上模块前缀，比如user-avatar、order-status-tag，避免全局命名冲突。另外，WorkBuddy 在开发模式下会在控制台输出组件注册日志，你可以通过日志确认每个组件是否注册成功以及注册到了哪个命名空间。
第七个坑是页面生命周期理解偏差。WorkBuddy 的页面生命周期跟原生 Android 或 iOS 不完全一样，它有自己的onReady、onShow、onHide、onUnload四个核心钩子。我一开始按 Android 的onCreate、onResume来理解，结果在onReady里做了太多初始化工作，导致页面切换时卡顿。后来梳理清楚：onReady只做一次性的初始化，onShow做每次可见时的数据刷新，onHide做资源释放或状态保存。这个区分在页面频繁切换的场景下特别重要。
第八个坑是样式作用域问题。WorkBuddy 的组件样式默认是全局的，如果你在组件里写了一个.title类，它可能会影响到其他页面的同名类。解决方案是在组件的样式文件里开启scoped模式，WorkBuddy 会给每个组件的样式加上唯一属性选择器。但要注意，scoped模式下，父组件想覆盖子组件的样式会比较麻烦，需要用深度选择器。我一般是在基础组件里用scoped，在页面级组件里用全局样式加命名空间前缀。
第九个坑是图片资源路径。WorkBuddy 在构建时会对图片资源做压缩和哈希处理，如果你在代码里硬编码了图片路径，构建后可能会找不到。正确的做法是用 WorkBuddy 提供的资源引用函数，比如require('@assets/logo.png')或者import logo from '@assets/logo.png'，构建时会自动替换成带哈希的最终路径。另外，不同分辨率的图片要放在对应的drawable-xxhdpi目录下，WorkBuddy 会根据设备密度自动选择。
3.3 构建与打包相关的四个坑
第十个坑是构建缓存导致的“改了没生效”。WorkBuddy 为了加速构建，会缓存一些中间产物。但有时候你改了配置文件或者某个依赖，缓存没有及时失效，构建出来的包还是旧的行为。我遇到过一次，改了 API 地址但打包出来的 App 还是连的旧地址，排查了半天才发现是缓存问题。解决方案是在构建命令里加--no-cache参数强制全量构建，或者在 WorkBuddy 配置里设置cacheStrategy为smart，它会根据文件修改时间智能判断是否需要清缓存。
第十一个坑是渠道配置合并顺序。前面提到过渠道配置是深合并，但合并顺序是“主配置 → 环境配置 → 渠道配置”，后面的覆盖前面的。如果你在环境配置里定义了 API 地址，在渠道配置里又定义了一个不同的 API 地址，最终生效的是渠道配置里的。这个顺序在大多数情况下是合理的，但如果你想让某个渠道强制使用环境配置里的值，就需要在渠道配置里显式删除该字段，而不是留空。WorkBuddy 支持用null值来删除字段，但要注意null和undefined的行为可能不同。
第十二个坑是签名文件路径问题。WorkBuddy 在构建时读取 keystore 文件的路径是相对于项目根目录的，但如果你在 CI 环境里，工作目录可能不是项目根目录。我建议在配置里用绝对路径，或者用环境变量传入。另外，keystore 文件的权限也要注意，在 Linux 或 macOS 上，如果文件权限过于开放，某些构建工具会拒绝使用。我一般会设置成600，只允许当前用户读写。
第十三个坑是构建产物体积过大。WorkBuddy 默认会把所有资源都打进包里，包括一些只在开发环境用的调试工具。我建议在构建配置里开启treeShaking和minify，同时用exclude字段排除掉不需要的文件。另外，如果项目里用了较大的第三方库，可以考虑按需引入或者用 WorkBuddy 的dynamicImport功能做懒加载。我实测下来，开启这些优化后，包体积能减少百分之三十左右。
3.4 上架与审核相关的三个坑
第十四个坑是隐私政策合规。现在各大应用市场对隐私政策的要求越来越严，如果你的 App 收集了用户信息但没有在隐私政策里说明，或者说明不完整，审核会被拒。WorkBuddy 在构建时会生成一个privacy-manifest.json，你可以在里面声明 App 收集的所有数据类型和用途。我建议在项目初期就把这个文件建好，每加一个涉及用户数据的功能就更新一次，不要等到上架前才补。
第十五个坑是权限申请时机。Android 和 iOS 对权限申请的要求不同，Android 可以在需要时动态申请，iOS 则需要在Info.plist里声明用途描述。WorkBuddy 在构建 iOS 包时会根据workbuddy.config.json里的permissions字段自动生成Info.plist里的描述文案。但要注意，描述文案必须具体说明用途，不能写“需要此权限以正常运行”这种模糊表述，否则审核会被拒。我一般会写“用于在您保存图片时访问相册”这种具体场景。
第十六个坑是版本号回退问题。如果你上架了一个版本后发现严重 bug，想回退到上一个版本，但应用市场通常不允许版本号回退。WorkBuddy 的版本管理功能支持在构建时指定versionCode，我建议每次上架前都确认versionCode是递增的，并且保留好每个版本的构建产物和对应的 Git tag。这样即使需要紧急修复，也能快速定位到上一个稳定版本的代码。
4. 可复用经验总结：从项目实战中提炼的六条核心原则
4.1 配置即代码，所有环境差异都要显式声明
我在这个项目里最大的体会是，凡是跟环境相关的配置，都不要靠“默认值”或者“隐式行为”，一定要显式写出来。WorkBuddy 的配置系统支持多环境覆盖，但如果你不写，它就用默认值，而默认值在不同版本之间可能会变。我现在的做法是，在workbuddy.config.json里把dev、staging、prod三套环境的差异全部列出来，哪怕某个环境的值跟默认值一样，也写上去。这样当默认值变化时，你的项目行为不会受影响。
另外，配置文件里的敏感信息，比如签名密码、API 密钥，一定要用环境变量引用，不要明文写在文件里。WorkBuddy 支持${ENV_VAR}这种语法，构建时会从环境变量里读取。在 CI 系统里配置这些变量，本地开发时用.env文件加载，.env文件要加入.gitignore。我见过有团队把签名密码提交到了公开仓库，结果被人恶意打包，教训很深刻。
4.2 组件边界要清晰，基础组件零业务依赖
组件化说起来简单，做起来最容易出问题的地方就是边界模糊。我的原则是：基础组件里绝对不能出现任何业务相关的 API 调用、状态引用或者路由跳转。基础组件只接受 props，只触发事件，所有业务逻辑由使用它的页面或业务组件处理。这样基础组件才能跨项目复用，也才能独立测试。
业务组件可以引用基础组件，可以调用 service 层的方法，但不要直接操作全局状态。我一般会让业务组件通过 props 接收数据，通过事件向上传递操作意图，由页面级组件统一管理状态和调用 service。这样数据流向是单向的，排查问题时容易定位。WorkBuddy 在组件通信方面支持事件总线和全局状态两种方式，我建议优先用 props 和事件，全局状态只在跨多层级组件通信时使用。
4.3 构建流程要可重复，本地和 CI 行为一致
构建流程最怕的就是“在我机器上是好的”。要避免这个问题，关键是让本地构建和 CI 构建使用完全相同的环境和配置。我现在的做法是，把构建命令写进package.json的scripts里，本地和 CI 都执行同一个命令。环境变量通过.env文件和 CI 的变量配置来管理，但变量名和含义保持一致。
另外，构建产物的命名和存放路径也要统一。WorkBuddy 默认会把产物放在build/output目录下，按渠道和版本号分文件夹。我建议在 CI 里把产物上传到制品库，并记录每次构建的 Git commit hash 和版本号。这样当需要回溯某个版本的构建产物时，能快速找到。我一般会在构建脚本最后加一步，生成一个build-info.json，里面包含构建时间、Git 分支、commit hash、版本号等信息，跟产物一起归档。
4.4 WebView 调优要分版本处理，不能一刀切
WebView 的兼容性问题没有银弹，不同 Android 版本、不同厂商的 WebView 内核差异很大。我的经验是，先确定你的目标用户群体主要使用的系统版本范围，然后针对这个范围做兼容。WorkBuddy 的 WebView 配置支持按系统版本设置不同的参数，比如在 Android 7 以下禁用某些新特性，在 Android 10 以上启用硬件加速。
另外，JSBridge 的协议设计要考虑向前兼容。我一般会在协议里加一个版本号字段，H5 和原生侧都根据版本号决定支持哪些方法。当原生侧升级了 JSBridge 实现，但用户的 H5 页面还是旧版本时，可以通过版本号协商，避免调用不存在的方法导致崩溃。WorkBuddy 在 WebView 容器里预置了一套 JSBridge 框架，你可以在此基础上扩展，也可以完全自己实现。
4.5 上架材料要提前准备，不要等到构建完才补
上架审核被拒最常见的原因不是代码问题，而是材料不齐全或者不合规。我现在的做法是，在项目初期就建一个release目录，里面放应用图标、截图、描述文案、隐私政策这些材料。每次版本迭代时，同步更新这些材料。WorkBuddy 在构建时会检查release目录下的文件是否齐全，不齐全会给出警告。
隐私政策这块要特别注意，不同应用市场的要求略有差异，但核心是“收集什么数据、用来做什么、跟谁共享、用户如何撤回同意”。我一般会写一个详细的隐私政策文档，然后在 WorkBuddy 的privacy-manifest.json里引用这个文档的链接。另外，如果 App 里有第三方 SDK，也要在隐私政策里说明这些 SDK 收集的数据类型。WorkBuddy 支持在配置里声明第三方 SDK 列表，构建时会自动生成对应的隐私政策片段。
4.6 版本管理要跟 Git 流程绑定，每次构建都可追溯
版本管理不只是改个版本号那么简单，它应该跟你的 Git 工作流绑定。我现在的做法是，每次发布版本时，从develop分支切一个release分支，在release分支上做最后的测试和构建。构建成功后，打一个 Git tag，tag 名称跟版本号一致。然后合并到main分支，并在main分支上再构建一次，确保main分支的代码跟发布版本完全一致。
WorkBuddy 在构建时会读取当前 Git 分支和 commit hash，并写入构建产物。这样当用户反馈问题时，你可以通过构建产物里的信息快速定位到对应的代码版本。另外，我建议在workbuddy.config.json里配置versionName的生成规则为major.minor.patch，versionCode用git rev-list --count HEAD生成，这样每次提交都会递增版本号，不会重复。
5. 常见问题速查与排查技巧实录
5.1 构建失败类问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 构建时报 Node 版本错误 | Node 版本低于要求 | 执行node -v查看版本 | 升级到 Node 16 以上，或用 nvm 切换 |
| 依赖解析失败 | 依赖包版本冲突 | 查看构建日志中的模块路径 | 用resolutions统一版本，或清理node_modules重装 |
| Android SDK 找不到 | SDK 路径未配置 | 检查workbuddy.config.json中的androidSdkPath | 显式配置绝对路径，或设置ANDROID_HOME环境变量 |
| iOS 证书找不到 | 钥匙串信任设置问题 | 打开钥匙串访问，查看证书信任设置 | 改为“使用系统默认”，确保描述文件 UUID 匹配 |
| 构建产物跟代码不一致 | 缓存未失效 | 对比构建时间和文件修改时间 | 加--no-cache参数，或设置cacheStrategy为smart |
5.2 运行时异常类问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| H5 页面白屏 | WebView 版本过低 | 在 WebView 里打印 UserAgent | 设置minimumWebViewVersion，低于阈值时降级提示 |
| localStorage 写入失败 | 系统 WebView 不支持 | 在 H5 里做特性检测 | 开启domStorageEnabled，降级到 JSBridge 存储 |
| 页面切换卡顿 | 生命周期钩子使用不当 | 在onReady和onShow里打日志 | onReady只做一次性初始化，onShow做数据刷新 |
| 样式错乱 | 组件样式作用域冲突 | 检查是否有同名类名 | 基础组件用scoped，页面组件用命名空间前缀 |
| 图片加载失败 | 资源路径硬编码 | 检查构建后的资源路径 | 用require或import引用资源 |
5.3 上架审核类问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 审核被拒：隐私政策不合规 | 未声明收集的数据类型 | 检查privacy-manifest.json | 补全数据类型和用途说明，更新隐私政策链接 |
| 审核被拒：权限描述模糊 | Info.plist描述文案不具体 | 查看构建生成的Info.plist | 改为具体场景描述，如“用于保存图片到相册” |
| 审核被拒：版本号重复 | versionCode未递增 | 对比已上架版本的versionCode | 用 Git commit 数量生成versionCode，确保递增 |
| 审核被拒：截图不符合要求 | 截图尺寸或内容不合规 | 查看应用市场的截图规范 | 按规范重新截取，确保展示核心功能 |
| 审核被拒：应用图标有圆角 | 图标未按平台规范处理 | 查看应用市场的图标规范 | 提供直角图标，由平台自动裁切圆角 |
5.4 独家避坑技巧：三个文档里不会写的经验
第一个技巧是关于构建日志的。WorkBuddy 的构建日志默认输出到控制台，但如果你在 CI 环境里，控制台日志可能被截断。我建议在构建配置里开启logToFile，把完整日志写到build/logs目录下。这样当构建失败时，你可以下载日志文件慢慢分析，不会因为控制台滚动而丢失关键信息。另外，日志文件按构建时间命名，方便回溯。
第二个技巧是关于渠道配置的。如果你有很多渠道，每个渠道的配置都写一遍会很冗余。WorkBuddy 支持渠道配置继承，你可以在build/channel下建一个base.json，其他渠道配置用extends字段继承它。这样公共配置只写一次，渠道特有的配置单独覆盖。我一般会把统计 SDK 的配置放在base.json里，渠道特有的应用名和图标放在各自的配置文件里。
第三个技巧是关于 WebView 调试的。在开发阶段，你可以在 WorkBuddy 的 WebView 配置里开启debugEnabled，这样在 Chrome 的chrome://inspect里就能看到 WebView 的页面，方便调试 H5。但要注意，这个选项在正式构建里一定要关掉，否则会有安全风险。我一般会在dev环境配置里开启，在prod环境配置里显式关闭。另外，WebView 的缓存策略在开发阶段建议设为no-cache，避免改了 H5 代码但 WebView 还加载旧缓存。
6. 从项目实战中沉淀的工程化思考
6.1 工具链的选择标准：可控性优先于便利性
WorkBuddy 这类工具最大的价值是提升效率，但我在选型时最看重的不是它有多少功能，而是它的行为是否可控。什么叫可控？就是当构建出问题时，我能通过日志和配置定位到原因，而不是只能等工具更新或者求助官方。WorkBuddy 在这方面做得比较好的是，它的构建流程是透明的，每个阶段都有日志输出，配置文件也是纯文本的 JSON，你可以清楚地知道每个配置项的作用。
我建议在引入任何工具链之前，先花时间读一遍它的构建脚本或者核心源码。WorkBuddy 的构建脚本是开源的，你可以看到它怎么解析配置、怎么合并环境变量、怎么调用底层构建工具。了解这些之后，当遇到问题时你就能判断是工具本身的 bug 还是自己的配置问题。我见过很多团队遇到构建问题就重装工具或者升级版本，其实很多时候只是配置写错了。
6.2 团队协作中的配置管理：单一事实来源
两个人以上的团队，配置管理就变得很重要。我的原则是“单一事实来源”，也就是说，同一个配置项只能在一个地方定义，其他地方引用它。WorkBuddy 的配置系统支持变量引用，你可以在workbuddy.config.json里定义全局变量，然后在环境配置和渠道配置里引用。比如 API 地址的域名部分定义在全局变量里，路径部分在各环境配置里定义，这样改域名时只需要改一个地方。
另外，配置文件的修改要跟代码一样走 Code Review。我见过有团队成员直接在 CI 上改配置，结果导致构建行为变化但没人知道。我现在的做法是，所有配置文件都放在 Git 仓库里，修改配置必须提 PR，经过 Review 后才能合并。CI 上的配置只包含环境变量和密钥，不包含业务配置。这样配置的变更历史是可追溯的，出了问题也能快速定位到是哪次修改导致的。
6.3 性能优化的优先级：先测量再优化
性能优化最容易犯的错误是凭感觉优化。我一开始觉得 App 启动慢是因为加载了太多资源，于是花了很多时间做资源懒加载，结果启动时间只减少了不到一百毫秒。后来用 WorkBuddy 的性能分析工具测了一下，发现启动耗时的大头在初始化第三方 SDK 上。调整了 SDK 的初始化时机后，启动时间减少了一半。
WorkBuddy 内置了性能分析功能，可以在构建时开启performanceProfile，它会记录每个阶段的耗时并生成报告。我建议在项目初期就开启这个功能，建立性能基线，后续每次迭代都对比一下，及时发现性能退化。另外，性能优化要分优先级，先优化影响用户感知最大的部分，比如启动速度、页面切换流畅度、网络请求响应时间。不要一上来就抠细节，那样投入产出比很低。
6.4 版本迭代的节奏控制：小步快跑但要有节奏
版本迭代最怕的是“憋大招”，攒了一堆功能一起发，结果出了问题不好定位，回退也麻烦。我现在的做法是，每个版本只做一到两个核心功能，加上必要的 bug 修复。版本周期控制在一到两周，这样即使出了问题，影响范围也有限。WorkBuddy 的版本管理功能支持按功能分支构建测试包，你可以在功能开发完成后先构建一个测试包给内部试用，确认没问题再合并到发布分支。
另外，每个版本发布后要留一段观察期，不要马上开始下一个版本的大改动。观察期内关注崩溃率、用户反馈、性能指标，如果有问题及时发补丁版本。我一般会在版本发布后的三天内每天看一次崩溃日志和用户反馈，一周后做一次总结，把问题记录到下一个版本的改进计划里。这样迭代节奏是可控的，不会因为赶进度而积累技术债务。
6.5 文档沉淀：把踩过的坑变成团队资产
最后一点，也是我觉得最重要的一点：把踩过的坑记录下来。我在这个项目里维护了一个TROUBLESHOOTING.md文件，每次遇到问题并解决后，就把问题现象、排查过程、解决方案写进去。这个文件现在成了团队新成员入职的必读材料，很多常见问题不用再问一遍。WorkBuddy 的构建日志和错误信息也可以附在文档里，方便对照。
文档的格式我建议用“问题现象 → 可能原因 → 排查步骤 → 解决方案 → 预防措施”这个结构。预防措施很重要，它告诉你以后怎么避免同样的问题。比如“构建缓存导致改了没生效”这个问题，预防措施就是“修改配置文件后加--no-cache参数构建一次”。这样下次遇到类似情况，直接看预防措施就能避免踩坑。文档不用写得很正式，关键是实用，能帮到人就行。
这个项目从立项到上架一共用了五周多，比原计划多了一周，多出来的时间基本都花在踩坑和填坑上。但如果让我重新做一遍，有了这些经验，我估计四周就能完成。WorkBuddy 这个工具本身还在迭代，我用的过程中也提了一些 issue，有些已经在新版本里修复了。如果你也在用类似的方式做 App 开发，希望这篇内容能帮你少走一些弯路。后面如果遇到新的问题，我也会继续更新这个文档，毕竟工程化的东西，都是在实践中一点点磨出来的。
