VTuber Mini

540px 宽的移动端 H5 —— 单 VTuber 粉丝养成 app(养宠物、抽卡、纪念日提醒、商城兑换)。一套模板服务一个 VTuber,可换皮。

技术栈

React 19 + Vite 8 + Tailwind CSS 4 + TypeScript;Capacitor 8 打包 Android。包管理用 pnpm。

目录结构

.
├── vtubermini/              # 前端主工程(代码都在这)
│   ├── src/                 # 源码(pages / components / lib / services)
│   ├── docs/                # 工程文档(Android 构建、接口契约等)
│   ├── AGENTS.md            # ⭐ 自适应布局规范(给 codex/AI 调页面用,改 UI 前必读)
│   ├── android/             # Capacitor Android 工程
│   └── package.json
├── design/                  # 设计稿
├── assets/                  # 素材
├── Product-Spec.md          # 产品规格
├── DEV-PLAN.md              # 开发计划
├── *-Breakdown.md / *.mmd   # 需求拆解 / UX 流程图
└── .codex-logs/             # codex 运行日志

快速启动(本地预览)

cd vtubermini
pnpm install        # 首次需要
pnpm dev            # 启动,浏览器打开终端显示的 http://localhost:5173/

• 打开后先是登录页 → 点 「进入花园」 进首页。
• 看不同手机宽度:Chrome 按 F12 → 设备工具栏 → 选 360 / 390 / 414。
• 桌面不开设备模拟时,页面是一个 540 宽的竖条居中显示(已去掉手机外壳)。

构建 / Android 打包

cd vtubermini
pnpm build          # 类型检查 + 产出 dist/
pnpm cap:sync       # 把 web 资源同步到 Android 工程

Android 打 APK 需要 JDK 17 + Android Studio + ANDROID_HOME,详细步骤见 vtubermini/docs/android-build.md。

当前进度(自适应改造)

全站自适应采用分层解耦:背景美术留在 9:16 画布(object-cover 铺满、边缘可裁),UI(对话框 / tab / 图标 / 头像)锚定视口容器、不随宽度漂。解决手机宽度变化导致 UI 错位 / 漂移的问题。

• ✅ 首页 src/pages/home-page.tsx:背景视频 + 立绘在 9:16 画布;tab + 对话框已锚屏幕(画布外)——已改对的样板
• ✅ 自适应规范已沉淀为权威版 vtubermini/AGENTS.md(分层心法 + 判断 3 步 + 反面教材 + 验证法)——同事用 codex 调任何页照此执行
• ✅ 全部页面已审查:其余 18 页均合规(只有 home 曾用 9:16 画布致 UI 漂、已修);后续新页面 / 改动遵循 AGENTS.md 即可

核心规则(详见 vtubermini/AGENTS.md):

1. 分层:美术(背景 / 立绘)留 9:16 画布 object-cover 铺满;UI(对话框 / tab / 图标)锚视口容器(.device-stage / h-full),绝不挂进画布;
2. 别在 9:16 画布里用百分比纵向定位(bottom-[X%] 随宽度漂);
3. 关键尺寸写 inline style 用 vw/vh/min();
4. 改完换 360 / 400 / 540 实测 UI 距屏幕底 px 不变。

关键文档

文档	用途
vtubermini/AGENTS.md	自适应布局规范(改任何页面 UI 前必读)
vtubermini/docs/android-build.md	Android 构建步骤
vtubermini/docs/api-contract.md	前后端接口契约
Product-Spec.md / DEV-PLAN.md	产品规格 / 开发计划