MediaHub

本地媒体与游戏分类管理工具。Electron + Vue 3 桌面端，用于把散落在磁盘上的视频与游戏整理成可浏览、可分类、可播放的库。

功能

视频库

• 添加多个媒体根目录，递归扫描并入库
• 自动生成缩略图（图片走 sharp，视频走 ffmpeg-static）
• 按分类、集合（collection）组织，支持卡片拖拽归类
• 播放列表，本地视频通过自定义协议在内置播放器中播放
• 也可以交给系统默认播放器或其他外部播放器打开

游戏库

• 独立扫描游戏目录并入库
• 自动匹配游戏封面
• 游戏分类与视频分类分开维护

通用

• 文件夹树视图，按目录层级浏览
• 媒体卡片带懒加载缩略图、长按拖拽
• 应用内更新检查

技术栈

层	选型
桌面壳	Electron 44
构建	electron-vite 5 + Vite 7
前端	Vue 3.5 + Vue Router 4 + Pinia 3
语言	TypeScript 5.9（主进程 tsc，渲染层 vue-tsc）
媒体处理	sharp（图片）、ffmpeg-static（视频）
打包	electron-builder 26（portable + NSIS）

目录结构

src/
  main/                 主进程
    db/                 数据持久化
    ipc/                IPC 入口
    services/           业务服务
      scanner.ts        媒体扫描
      thumbnail.ts      缩略图生成
      mediaProtocol.ts  本地媒体自定义协议
      externalPlayer.ts 外部播放器拉起
      collections.ts    集合/分类收纳
      gameScanner.ts    游戏扫描
      gameCover.ts      游戏封面
      updater.ts        更新检查
    util/               分类、日志、路径、路径安全
    smoke.ts            冒烟自检入口
  preload/              预加载桥接
  renderer/             前端（Vue 3）
    src/components/     媒体卡片、集合卡片、分类标签、文件夹树、播放列表
    src/views/          浏览 / 文件夹 / 游戏 / 根目录 / 设置
    src/stores/         分类、集合、游戏、库、播放列表、扫描、设置等状态
    src/composables/    懒加载缩略图、长按拖拽
    src/utils/          格式化、列表动画
  shared/types.ts       主进程与渲染层共用的类型
scripts/
  copy-local.mjs        打包后复制到本地发布位置
  publish-update.mjs    生成并发布更新包

开发

npm install

npm run dev          # 开发模式（electron-vite dev）
npm run typecheck    # 类型检查（主进程 + 渲染层）
npm run smoke        # 构建后跑冒烟自检

打包

npm run build:win     # 构建 + electron-builder 出 Windows 包
npm run build:local   # 在上面基础上复制到本地发布目录

产物在 release/，两种形态：

• MediaHub-<版本>-portable.exe 免安装版
• MediaHub-<版本>-setup.exe NSIS 安装版（可选安装目录，装完自动启动）

更新

npm run publish:update   # 生成更新包

更新包与主程序分离发布，应用启动时检查。

文档

项目根目录下这几份是随开发一起维护的实现规格，改功能前先看对应的：

• 本地媒体管理工具-可行性分析与方案.md 总体方案
• 方案_播放器与交互改造_实现规格.md 播放器与交互
• 方案_分类与收纳_实现规格.md 分类与集合
• 方案_界面动效规划.md 界面动效
• 方案_卡片动效优化.md 卡片动效
• 方案_游戏库_实现规格.md 游戏库

说明

node_modules/、out/、build/、release/、*.exe 以及备份归档目录都已在 .gitignore 中排除，仓库里只有源码、脚本、配置与文档。