flutter-pos-system本地开发环境搭建:5步完成Flutter POS系统编译与运行
flutter-pos-system本地开发环境搭建:5步完成Flutter POS系统编译与运行
flutter-pos-system 是一款面向小型餐厅和商家的开源 Flutter POS 系统,支持点单、库存管理、收银、数据分析与蓝牙打印小票。本文带你完成 flutter-pos-system 本地开发环境搭建:从安装 Flutter SDK 到编译运行,只需 5 步即可在本地跑起这个 POS 应用,并教你如何用 Makefile 一键执行测试。
1️⃣ 准备 Flutter SDK 与 Android 开发环境
本项目对工具链版本有明确要求,搭建前先确认环境:
| 工具 | 版本要求 | 说明 |
|---|---|---|
| Flutter | 3.41.x(stable) | 见 pubspec.yaml 的 environment 配置 |
| Java | 17(如 Zulu JDK 17) | 用于 Gradle 构建 |
| Android SDK | Android 平台工具 + 模拟器或真机 | 用于运行 Android 应用 |
| Android Studio | 可选 | 图形化调试更方便 |
安装完成后,执行以下命令确认版本符合预期:
flutter --version
java -version
💡 项目的 CI 也锁定在 Flutter 3.41.x,参考 .github/workflows/test.yaml 中的
flutter-version配置。
2️⃣ 克隆 flutter-pos-system 仓库
将仓库克隆到本地工作目录:
git clone https://gitcode.com/gh_mirrors/fl/flutter-pos-system
cd flutter-pos-system
仓库结构清晰:lib/ 是主逻辑,test/ 是对应测试,android/ 与 ios/ 是平台工程,详细说明可参考 docs/about/structure.zh.md。
3️⃣ 将私有依赖包替换为 mock 版本
这是本项目开发最关键的一步。由于隐私原因,pubspec.yaml 中引用了私有工具包 flutter-pos-packages,公开环境下无法直接拉取。官方要求先替换成模拟工具 flutter-pos-packages-mock:
sed -i.bk 's/flutter-pos-packages$/flutter-pos-packages-mock/' pubspec.yaml
rm -f pubspec.yaml.bk
这条 sed 命令会精确定位 pubspec.yaml 中以 flutter-pos-packages 结尾的包名声明并追加 -mock 后缀,随后清理临时备份文件 .bk。完整流程记录在 docs/maintenance/development.zh.md。
4️⃣ 安装依赖:flutter pub get
依赖替换完成后,执行:
flutter pub get
该命令会解析 pubspec.yaml 中的全部依赖(包括 go_router、provider、sqflite、firebase_* 系列等核心包)并写入本地缓存。看到 Got dependencies! 即表示成功。
若后续修改了国际化文案,可执行 Makefile 中的 make build-l10n 重新生成 l10n.yaml 配置的语言文件。
5️⃣ 编译运行:flutter run
方式一:快速调试(推荐新手)
仓库内已内置 androidDebug 的 Firebase 配置(见 lib/firebase_compatible_options.dart),直接运行即可:
flutter run
方式二:构建正式签名应用(可选)
若你要打包 release 版本,还需按 docs/maintenance/development.zh.md 准备三样东西:
- 签名密钥:用
keytool在android/app/下生成.jks密钥库(别名possystem,RSA 2048); - 密钥配置:创建
android/key.properties,写入keyAlias、keyPassword、storeFile、storePassword四项; - Firebase 配置:在 Firebase 控制台下载
google-services.json放入android/app/,并把密钥的 SHA-256 指纹填回控制台,最后将配置同步到 lib/firebase_compatible_options.dart。
构建配置由 android/settings.gradle 与 android/gradle.properties 驱动(Gradle 堆内存已预设为 4G)。
🧪 附加:运行测试与代码检查
项目通过 Makefile 提供了一键命令,方便本地验证:
# 代码格式(行宽 120)
make format
# 静态检查
make lint
# 运行全部测试
make test
# 测试 + 生成覆盖率报告
make test-coverage
测试用例与源码同构,位于 test/ 目录,覆盖 models/、services/、UI 组件等模块。
❓ 常见问题
Q:flutter pub get 提示找不到 flutter-pos-packages 包?
确认你已完成第 3 步的 sed 替换,且包名结尾正确追加了 -mock。
Q:版本冲突或依赖解析失败?
先 flutter --version 核对是否为 3.41.x;必要时执行 flutter clean && flutter pub get 清理重建。
Q:运行时需要登录 Google 账号吗?
调试版使用内置的 flutter-pos-system-debug 项目配置,一般可直接运行体验核心功能。
Q:想跟进部署流程?
项目使用 Fastlane 划分 internal / beta / promote_to_production 三条发布通道,详见 docs/maintenance/deployment.zh.md。
至此,你已完成 flutter-pos-system 的本地开发环境搭建。祝开发顺利,也欢迎查阅 docs/about/contribute.zh.md 了解如何贡献代码!


