跳转到内容

快速开始

Patchwing 让你即时向 Flutter 应用推送 Dart 代码更新,无需等待应用商店审核。本页带你在一台新电脑上完整走一遍:安装 CLI、注册账号、创建应用、发布基线,然后推送补丁,并看到已安装的应用自动更新。

安装 Git 2.25.1 或更高版本。Android 开发请安装 Android Studio,并在 SDK Manager 中安装 Android SDK Platform 36、SDK Build-Tools、Command-line Tools、Platform-Tools 和 NDK 28.2.13676358;准备一台模拟器或开启 USB 调试的手机。环境细节可参考 Flutter 官方 Android 指南。

工程模板使用 Gradle 9.1.0 和 AGP 9.0.1,构建 JVM 需为 Java 17 或更高版本,使用 Android Studio 自带的 JDK 即可。

日常编辑与调试需要安装公开 Flutter SDK,按 官方指南 安装并把 bin 目录加入 PATH,然后检查 Android 工具链:

flutter doctor --android-licensesflutter doctor -v

Windows 上使用 Windows 11 x64 和 PowerShell 5.1 或更高版本(无需 WSL)。在管理员 PowerShell 中执行一次以下命令并确认输出 true,然后关闭该窗口,后续均以普通用户操作。构建 Android 不需要安装 Visual Studio C++ 桌面工具链。

git config --system core.longpaths trueif ($LASTEXITCODE -ne 0) { throw 'Git configuration failed' }git config --get core.longpaths

构建 iOS 需要 Apple Silicon Mac:安装完整 Xcode 及 iOS 平台组件,准备有效的签名团队和描述文件,在 iPhone 上打开开发者模式并信任电脑,插件需要时安装 CocoaPods。参考 Flutter 官方 iOS 指南。

打开 控制台注册页,用邮箱验证码完成注册并设置密码。之后用邮箱和密码登录控制台;忘记密码时用邮箱验证码重置。注册过程不需要任何组织设置。

curl --proto '=https' --tlsv1.2 -sSf https://patchwing.net/install.sh -o patchwing-install.shbash patchwing-install.sh

安装完成后关闭并重新打开终端,让新的 PATH 生效,然后验证安装并登录:

pw --versionpw doctorpw login

pw login 会打开浏览器授权页:用注册邮箱和验证码确认登录,并允许本机 localhost 回调。pw doctor 会检查 Android 工具链和 Patchwing 项目配置,按它的提示补齐缺失项即可。

pw create my_appcd my_app

在一个可写的工作目录中执行(Windows 上例如 C:\pw-projects)。它会创建 Flutter 应用并初始化 Patchwing:patchwing.yaml 中的 app_id 对应控制台里的这个应用。已有 Flutter 工程在根目录执行 pw init 即可接入。

跟随本页示例时,把 pubspec.yaml 的 version 设为 1.0.0+1,保留生成的计数器应用,把 lib/main.dart 中首页标题改为 BASE。用 Git 提交源码和 pubspec.lock,然后在工程里执行 pw doctor,按提示处理(例如 INTERNET 权限)。

pw release --platforms=androidpw releases get-apks --release-version=1.0.0+1 --out=apks

Release 登记用户安装的基线版本。Android 默认产出 AAB,get-apks 会基于它生成可安装的 APK。启动模拟器或连接手机,确认设备已识别后安装:

adb devicesadb install apks/universal.apk

连接了多台设备时,用 adb -s 指定设备 ID。找不到 adb 时,把 Android SDK 的 Platform-Tools 目录加入 PATH。

iOS 在发布前先用 Xcode 打开 ios/Runner.xcworkspace,设置 Runner 的签名团队和唯一的 Bundle Identifier,再通过 Xcode 的 Devices and Simulators 安装 pw release 输出的签名 IPA。

打开安装好的应用:标题显示 BASE,点击 + 计数加 1。之后正式上架商店时,配置自己的发布签名,并提交 pw release 产出的制品。

保持版本号 1.0.0+1 不变。在 lib/main.dart 中把标题 BASE 改为 PATCHED,把 _counter++ 改为 _counter += 3,同步修改生成的 widget 测试为点击一次后期望 3,提交代码后向 stable 通道发布补丁:

pw patch --platforms=android --release-version=1.0.0+1 --track=stable

在自己的应用里,请传入实际登记过的 release version,并保持与基线相同的 flavor、入口和 dart-define。Dart 文件、函数和顶层变量可以自由增改;原生代码、插件原生实现或打包资源的变更需要发布新的基线版本。

让已安装的应用保持联网:它会自动检查并后台下载补丁。下载完成的补丁在下一次完整启动时生效,不会热替换正在运行的会话。如果刚打开时才开始下载,稍等片刻后完整关闭应用再重新打开即可。

重新打开应用:标题变为 PATCHED,点击 + 计数加 3,应用的版本号和签名保持不变。要撤销某个补丁,在 控制台 中打开对应应用和版本执行回滚;已安装的应用冷启动后收到回滚,恢复显示 BASE、计数加 1。

某一步失败时,停留在该步骤阅读命令输出:网络类错误直接重试即可;持续失败时把完整输出发到 contact@patchwing.net。日常发布操作参考 发布版本 与 补丁 文档。