koring-launcher/DEV.md

Koring Launcher — 开发文档

技术栈

层	技术
Frontend	React 19 + Vite 7 + TypeScript
UI	Tailwind CSS v4 + shadcn/ui (base-ui)
状态管理	Zustand
Backend	Rust / Tauri 2
Sidecar	Node.js / TypeScript / @xmcl/*
包管理	pnpm
目标平台	ARM64 Windows (aarch64-pc-windows-msvc)

快速命令

pnpm dev                # 前端 dev server (port 1420)
pnpm dev:t              # 前端 + Rust dev (需 VS 环境)
./dev-vs.cmd            # VS ARM64 环境启动 dev
pnpm build              # 生产构建 (switch-icon run + tsc + vite build)
pnpm build:beta         # Beta 构建 (switch-icon beta + tsc + vite build --mode beta)
./build-vs.cmd          # Rust 编译 (production, NSIS 打包)
./build-vs.cmd --mode beta  # Rust 编译 (beta, 跳过打包)

构建模式

模式	VITE_BUILD_MODE	图标	Badge	说明
dev	"dev"	dev.png	🟢 DEV	开发预览版
beta	"beta"	beta.png	🟡 BETA	测试版
run	"run"	run.png	无	正式版

模式由 src/lib/mode.ts 导出 BUILD_MODE, isDev, isBeta, isRun。

环境变量 (.env.*)

VITE_BUILD_MODE=dev|beta|run
VITE_APP_ICON=/dev.png|/beta.png|/run.png
VITE_START_POP=true|false              # 启动弹窗开关
VITE_START_POP_TITLE="..."             # 弹窗标题
VITE_START_POP_INFO="..."              # 弹窗内容
VITE_START_POP_BOUTTON="..."           # 弹窗按钮文字

---

项目结构

koring-launcher/
├── src/                        # 前端源码
│   ├── App.tsx                 # 路由入口 (Zustand 路由)
│   ├── index.css               # 全局样式 + CSS 变量 + 动画
│   ├── layouts/
│   │   └── RootLayout.tsx      # 三层布局: BackgroundLayer + ContentLayer + SystemLayer
│   ├── components/
│   │   ├── background/
│   │   │   └── BackgroundLayer.tsx    # 全屏背景层 + 视差 + 强内容遮罩
│   │   ├── system/
│   │   │   ├── SystemLayer.tsx        # 系统层容器 (z-[100])
│   │   │   ├── TitleBar.tsx           # 自定义标题栏 (40px, 胶囊菜单/返回按钮)
│   │   │   └── WindowControls.tsx     # 窗口按钮 + DEV/BETA badge + TaskButton
│   │   ├── splash/
│   │   │   └── Splash.tsx             # 启动动画 (独立窗口, HTML+React)
│   │   ├── silk/
│   │   │   └── Silk.tsx               # WebGL 丝绸着色器 (Three.js)
│   │   ├── task/
│   │   │   ├── TaskButton.tsx         # 标题栏任务指示器 (SVG 圆弧动画)
│   │   │   ├── TaskSheet.tsx          # 任务队列侧面板 (z-[110])
│   │   │   └── TaskCard.tsx           # 单个任务卡片 (进度条+日志)
│   │   ├── ui/                        # shadcn/ui 组件
│   │   │   ├── sheet.tsx, button.tsx, switch.tsx, slider.tsx
│   │   │   ├── progress.tsx, badge.tsx, separator.tsx
│   │   │   ├── label.tsx, radio-group.tsx, alert-dialog.tsx
│   │   ├── VersionCard.tsx            # 版本/更新卡片 (Silk 背景+毛玻璃)
│   │   ├── UnderConstruction.tsx      # "装修中" 占位组件
│   │   └── StartupPopup.tsx           # 启动弹窗 (环境变量控制)
│   ├── stores/                 # Zustand 状态管理
│   ├── hooks/
│   │   └── useTheme.ts         # 同步 darkMode → .dark class
│   ├── lib/
│   │   ├── mode.ts             # BUILD_MODE 常量
│   │   └── utils.ts            # cn() 工具函数
│   ├── api/                    # Sidecar IPC 封装
│   ├── types/
│   │   └── task.ts             # Task 类型定义
│   └── pages/                  # 页面组件
├── src-tauri/                  # Rust 后端
│   ├── tauri.conf.json         # 窗口配置 + Bundle + Updater
│   ├── capabilities/default.json   # 权限声明
│   ├── src/
│   │   ├── lib.rs              # 插件注册 + splash/main 窗口逻辑
│   │   ├── commands/mod.rs     # Tauri 命令 (→ sidecar)
│   │   └── sidecar.rs          # Sidecar 进程管理
│   └── binaries/               # Sidecar 二进制文件
├── splash.html                 # 启动动画 HTML 入口 (加载 Splash.tsx)
├── build-vs.cmd                # VS 环境编译脚本
└── dev-vs.cmd                  # VS 环境开发脚本

---

页面路由

顶层路由 (标题栏可见)

Key	Label	组件	说明
home	首页	pages/home/index.tsx	欢迎页
store	资源	pages/store/index.tsx	🚧 装修中
today	资讯	pages/today/index.tsx	🚧 装修中
play-link	联机	pages/play-link/index.tsx	🚧 装修中
setting	设置	pages/setting/index.tsx	侧边栏 + 内容区

隐藏路由 (debug)

Key	Label	组件
debug	调试	pages/debug/index.tsx
debug-splash	启动动画调试	pages/debug/splash-debug.tsx
debug-display	显示效果调试	pages/debug/display-debug.tsx
debug-version-card	版本卡片调试	pages/debug/version-card-debug.tsx
debug-task	任务队列调试	pages/debug/task-debug.tsx

路由层级 (返回导航)

home / store / today / play-link / setting
  └─ debug
       ├─ debug-splash
       ├─ debug-display
       ├─ debug-version-card
       └─ debug-task

设置子页面 (setting 内部侧边栏)

分组	Key	组件	状态
通用	home	general/home.tsx	✅ 设置首页 (搜索+快捷入口)
	account	general/account.tsx	✅ Koring 账户 (微软登录)
	game-account	game/game-account.tsx	🚧 占位
	about	general/about.tsx	✅ 关于 (版本卡+链接)
	copyright	general/copyright.tsx	✅ 版权声明
游戏	java-mem	game/java-mem.tsx	✅ Java/内存/JVM 参数
	game-dir	game/game-dir.tsx	✅ 游戏目录路径
	advanced	game/advanced.tsx	✅ 高级设置
个性化	theme-bg	personalization/theme-bg.tsx	✅ 主题+背景 (文件选择器)
	ui	personalization/ui.tsx	✅ UI 设置
	lang	personalization/lang.tsx	✅ 语言设置
	a11y	personalization/a11y.tsx	✅ 无障碍
网络	download	network/download.tsx	✅ 下载设置
	security-id	network/security-id.tsx	✅ 第三方认证
	ether-online	network/ether-online.tsx	🚧 占位
	tawa-online	network/tawa-online.tsx	🚧 占位
其他	feedback	other/feedback.tsx	🚧 占位
	sponsor	other/sponsor.tsx	🚧 占位
	developer	(→ debug route)	跳转调试页

---

Zustand Stores

routeStore

管理页面路由和标题栏模式。

// State
current: RouteKey           // 当前路由 key
titleBarMode: TitleBarMode  // "default" | "sub" | "window"
direction: TransitionDirection  // "forward" | "backward"

// Actions
navigate(key)       // 跳转路由 (View Transitions API 动画)
goBack()            // 返回父路由 (通过 parentMap)
setTitleBarMode(m)  // 手动设置标题栏模式

themeStore

深色模式和视差设置。

// State
darkMode: "auto" | "light" | "dark"   // 默认 "auto"
parallax: boolean                       // 默认 true

// Actions
setDarkMode(mode)   // 应用深色模式到 DOM (.dark class)
setParallax(v)      // 设置视差开关

backgroundStore

背景图片/颜色/模糊/透明度 (localStorage 持久化)。

// State (localStorage: "koring-background")
type: "image" | "color"   // 默认 "image"
image: string              // 默认 "/background.png"
blur: number               // 默认 0 (0-20)
opacity: number            // 默认 1 (0-1)

// Actions
setImage(url)     // 设置背景图 (通过 convertFileSrc 转换本地路径)
setColor(color)   // 设置纯色背景
setBlur(blur)      // 设置模糊
setOpacity(op)     // 设置透明度
reset()            // 恢复默认

a11yStore

无障碍设置。

// State
reduceMotion: boolean          // 默认 false
reduceTransparency: boolean    // 默认 false
highContrast: boolean          // 默认 false
contentBlurOpacity: number     // 默认 50 (0-100)

// Actions
setReduceMotion(v)
setReduceTransparency(v)
setHighContrast(v)
setContentBlurOpacity(v)

devStore

开发者调试控制。

// State
forceDisableContentBlur: boolean       // 默认 false
previewMode: string | null             // 默认 null
previewUpdateState: PreviewUpdateState | null  // 默认 null
overlayOpacity: number                 // 默认 30
blurAmount: number                     // 默认 12

// Actions
setForceDisableContentBlur(v)
setPreviewMode(v)
setPreviewUpdateState(v)
setOverlayOpacity(v)
setBlurAmount(v)

updateStore

应用更新。

// State
checking: boolean
downloading: boolean
installed: boolean
progress: DownloadProgress | null
update: Update | null
error: string | null

// Actions
check()     // 检查更新 (调用 @tauri-apps/plugin-updater)
install()   // 下载并安装
reset()     // 清除状态

taskStore

任务队列系统 (localStorage 持久化历史)。

// State (localStorage: "koring-task-history", max 50)
tasks: Task[]
sheetOpen: boolean

// Derived
isRunning()        // 是否有运行中/等待中的任务
activeTasks()      // 运行中+等待中的任务列表
completedTasks()   // 已完成/失败/取消的任务列表

// Actions
addTask(type, title, desc, executor)  // 添加任务并自动开始
cancelTask(id)     // 取消任务 (AbortController)
removeTask(id)     // 删除任务
retryTask(id)      // 重试失败任务
clearHistory()     // 清空历史
openSheet() / closeSheet()

authStore

账户认证 (localStorage: "koring-user")。

// State
user: AuthResult | null    // { username, uuid, accessToken, expiresAt, xboxProfile }
loading: boolean
error: string | null

// Actions
loginOffline(username)
startMicrosoftLogin(clientId)
completeMicrosoftLogin(code, clientId)
logout()

installStore

Minecraft 安装。

// State
versions: VersionManifest | null
installing: boolean
loading: boolean
error: string | null

// Actions
fetchVersions(type?)
install(version, gamePath, javaPath?)
installLoader(mcVersion, gamePath, loaderType, loaderVersion?, javaPath?)

launchStore

游戏启动。

// State
launching: boolean
launched: boolean
gameResult: LaunchResult | null
events: GameEvent[]
error: string | null

// Actions
launch(options: LaunchOptions)
diagnose(gamePath, version)
reset()

modsStore

Mod 搜索与安装。

// State
searchResults: ModSearchResult[]
currentMod: ModSearchResult | null
modVersions: ModVersionResult[]

// Actions
search(query?, gameVersion?, loader?, source?)
getDetail(projectId, source)
getVersions(projectId, gameVersion?, loader?, source?)
install(projectId, versionId, gamePath, source?)

instanceStore

游戏实例管理。

// State
instances: InstanceInfo[]
currentInstance: InstanceInfo | null

// Actions
fetchInstances(instancesPath)
create(name, gamePath, mcVersion, ...)
remove(name, instancesPath)
select(name, instancesPath)

---

核心组件

三层布局 (RootLayout)

z-0   BackgroundLayer     全屏背景图 + 视差 + 模糊 + 强内容遮罩
z-1   ContentLayer        页面内容区 (top: 40px, overflow-auto)
z-100 SystemLayer         自定义标题栏 (TitleBar)
z-110 TaskSheet           任务队列面板 (右滑入)
z-200 StartupPopup        启动弹窗 (环境变量控制)

TitleBar 标题栏

三种模式:

• default: 左侧品牌文字 + 中间胶囊菜单 (可拖拽切换) + 右侧窗口控制
• sub: 左侧返回按钮 + 品牌文字 + 右侧窗口控制 (隐藏 TaskButton)
• window: 仅窗口控制

BackgroundLayer 背景层

• 支持 image (CSS background-image) 和 color (CSS background-color) 两种类型
• 视差效果: 鼠标移动时背景偏移 ±20px, scale(1.05)
• 强内容遮罩: 非 home 页面自动显示 (可通过 contentBlurOpacity 控制)
• 深色模式叠加层: bg-black/35

VersionCard 版本卡片

• Silk WebGL 动画背景 + 毛玻璃叠加层
• 三种更新状态: latest / hasUpdate / installed
• 颜色方案: dev=amber, beta=emerald, run=blue
• 可通过 props 覆盖 mode 和 state (用于 debug)

TaskQueue 任务系统

• 执行器模式: addTask(type, title, desc, async (ctx) => {...})
• 支持并行执行 (多个任务同时运行)
• AbortController 取消机制
• localStorage 持久化历史 (max 50)
• 任务类型: install / download / update / launch / auth / sync / custom

---

Tauri 窗口配置

窗口	尺寸	特性
splashscreen	480×320	无边框, 透明, 不可缩放, 居中
main	900×600 (min 800×600)	无边框, 透明, 隐藏启动

权限 (capabilities/default.json)

core:default, core:window:default, core:window:allow-*,
core:webview:allow-create-webview-window,
opener:default, process:default, shell:allow-execute,
updater:default, dialog:default

Rust 插件

tauri-plugin-opener, tauri-plugin-process, tauri-plugin-dialog,
tauri-plugin-shell, tauri-plugin-updater

IPC 协议

前端 → invoke() → Rust commands::sidecar_request → sidecar stdin (JSON) → sidecar stdout (JSON) → Tauri 事件 → 前端

Sidecar 命令: install-minecraft, install-mod-loader, get-version-list, launch-game, offline-login, search-mods, install-mod, create-instance, list-instances, background:*