一个基于 Flutter 开发的视频播放应用,支持 HLS 流媒体播放、清晰度切换、全屏播放、评论、弹幕、投稿等功能。

• 项目名称: 喵聚 (miaoju)
• 版本: v1.1.0
• Flutter SDK: 3.9.2+
• 开发语言: Dart
• 总代码行数: 约 8,000+ 行

• 🏠 首页（视频/专栏双模式）
  • 视频列表展示（封面、标题、作者、播放数、时长等）
  • 专栏文章列表展示
  • 分区（分类）筛选
  • 轮播图展示
  • 搜索功能
  • 分页加载（滚动到底部自动加载更多）
• � 底部导航栏（首页、我的）
• 🔐 用户登录/注册
  • 账号密码登录
  • 邮箱验证码注册
  • 图形验证码支持
  • Token 自动刷新机制
  • 找回密码功能
• 🎥 视频播放页面
  • 视频播放器（HLS 流媒体、多清晰度切换）
  • 作者信息卡片（头像、名字、粉丝数、关注按钮）
  • 视频信息展示（标题、播放量、弹幕数、上传时间、在线人数）
  • 三大操作按钮（点赞、收藏、分享）
  • 分集列表支持（列表/网格视图切换、自动连播）
  • 视频推荐区域（相关推荐、自动连播）
  • 播放进度记忆与上报
  • 响应式布局（宽屏左右两栏，窄屏单栏）
  • 后台播放支持
• 💬 评论系统
  • 评论列表展示（支持分页加载）
  • 发送评论/回复评论
  • 二级评论（楼中楼）
  • 评论点赞
  • 评论时间戳跳转（点击时间戳跳转到视频对应位置）
  • 表情包选择器（支持深色/浅色主题）
  • 评论预览卡片（YouTube 风格）
  • 评论管理（删除、置顶等）
• 🎯 弹幕功能
  • 实时弹幕显示
  • 弹幕发送
  • 弹幕开关控制
• 📤 视频投稿
  • 视频上传（分片上传、断点续传、秒传）
  • 封面上传
  • 多分P支持
  • Token 自动刷新
• 📝 专栏投稿
  • 文章编辑器
  • 封面上传
  • 文章发布
• 📚 收藏功能
  • 收藏夹管理
  • 创建收藏夹
  • 添加视频到收藏夹
• 💬 消息系统
  • 消息中心
  • 私信功能
  • @消息
  • 点赞消息
  • 回复消息
  • 系统公告
• 👤 个人中心
  • 用户信息展示
  • 用户空间页面
  • 关注/粉丝列表
  • 播放历史
  • 创作中心
• 🎨 主题系统
  • 深色/浅色主题切换
  • 主题持久化存储
• ⚙️ 设置页面
  • 版本信息显示
  • 缓存管理
  • 退出即清功能
  • 退出登录

• 动态功能
• 更多设置选项

• ✅ HLS (M3U8) 流媒体播放
• ✅ 多清晰度切换(360P/480P/720P/1080P/4K 等)
• ✅ 友好的清晰度名称显示
• ✅ 播放进度保存和恢复
• ✅ 播放历史记录同步
• ✅ 后台播放支持
• ✅ 音频会话管理（电话打断等）

• ✅ 全屏/非全屏模式切换
• ✅ 横竖屏自动适配
• ✅ 手势控制(亮度、音量、进度)
• ✅ 双击暂停/播放
• ✅ 播放速度调节
• ✅ 画质自适应
• ✅ 自定义播放器 UI
• ✅ 屏幕常亮控制

• ✅ Material Design 3 设计
• ✅ 自定义播放器控制栏
• ✅ 视频信息卡片展示
• ✅ 作者信息展示
• ✅ 分P选集列表
• ✅ 推荐视频列表
• ✅ 视频操作按钮(点赞、收藏、分享等)
• ✅ 深色/浅色主题切换
• ✅ 主题持久化存储
• ✅ 响应式布局

• UI 框架: Flutter 3.9.2+
• 视频播放: media_kit (基于 AndroidX Media3)
  • media_kit: ^1.1.10 - 核心播放器
  • media_kit_video: 1.2.2 - 视频 UI 组件
  • media_kit_libs_video: ^1.0.4 - 原生 libmpv 库
• 网络请求:
  • http: ^1.2.0 - HTTP 客户端
  • dio: ^5.4.0 - 高级网络库（带重试机制）
• 图片缓存: cached_network_image: ^3.3.1 - 网络图片缓存
• 本地存储:
  • shared_preferences: ^2.2.0 - 轻量级键值存储
  • path_provider: ^2.1.1 - 路径获取
• 分享功能: share_plus: ^7.2.0
• 国际化: intl: ^0.20.2
• 后台播放: audio_service: ^0.18.12
• 音频会话管理: audio_session: ^0.1.21
• 系统控制: screen_brightness: ^0.2.2+1, volume_controller: ^2.0.7
• 网络状态监听: connectivity_plus: ^6.0.0
• 文件加密: crypto: ^3.0.3
• 文件路径处理: path: ^1.9.0
• 文件选择: file_picker: ^8.1.6
• 二维码生成: qr_flutter: ^4.1.0
• 表情包选择器: emoji_picker_flutter: ^3.0.0
• 图片选择: image_picker: ^1.0.7
• UUID 生成: uuid: ^4.2.0
• 包信息: package_info_plus: ^4.0.0
• URL 启动: url_launcher: ^6.1.0
• 屏幕常亮: wakelock_plus: ^1.1.6

lib/
├── main.dart                      # 应用入口
├── config/                        # 配置
│   └── api_config.dart           # API 配置
├── models/                        # 数据模型
│   ├── api_response.dart         # API 响应封装
│   ├── video_api_model.dart      # 视频 API 模型
│   ├── video_detail.dart         # 视频详情模型
│   ├── video_item.dart           # 视频列表项模型
│   ├── user_model.dart           # 用户模型
│   ├── comment.dart              # 评论模型
│   ├── danmaku.dart              # 弹幕模型
│   ├── article_list_model.dart   # 专栏模型
│   ├── collection_models.dart    # 收藏模型
│   ├── message_models.dart       # 消息模型
│   ├── auth_models.dart          # 认证模型
│   ├── captcha_models.dart       # 验证码模型
│   ├── partition.dart            # 分区模型
│   ├── upload_video.dart         # 视频上传模型
│   ├── upload_article.dart       # 文章上传模型
│   ├── carousel_model.dart       # 轮播图模型
│   ├── history_models.dart       # 历史记录模型
│   ├── comment_manage.dart       # 评论管理模型
│   └── loop_mode.dart            # 循环模式模型
├── pages/                         # 页面
│   ├── main_page.dart            # 主页面(底部导航)
│   ├── home_page.dart            # 首页(视频/专栏列表)
│   ├── profile_page.dart         # 个人中心
│   ├── settings_page.dart        # 设置页面
│   ├── search_page.dart          # 搜索页面
│   ├── login_page.dart           # 登录页面
│   ├── register_page.dart       # 注册页面
│   ├── reset_password_page.dart  # 重置密码页面
│   ├── edit_profile_page.dart    # 编辑资料页面
│   ├── history_page.dart         # 播放历史页面
│   ├── article/                  # 专栏相关
│   │   └── article_detail_page.dart  # 专栏详情页
│   ├── video/                    # 视频播放相关
│   │   ├── video_play_page.dart  # 视频播放页面
│   │   └── widgets/              # 视频页面组件
│   │       ├── media_player_widget.dart    # 视频播放器组件
│   │       ├── custom_player_ui.dart       # 自定义播放器UI
│   │       ├── author_card.dart           # 作者信息卡片
│   │       ├── part_list.dart             # 分P列表
│   │       ├── recommend_list.dart        # 推荐列表
│   │       ├── video_action_buttons.dart  # 视频操作按钮
│   │       ├── video_info_card.dart       # 视频信息卡片
│   │       ├── comment_list.dart          # 评论列表
│   │       └── comment_preview_card.dart  # 评论预览卡片
│   ├── upload/                   # 投稿相关
│   │   ├── video_upload_page.dart       # 视频上传页面
│   │   ├── video_manuscript_page.dart    # 视频稿件管理页面
│   │   ├── article_upload_page.dart      # 文章上传页面
│   │   ├── article_manuscript_page.dart  # 文章稿件管理页面
│   │   └── widgets/
│   │       └── video_resource_list.dart  # 视频资源列表
│   ├── message/                  # 消息相关
│   │   ├── message_center_page.dart      # 消息中心
│   │   ├── whisper_page.dart             # 私信页面
│   │   ├── whisper_detail_page.dart      # 私信详情页
│   │   ├── at_message_page.dart          # @消息页面
│   │   ├── like_message_page.dart        # 点赞消息页面
│   │   ├── reply_message_page.dart       # 回复消息页面
│   │   └── announce_page.dart            # 系统公告页面
│   ├── collection/               # 收藏相关
│   │   ├── collection_list_page.dart      # 收藏夹列表
│   │   └── collection_detail_page.dart   # 收藏夹详情
│   ├── creator/                  # 创作中心
│   │   ├── creator_center_page.dart      # 创作中心
│   │   ├── video_manage_page.dart        # 视频管理
│   │   └── comment_manage_page.dart      # 评论管理
│   └── user/                     # 用户相关
│       └── user_space_page.dart         # 用户空间页面
├── services/                      # 业务服务
│   ├── hls_service.dart          # HLS 流处理服务
│   ├── logger_service.dart       # 日志服务
│   ├── video_api_service.dart    # 视频 API 服务
│   ├── video_service.dart        # 视频业务服务
│   ├── video_submit_api_service.dart  # 视频投稿服务
│   ├── article_api_service.dart # 专栏 API 服务
│   ├── article_submit_api_service.dart # 专栏投稿服务
│   ├── auth_service.dart         # 认证服务
│   ├── user_service.dart         # 用户服务
│   ├── comment_manage_service.dart # 评论管理服务
│   ├── danmaku_service.dart      # 弹幕服务
│   ├── collection_service.dart   # 收藏服务
│   ├── collection_api_service.dart # 收藏 API 服务
│   ├── message_api_service.dart  # 消息 API 服务
│   ├── upload_api_service.dart   # 上传服务
│   ├── captcha_service.dart     # 验证码服务
│   ├── partition_api_service.dart # 分区服务
│   ├── resource_api_service.dart # 资源服务
│   ├── review_api_service.dart   # 审核服务
│   ├── history_service.dart      # 历史记录服务
│   ├── theme_service.dart        # 主题服务
│   ├── version_service.dart      # 版本服务
│   └── carousel_service.dart     # 轮播图服务
├── controllers/                   # 控制器
│   ├── video_player_controller.dart  # 视频播放器控制器
│   └── danmaku_controller.dart       # 弹幕控制器
├── managers/                      # 管理器
│   └── video_player_manager.dart     # 视频播放器管理器
├── theme/                         # 主题
│   ├── app_theme.dart            # 应用主题
│   ├── app_colors.dart           # 主题颜色
│   └── theme_extensions.dart     # 主题扩展
├── utils/                         # 工具类
│   ├── http_client.dart          # HTTP 客户端封装
│   ├── image_utils.dart          # 图片工具类
│   ├── token_manager.dart        # Token 管理器
│   ├── quality_utils.dart        # 清晰度工具类
│   ├── login_guard.dart          # 登录守卫
│   ├── auth_state_manager.dart   # 认证状态管理器
│   ├── wakelock_manager.dart     # 屏幕常亮管理器
│   ├── timestamp_parser.dart     # 时间戳解析器
│   ├── time_utils.dart           # 时间工具类
│   ├── redirect_http_service.dart # 重定向 HTTP 服务
│   ├── error_handler.dart        # 错误处理器
│   └── whisper_read_status.dart  # 私信阅读状态
├── widgets/                       # 通用组件
│   ├── video_card.dart           # 视频卡片组件
│   ├── cached_image_widget.dart  # 缓存图片组件
│   ├── danmaku_overlay.dart      # 弹幕覆盖层
│   ├── danmaku_input.dart        # 弹幕输入框
│   ├── collection_dialog.dart   # 收藏对话框
│   ├── carousel_widget.dart      # 轮播图组件
│   └── slider_captcha_widget.dart # 滑块验证码组件
└── generated/                     # 生成文件
    └── version_info.dart         # 版本信息

位置: lib/pages/video/widgets/media_player_widget.dart

核心功能:

• HLS 流处理: 自动下载并解析 M3U8 文件,转换为本地可访问的播放地址
• 清晰度切换: 支持多种清晰度无缝切换,保持播放进度
• 全屏管理: 自动处理横竖屏切换和系统 UI 显示/隐藏
• 播放状态管理: 完整的播放器生命周期管理(初始化、播放、暂停、销毁)
• 进度同步: 定期向服务器同步播放进度

关键配置:

MaterialVideoControlsTheme(
  seekBarMargin: EdgeInsets.only(bottom: 44),        // 进度条位置
  bottomButtonBarMargin: EdgeInsets.only(bottom: 0), // 控制按钮位置
  displaySeekBar: true,                              // 显示进度条
  automaticallyImplySkipNextButton: false,           // 隐藏下一集按钮
  automaticallyImplySkipPreviousButton: false,       // 隐藏上一集按钮
)

位置: lib/services/hls_service.dart

功能:

• 下载 M3U8 文件并解析
• 转换相对路径为绝对 URL
• 缓存处理的 M3U8 文件到本地
• 提供本地文件路径供播放器使用

位置: lib/services/video_service.dart

功能:

• 获取视频详情信息
• 获取视频资源和清晰度列表（指的是播放器）
• 播放进度管理（指的是播放器）
• 历史记录管理（指的是播放器）

• Flutter SDK: 3.35.7
• Dart SDK: 3.9.2
• Android:
  • minSdk: 21
  • targetSdk: 34
  • Java: 11+
  • Kotlin: 1.9.0+

flutter run -d <device_id>

flutter build apk --release --split-per-abi

生成的 APK 文件:

• app-armeabi-v7a-release.apk (25.7MB) - 32位 ARM 设备
• app-arm64-v8a-release.apk (28.9MB) - 64位 ARM 设备(推荐)
• app-x86_64-release.apk (33.3MB) - x86_64 设备/模拟器

flutter build apk --release

# 禁用 Kotlin 增量编译(解决跨盘符路径问题)
kotlin.incremental=false
kotlin.incremental.java=false
kotlin.caching.enabled=false
org.gradle.caching=false

# JVM 内存配置
org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=1G -XX:+HeapDumpOnOutOfMemoryError

# AndroidX 支持
android.useAndroidX=true
android.enableJetifier=true

⚠️ 注意: 如果项目和 Flutter SDK/Pub Cache 在不同盘符,必须禁用 Kotlin 增量编译,否则会出现编译错误。

后端 API 地址: https://miaoju.hydun.com

主要接口:

• GET /api/v1/video/getHotVideo - 获取热门视频列表
• GET /api/v1/video/getVideoById - 获取视频详情
• GET /api/v1/video/getResourceQuality - 获取视频清晰度列表
• GET /api/v1/video/getVideoFile - 获取视频播放地址
• GET /api/v1/video/getRelatedVideoList - 获取相关推荐
• POST /api/v1/history/video/addHistory - 添加播放历史
• GET /api/v1/history/video/getProgress - 获取播放进度
• GET /api/v1/partition/list - 获取分区列表
• GET /api/v1/article/list - 获取专栏列表
• GET /api/v1/article/detail - 获取专栏详情
• POST /api/v1/auth/login - 用户登录
• POST /api/v1/auth/register - 用户注册
• POST /api/v1/auth/sendCode - 发送验证码
• GET /api/v1/user/info - 获取用户信息
• POST /api/v1/comment/send - 发送评论
• GET /api/v1/comment/list - 获取评论列表
• POST /api/v1/danmaku/send - 发送弹幕
• GET /api/v1/danmaku/list - 获取弹幕列表
• POST /api/v1/upload/video - 上传视频
• POST /api/v1/upload/article - 发布专栏
• GET /api/v1/collection/list - 获取收藏夹列表
• POST /api/v1/collection/add - 添加收藏
• GET /api/v1/message/list - 获取消息列表
• GET /api/v1/message/whisper - 获取私信列表

问题: 跨盘符(C: 和 E:)编译时出现 IllegalArgumentException: this and base files have different roots

解决方案: 在 android/gradle.properties 中禁用 Kotlin 增量编译

问题: 运行时报错 Cannot find libmpv.so

解决方案: 确保 media_kit_libs_video 依赖已正确添加到 pubspec.yaml

问题: 切换全屏后画面不显示

解决方案: 已通过正确配置 SystemChrome 和 Widget 生命周期管理解决

问题: 网络不稳定时视频加载失败或图片加载缓慢

解决方案: 已实施网络优化，详见 NETWORK_OPTIMIZATION.md

• ✅ HTTP 请求自动重试机制（最多3次）
• ✅ 超时时间优化（15s 连接，30s 接收）
• ✅ 图片智能缓存（内存+磁盘双层缓存）
• ✅ HLS 分片下载自动重试

• media_kit: AndroidX Media3 的 Flutter 封装,提供强大的视频播放能力
  • 支持 HLS、MP4、WebM 等多种格式
  • 内置缓冲管理和自适应码率
  • 原生性能优化

以下组件已使用 media_kit 原生控件替代:

• ❌ 旧播放器状态管理
• ❌ 旧手势检测
• ❌ 旧顶部控制栏
• ❌ 旧底部控制栏
• ❌ 旧进度条

项目使用 logger_service.dart 提供统一的日志输出:

LoggerService.debug('日志消息');
LoggerService.error('错误消息', error: e, stackTrace: st);

日志输出格式:

• 🔍 DEBUG - 调试信息
• ⚠️ WARNING - 警告信息
• ❌ ERROR - 错误信息
• 📹 - 视频播放相关日志

1. 在 VideoService 中添加新的 API 调用
2. 更新 VideoDetailModel 以支持新字段
3. 修改 HlsService 以处理不同的流格式(如需要)
4. 更新 UI 组件以展示新数据

修改 media_player_widget.dart 中的 MaterialVideoControlsTheme:

MaterialVideoControlsTheme(
  seekBarMargin: EdgeInsets.only(bottom: 44),  // 调整进度条位置
  bottomButtonBarMargin: EdgeInsets.only(bottom: 0),  // 调整按钮位置
  seekBarColor: Colors.blue,  // 进度条颜色
  // ... 更多配置项
)

• ✅ 添加 ColorScheme 兼容属性到主题颜色类
• ✅ 更新项目版本信息
• ✅ 添加版本号注入脚本
• ✅ 优化 Android SDK 和 NDK 版本
• ✅ 更新应用图标配置

• ✅ 投稿功能 Token 刷新统一（使用 TokenManager）
• ✅ 修复评论区表情包 emoji_picker_flutter 3.x API 兼容问题
• ✅ 表情选择器深色/浅色主题适配
• ✅ 回复二级评论自动添加 @用户名 前缀
• ✅ 发送评论后自动关闭表情面板
• ✅ 评论预览卡片深色模式适配
• ✅ 修复合集（分P）自动连播功能
• ✅ 修复推荐列表自动连播功能
• ✅ 修复后台播放卡顿问题
• ✅ 修复音量调节从当前系统音量开始的问题

• ✅ 初始版本发布
• ✅ 实现基础视频播放功能
• ✅ 支持 HLS 流媒体播放
• ✅ 清晰度切换功能
• ✅ 全屏播放支持
• ✅ 播放历史和进度同步
• ✅ 解决 Kotlin 编译跨盘符问题
• ✅ 优化播放器控件位置
• ✅ 添加主题系统
• ✅ 添加用户登录/注册功能
• ✅ 添加评论系统
• ✅ 添加弹幕功能
• ✅ 添加视频投稿功能
• ✅ 添加收藏功能
• ✅ 添加消息系统

• Flutter 官方文档
• media_kit GitHub
• Material Design 3

本项目仅供学习交流使用。

• 开发者: acgkiss, SDCOM, smallcat

---

最后更新: 2026-02-05