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

很多 Flutter 项目不是难在写页面，而是难在起步。

路由怎么组织，接口怎么封装，状态放哪里，列表页的加载、空态、错误态怎么处理，组件怎么复用，Android、iOS、Web、Windows 怎么一起兼顾，这些问题如果每个项目都从零搭一遍，会浪费不少时间。这个项目就是为了解决这类重复工作：把常见移动应用会用到的基础能力先搭好，让开发者把时间放在业务本身。

它不是一个只有计数器页面的空壳模板，而是一个已经跑过多类真实场景的 Flutter 工程。项目里有路由、网络请求、Redux 状态管理、本地存储、媒体播放、组件库、天气、短视频、音乐、虎扑内容流、认证流程等模块，可以当模板，也可以当参考工程。

1. 解决什么问题

解决 Flutter 项目起步慢的问题

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

- 页面路由怎么统一管理

- 接口请求放在哪里

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

- 全局状态怎么设计

- 页面之间怎么传参

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

- 多端构建版本怎么控制

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

这个项目把这些常见问题先整理好。开发新功能时，不需要再从空项目开始拼路由、网络层和状态层，可以直接按现有目录继续扩展。

解决代码边界混乱的问题

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

这个项目按比较清晰的边界拆分：

- lib/api/ 放接口声明

- lib/model/ 放业务模型

- lib/pages/ 放页面

- lib/components/ 放复用组件

- lib/store/ 放全局状态

- lib/router/ 放路由

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

这种结构让页面更薄，业务含义更清楚，也方便后面维护。

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

Flutter 本身支持多端，但真正落地时，Android Gradle Plugin、Kotlin、Gradle、Flutter SDK、插件版本之间经常互相影响。版本稍微不匹配，就可能遇到编译失败、插件接口不兼容、JDK class file 错误、下载超时等问题。

项目已经记录了当前能跑通的关键版本和构建配置，包括：

- Flutter SDK 版本

- Dart SDK 约束

- Android Gradle Plugin 版本

- Kotlin Gradle Plugin 版本

- Gradle Wrapper 版本

- Android SDK 路径示例

- 国内构建镜像配置

- iOS 真机安装注意事项

这对实际开发很有用，尤其适合 Windows 环境下做 Flutter Android 开发。

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

项目里不只有基础模板，还放了不少接近真实业务的页面：

- 天气页

- 短视频信息流

- 视频播放和播放历史

- 离线缓存

- 收藏管理

- 搜索

- 虎扑内容流

- NBA 赛程和比赛详情

- 音乐播放

- 用户认证流程

- 动态发布

- TodoList 状态流示例

- 俄罗斯方块小游戏

这些页面能直接展示一套完整业务从接口、模型、状态到 UI 的写法，比单独看文档更直观。

2. 特点和功能

路由能力完整

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

支持的能力包括：

- 统一路由表

- 页面跳转

- 转场动画

- 参数传递

- 404 页面

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

开发新页面时，可以直接在现有路由结构里增加入口，不需要重新设计导航方式。

网络请求集中管理

项目使用 dio 做网络请求，并把请求客户端集中放在 lib/utils/request.dart。

已有能力包括：

- 统一 baseUrl

- 请求超时配置

- 公共 headers

- cookie 管理

- token 注入

- 请求日志

- 多业务域名客户端

- 表单请求

- 查询参数拼接

- 错误记录

天气、短视频、虎扑、认证、音乐等接口都通过统一请求层发起，避免在页面里临时创建 Dio()，也避免不同模块各写一套请求逻辑。

状态管理清晰

项目使用 redux 和 flutter_redux 管理全局状态。

已有状态模块包括：

- 用户状态

- TodoList 状态

- 短视频状态

- 音乐播放状态

状态更新通过明确的 action 和 reducer 完成，适合处理跨页面共享数据，比如用户信息、播放状态、列表缓存等。

组件库丰富

项目里有一批可复用组件，并配套演示页面，适合快速搭业务页面。

已有组件包括：

- 按钮

- 弹窗

- Action Sheet

- Toast

- Notice Bar

- 输入框

- 密码输入

- 搜索框

- Picker

- Date Picker

- Calendar

- Checkbox

- Radio

- Switch

- Stepper

- Steps

- Tag

- Tab

- Sidebar

- Dropdown Menu

- Popover

- Swipe

- Swipe Cell

- 图片预览

- 网络图片

- 地区选择

- 文本省略

- 滚动数字

- 视频信息流

- 评论区

- 文章底部操作栏

这些组件偏 iOS 风格，减少 Material 味道，适合做更接近移动端原生体验的 Flutter 应用。

天气模块

天气模块包含城市搜索、实时天气、小时预报、多日预报、空气质量、生活指数、天气预警等内容。