vtubermini/vtubermini

VTuber Mini

单个虚拟主播的粉丝陪伴 App。粉丝每天回到这个私密的「冷蓝色粉丝空间」照料主题宠物、抽卡收集、查看纪念日、兑换创作者周边。

本仓库是该 App 的 前端工程:一个 React + Vite 构建的单页应用,通过 Capacitor 打包为原生 Android App,为 App 提供本地 H5 界面(界面随包内置、离线运行,不依赖在线服务器)。

⚠️ 核心约定:Capacitor 加载的是 dist/ 目录里的构建产物(capacitor.config.ts 中 webDir: 'dist')。 每次同步到原生工程 / 打包前,必须先 pnpm build,否则原生壳里装的是上一次(甚至为空)的旧界面。

---

技术栈

领域	选型
框架	React 19 + TypeScript
构建	Vite 8
样式	Tailwind CSS 4(@tailwindcss/vite)
图标	lucide-react
原生封装	Capacitor 8(目前仅 Android 平台)
代码规范	ESLint 10

环境要求

• Node.js ≥ 20.19(Vite 8 要求,推荐 LTS)
• pnpm(本项目统一用 pnpm,锁文件为 pnpm-lock.yaml;不要和 npm/yarn 混用,混装会污染 node_modules 依赖树,导致 dev server 起不来)
• 打包 Android 还需:JDK 17、Android SDK、Android Studio(可用 pnpm check:android 自检本机环境)

快速开始

# 安装依赖
pnpm install

# 启动开发服务器(默认 http://localhost:5176,监听 0.0.0.0,可局域网/真机调试)
pnpm dev

构建与打包到 Android

H5 → 原生的链路是:build 生成 dist/ → cap sync 把 dist/ 同步进 android/ 工程 → Android Studio / Gradle 打 APK。

# 1) 构建 H5(类型检查 + Vite 打包,输出到 dist/)
pnpm build

# 2) 把 dist/ 同步进 Android 原生工程
pnpm cap:sync            # 等价于 npx cap sync android

# —— 或者一步到位(先 build 再 sync)——
pnpm android:sync

同步完成后,用 Android Studio 打开 android/ 目录构建并运行,或用 Gradle 直接打包 APK。

再次提醒:改了任何前端代码后,务必重新 pnpm build(或直接 pnpm android:sync),再去构建 APK。cap sync 本身不会触发前端构建。

项目结构

vtubermini/
├─ src/
│  ├─ App.tsx / main.tsx / index.css   # 应用入口与全局样式
│  ├─ pages/                           # 页面
│  ├─ components/                      # 业务组件,按功能域划分:
│  │   ├─ home/ anniversary/ pet/      #   首页 / 纪念日 / 宠物
│  │   ├─ gacha/ album/ shop/ orders/  #   抽卡 / 心动档案 / 商城 / 订单
│  │   ├─ game/ profile/ common/       #   小游戏 / 个人资料 / 通用
│  ├─ admin/                           # 内置管理/配置页
│  ├─ hooks/                           # 自定义 Hooks
│  ├─ services/                        # 数据与业务服务
│  ├─ lib/                             # 工具与布局数据(部分由插件自动生成,见下)
│  └─ assets/desktop-assets/           # 立绘、视频等媒体素材(经 Git LFS 管理)
├─ android/                            # Capacitor 生成的 Android 原生工程
├─ public/                             # 原样拷贝的静态资源
├─ dist/                               # 构建产物(被 .gitignore 忽略,由 pnpm build 生成)
├─ capacitor.config.ts                # Capacitor 配置(appId / appName / webDir)
└─ vite.config.ts                     # Vite 配置 + 自定义布局编写插件

可用脚本

命令	作用
pnpm dev	启动 Vite 开发服务器(0.0.0.0:5176,支持真机/局域网调试)
pnpm build	类型检查(tsc -b)+ Vite 构建,输出到 dist/
pnpm cap:sync	npx cap sync android,把 dist/ 同步进 Android 工程
pnpm android:sync	一步到位:先 build 再 cap:sync
pnpm check:android	自检本机 Android 构建环境
pnpm lint	运行 ESLint
pnpm preview	本地预览 dist/ 构建产物

开发说明

首页布局可视化编辑

vite.config.ts 内置了一个 layoutWriterPlugin:在开发模式下,前端可把首页各元素(头像、纪念日素材、底部图标等)的位置通过 POST /__vtubermini/save-layouts 回写到 src/lib/home-layout.ts 与 src/lib/anniversary-image-layout.ts。这些布局文件因此是半自动生成的——通过可视化调整保存,而非手改坐标。该接口仅在 dev server 生效,生产构建不包含。

App 信息

• appId:com.vtubermini.app
• appName:VTuber Mini
• 该模板按「一次服务一位主播」设计,可作为同类粉丝陪伴 App 的可复用底座。