一个能直接开工的 Flutter 项目模板

很多 Flutter 项目难处多半在起步，页面本身反而好写。

路由怎么组织，接口怎么封装，状态放哪里，列表页的加载、空态、错误态怎么处理，组件怎么复用，Android、iOS、Web、Windows 怎么一块兼顾。这些问题每个项目都从零搭一遍，时间全耗在脚手架上。这个项目把常见移动应用会用到的基础能力先搭好，开发者好把时间放在业务本身。

它早就不只是计数器那种空壳。工程里已经跑过不少真场景：路由、网络请求、Redux 状态管理、本地存储、媒体播放、组件库，再加天气、短视频、音乐、虎扑内容流、认证流程。拿来当模板行，当参考工程也行。

1. 解决什么问题

解决 Flutter 项目起步慢的问题

新项目最容易卡在基础架构上。比如：

- 页面路由怎么统一管理

- 接口请求放在哪里

- token、cookie、超时、日志怎么处理

- 全局状态怎么设计

- 页面之间怎么传参

- 本地缓存、偏好设置怎么存

- 多端构建版本怎么控制

- 常用 UI 组件要不要重新写

这些事先整理过。开发新功能时，不必再从空项目拼路由、网络层、状态层，按现有目录往下扩就行。

解决代码边界混乱的问题

Flutter 项目做大以后，页面里经常什么都写：请求、解析、状态更新、UI 渲染、路由跳转搅在一块。短期能跑，后期很难改。

边界拆得比较清楚：

- lib/api/ 放接口声明

- lib/model/ 放业务模型

- lib/pages/ 放页面

- lib/components/ 放复用组件

- lib/store/ 放全局状态

- lib/router/ 放路由

- lib/utils/ 放基础设施、工具

- lib/layouts/ 放应用外壳、主题、Store 注入

- lib/app.config.dart 放域名、开关，dart-define 能覆盖

页面会薄一点，业务含义也清楚些，后面改起来省事。

解决跨端适配、构建踩坑的问题

Flutter 本身能打多端。真正落地时，Android Gradle Plugin、Kotlin、Gradle、Flutter SDK、插件版本经常互相扯。版本稍微不匹配，编译失败、插件接口对不上、JDK class file 报错、下载超时，都见过。

当前能跑通的关键版本已经记在仓库里：

- Flutter SDK 3.41.9 stable

- Dart SDK 约束 >=3.0.5 <4.0.0

- Android Gradle Plugin 8.6.0

- Kotlin Gradle Plugin 2.1.0

- Gradle Wrapper 8.11.1

- Android SDK 路径示例

- 国内构建镜像：腾讯云 Gradle、阿里云 Maven、storage.flutter-io.cn

- iOS 真机：Bundle ID com.oolaf.flutted，显示名 Oolaf，最低 13.0

这些数字别随便升降。Windows 上做 Android，版本对不上就会卡在 Gradle / Kotlin / JDK class file 这类问题上。

iOS CocoaPods 现在关掉 ENABLE_MODULE_VERIFIER。media_kit_libs_ios_video 在真机 Release 里校验模块时找不到 Flutter module，关了这条能绕过去。

解决常用业务场景没有参考的问题

基础模板之外，还放了不少接近真实业务的页面：

- 天气页

- 短视频信息流

- 视频播放、播放历史

- 离线缓存

- 收藏管理

- 搜索

- 虎扑内容流

- NBA 赛程、比赛详情

- 音乐播放

- 用户认证流程

- 动态发布

- TodoList 状态流示例

- 俄罗斯方块小游戏

能直接看到一套完整业务从接口、模型、状态到 UI 的写法，单独啃文档没这么直观。

2. 特点、功能

路由能力完整

项目用 fluro 管路由，首页、业务页、组件演示页、认证页、天气页、短视频页、虎扑页这些入口已经配好。

已有能力：

- 统一路由表

- 页面跳转

- 转场动画

- 参数传递

- 404 页面

- 页面返回值、回调场景示例

新页面往现有路由结构里加入口就行，不必另起一套导航。

网络请求集中管理

网络层用 dio，客户端集中放在 lib/utils/request.dart。

已有能力：

- 统一 baseUrl

- 请求超时配置

- 公共 headers

- cookie 管理

- token 注入

- 请求日志

- 多业务域名客户端

- 表单请求

- 查询参数拼接

- 错误记录

天气、短视频、虎扑、认证、音乐这些接口都走统一请求层。页面里临时 new 一个 Dio()，各模块各写一套，这两种都避开了。

Web 端还能套一层代理。图片 URL、音乐 CDN 主机会绕过，其余请求看 AppConfig.shouldUseProxy。这是给浏览器跨域用的，没再包一套网络库。

状态管理清晰

全局状态用 redux、flutter_redux。

已有状态模块：

- 用户状态

- TodoList 状态

- 短视频状态

- 音乐播放状态

更新走明确的 action、reducer。跨页面共享的数据，用户信息、播放状态、列表缓存这类，适合这么管。

组件库丰富

复用组件一批，演示页也配了，搭业务页能少写不少样板。

已有组件：

- 按钮

- 弹窗

- Action Sheet

- Toast（AppToast，自己画 overlay，没再用 easyloading）

- Notice Bar

- 输入框

- 密码输入

- 搜索框

- Picker

- Date Picker

- Calendar

- Checkbox

- Radio

- Switch

- Stepper

- Steps

- Tag

- Tab

- Sidebar

- Dropdown Menu

- Popover

- Swipe

- Swipe Cell

- 图片预览

- 网络图片

- 地区选择

- 文本省略

- 滚动数字

- 视频信息流

- 评论区

- 文章底部操作栏

视觉偏 iOS，Material 味少一点，做接近移动端原生观感的 Flutter 应用时好用。

天气模块

城市搜索、实时天气、小时预报、多日预报、空气质量、生活指数、天气预警都有。

结构也比较完整：

- 天气接口在 lib/api/weather/

- 天气模型在 lib/model/weather/

- 天气页面在 lib/pages/weather/

- 天气图标组件在 lib/components/weather/

适合拿来看「接口数据到页面渲染」怎么串。

短视频模块

短视频是项目里比较完整的业务场景之一。

已有功能：

- 短视频首页

- 推荐流

- 热点页

- 头条页

- 搜索页

- 搜索结果页

- 视频播放页

- 弹幕覆盖层

- 评论弹层

- 点赞动画

- 播放进度条

- 观看历史

- 收藏列表

- 离线缓存

- 频道管理

- 屏蔽管理

- 图集预览

- 文章详情

- 文章浏览历史

工具层也齐：播放进度、观看历史、搜索历史、离线缓存、频道排序、收藏，各自能落盘。

音乐播放模块

Oolaf 音乐相关能力在工程里：列表、音频播放、缓存、收藏。

已有能力：

- 音频播放器封装

- 播放状态管理

- 音乐缓存

- 收藏管理

- Windows 音频支持

- 播放中状态组件

Flutter 里音频播放、本地缓存、多端播放兼容，这块能对着抄。

请求头 x-oolaf-client-key 从本机读。没存过 key 时，音乐接口不发。

虎扑内容模块

虎扑这块覆盖内容流、搜索、帖子详情、用户详情、话题、NBA 赛程、比赛数据。

首页三个顶栏：关注、推荐、赛事。关注流要登录才看得到；赛事里有主队资讯、NBA、中国篮球、国际足球、中国足球、英雄联盟。

已有功能：

- 虎扑首页

- 关注流

- 赛事 / 体育新闻

- 登录页（/hupu/login）

- 搜索页

- 帖子详情

- 用户详情

- 话题详情

- NBA 赛程

- NBA 比赛详情

- 比分详情

- 热点新闻

- 关注、论坛、榜单等接口封装

更接近真实内容型 App。列表、详情、富文本、媒体块、评论、加载更多，能看见怎么组合。

认证流程完整

账号相关页面覆盖常见流程：

- 启动门禁页

- 登录

- 注册

- 验证码

- 忘记密码

- 重置密码

- 修改密码

- 账号绑定

- 解绑

- 完善资料

- 权限说明

- 验证状态

- MFA

- 会话过期

- 账号安全

- 设备管理

- 注销账号

- 用户协议

- 隐私政策

- 第三方回调

- 异常页

适合直接当账号系统页面骨架。

别把虎扑登录搅进来。/auth 只是静态演示，本地校验一下表单就算完，不接真实账号接口。虎扑关注页的「立即登录」只跳 /hupu/login。

动态、Client API Key

仓库里已经去掉 AppConfig.apheliosClientApiKey 那种写死的值。

进动态列表、新增动态页之前，会先要一把 Client API Key，用 AppField 输入，存本机。动态请求、音乐请求都读本地 x-oolaf-client-key，没存就不发。

Home 页「动态」支持长按，二次确认后清掉这把 key。

AppSheet 加了键盘避让。移动端新增动态外链弹层，键盘弹起来时不再挡表单。

本地存储、缓存能力

本地数据走 shared_preferences、path_provider、flutter_cache_manager 这类。

已有本地能力：

- 用户认证信息保存

- Client API Key 保存

- 短视频观看历史

- 搜索历史

- 播放进度

- 收藏

- 离线缓存

- 屏蔽列表

- 频道排序

- 音乐收藏

- 音乐缓存

多数移动应用常见的轻量本地状态，这些能盖住。

多媒体能力扎实

依赖里有 media_kit、media_kit_video、just_audio、just_audio_windows，视频、音频都能播。

适用场景：

- 短视频播放

- 视频控制器管理

- 播放进度追踪

- 视频缓存

- 音频播放

- Windows 音频播放

- 音乐缓存代理

要做视频流、音乐播放、媒体缓存，这部分值得对着看。

开发工具、错误记录

main.dart 里接了 Flutter 错误、平台错误捕获，记到开发工具中心。

已有处理：

- FlutterError.onError

- PlatformDispatcher.instance.onError

- runZonedGuarded

- 开发工具中心错误记录

运行期问题好查一点，不会只剩控制台一闪而过的异常。

UI 风格偏 iOS

业务 UI 优先用 Cupertino，方向更接近 iOS，默认 Android Material 那套先放一边。

适合这种视觉方向的应用：

- 轻量

- 清爽

- 弹层自然

- 交互接近 iOS

- 组件状态明确

- 页面层次清楚

Flutter 默认 Material 方便，不少国内移动端产品并不希望一眼看成 Android 原生模板。

平台覆盖广

声明支持：

- Android

- iOS

- Web

- Windows

- macOS

- Linux

README 里重点记了 Windows 环境下 Android 模拟器验证，另有 iOS 自用真机安装配置。要多端试一试，这个基础比纯移动端模板弹性大一点。

本地打包用 tool/release_build.ps1，产物丢 dist/releases，文件名是 oolaf flutted <version> <yyyyMMdd HH>。GitHub Actions 还有两套：flutter-web-publish.yml 发 Pages，flutter-release.yml 打 APK、Web zip、Windows zip 并建 Release。CI 里会临时拿掉本机 Gradle 代理、改回官方 Gradle 分发，这些改动不会提交回仓库。