Home

StudyWithMiku 开发文档

本文档面向开发者，重点介绍 StudyWithMiku 项目的内部实现细节和开发者工具的使用。

文档版本

项目	值
基于 commit	尚未发版
说明	基于 v1.2.0 后的开发分支，包含 Protobuf 迁移和 Hook 系统重构
文档更新日期	2026-03-01

---

项目简介

StudyWithMiku 是一个「Study with Miku」企划主题的番茄钟学习陪伴 Web 应用，让 Miku 陪你一起学习。

核心特性

• 番茄钟计时系统 - 基于状态机实现，支持中断恢复、统计分析
• 多音乐源支持 - 网易云音乐、QQ音乐、Spotify 等平台
• 播放器适配器架构 - 可扩展的适配器模式，统一接口
• 本地音频存储 - OPFS + FileHandle 双模式支持
• 用户认证系统 - WebAuthn/FIDO2 无密码登录 + 多平台 OAuth 集成
• 云端数据同步 - 基于 Protobuf 编码的多设备数据同步，支持冲突解决
• 账号管理 - 多认证方式管理、跨账号合并、多源头像系统
• 钩子系统 (Hook System) - 通用 Provider 框架，支持通知、提示音、推送和电刺激 4 种 Provider
• 开发者控制台 (swm_dev) - 强大的调试和测试工具
• 在线计数服务 - 基于 Durable Objects 的实时在线人数

---

技术栈

前端

技术	版本	用途
Vue	3.3.4	响应式 UI 框架
Vite	7.3.0	构建工具
SCSS	-	样式预处理
VueUse	10.1.2	Vue 组合式工具库
APlayer	1.10.1	音乐播放器
Chart.js	4.5.1	统计图表
@simplewebauthn/browser	-	WebAuthn 浏览器端 API
@bufbuild/protobuf	2.x	Protobuf 二进制编解码 (Protobuf-ES)

后端

技术	版本	用途
Cloudflare Workers	-	Serverless 运行时
Hono.js	4.11.0	Web 框架
D1 (SQLite)	-	关系型数据库
Drizzle ORM	0.45.1	数据库 ORM
@simplewebauthn/server	13.2.2	WebAuthn 服务端验证
Durable Objects x4	-	有状态服务（在线计数、认证挑战、速率限制、番茄钟推送通知）

开发工具

工具	用途
Vitest	单元测试
Playwright	E2E 测试
ESLint + Prettier	代码规范
Husky	Git Hooks
Wrangler	Workers 部署工具
Drizzle Kit	数据库迁移工具

---

快速开始

环境要求

• Bun

安装依赖

bun install

开发模式

# 前端开发
bun run dev

# 后端 Worker 本地开发
bun run dev:worker

构建

bun run build

部署

# 部署 Worker 到 Cloudflare
bun run deploy:worker

数据库管理

# 生成数据库迁移
bun run db:generate

# 推送迁移到 D1
bun run db:push

运行测试

# 单元测试
bun run test

# API 测试
bun run test:api

# E2E 测试
bun run test:e2e

# 全部测试
bun run test:all

使用开发者控制台

在浏览器 DevTools 或 Eruda 中访问全局对象 swm_dev：

// 查看帮助(会列出模块)
swm_dev.help()

// 查看特定模块的 API
swm_dev.help('player')