HE Music Flutter

一个基于 Flutter 的音乐应用项目，延续桌面端 HE-Music 的产品方向，并针对移动端与桌面端场景做适配。

项目当前以功能迭代为主，欢迎通过 PR 一起完善功能、体验与文档。

项目简介

HE Music Flutter 以 feature-first 方式组织代码，围绕播放器、在线内容浏览、本地音乐、下载管理、登录与个人中心等能力持续演进。当前仓库已经具备完整的应用骨架、核心业务模块与常用开发命令，适合作为持续开发中的 Flutter 音乐应用工程使用。

功能概览

• 首页发现与我的页双入口，适配移动端底部导航和桌面端侧边导航
• 内置播放器，包含迷你播放器、全屏播放器、播放队列、播放进度与播放模式管理
• 支持歌词展示，包含播放器内歌词面板与桌面悬浮歌词能力
• 支持本地音乐扫描与管理，可读取本地音频元数据
• 支持歌曲下载、下载任务管理，以及下载后元数据与歌词写入
• 支持登录与验证码流程，包含二维码扫码登录相关页面
• 支持在线能力聚合，包括搜索、热搜/联想、评论等页面
• 支持歌单广场、歌单详情、歌曲详情、专辑详情、歌手详情
• 支持排行榜、新歌、新碟、视频、电台等内容浏览
• 支持“我的”相关能力，包括收藏、历史记录、个人歌单详情
• 支持设置页与关于页，并内置 GitHub Release 更新检查

目录结构

lib/
  app/       应用启动、路由、主题、配置
  core/      音频、网络、错误处理等基础设施
  features/  按业务功能划分的模块
  shared/    复用组件、辅助方法、模型与工具
test/        测试代码
assets/      静态资源
third_party/ 本地覆盖依赖

常用命令

项目根目录提供了 Makefile，日常开发优先使用以下命令：

make get            安装或同步依赖
make upgrade        升级依赖
make run            启动应用
make analyze        执行静态检查
make test           运行测试
make format         格式化 Dart 代码
make fix            自动应用 Dart 可修复项
make gen            执行代码生成
make clean          清理构建产物
make build-apk      构建 Android release APK（按 ABI 拆分）
make build-aab      构建 Android release AAB
make release-check  发布前执行检查与测试

开发说明

• 代码主要位于 lib/，按 app、core、features、shared 分层组织
• 测试位于 test/，建议与源码路径保持对应
• 本地覆盖依赖位于 third_party/，按 vendored code 对待
• 涉及 Retrofit 或 JSON 模型变更时，通常需要执行 make gen
• 提交前建议至少执行 make analyze 与 make test

更多仓库约定可参考项目内 AGENTS.md 与 Makefile。

鸣谢

• 感谢原始桌面端项目 HE-Music，本仓库的产品方向与部分能力设计基于该项目延续
• 感谢 Flutter 及其生态，为本项目提供跨平台应用基础
• 感谢 flutter_riverpod，用于状态管理与依赖注入
• 感谢 go_router，用于页面路由与导航组织
• 感谢 dio、retrofit、json_annotation，用于网络请求封装与数据模型序列化
• 感谢 just_audio 与 audio_service，为播放器、后台播放和播放控制能力提供基础支持
• 感谢 background_downloader，用于下载任务调度与下载管理
• 感谢 flutter_lyric，用于歌词展示；项目当前通过本地覆盖依赖 third_party/flutter_lyric/ 集成
• 感谢 local_audio_scan 与 audiotags，用于本地音乐扫描与音频元数据读取；其中 audiotags 当前通过 third_party/audiotags/ 本地覆盖依赖集成
• 感谢 video_player，用于视频内容播放能力
• 感谢 mobile_scanner 与 qr_flutter，用于二维码扫描与展示，支撑扫码登录流程
• 感谢 cached_network_image、palette_generator、flutter_svg、marquee 与 mesh_gradient，用于封面加载、配色提取、SVG 渲染、滚动文本与界面视觉表现
• 感谢 permission_handler、path_provider、shared_preferences、package_info_plus、url_launcher、share_plus、screen_brightness、volume_controller、saver_gallery 与 gocaptcha，为权限、存储、配置、分享、系统交互与验证码能力提供支持
• 感谢 flutter_overlay_window，用于悬浮歌词窗口能力；当前使用的是带通信修复的 Git 版本依赖