开发与架构

本文面向希望参与 MintCat 开发、调试或本地构建的贡献者。

技术栈

MintCat 由前端界面与 Tauri 后端组成：

层	技术
前端	React、TypeScript、Vite、Ant Design
桌面容器	Tauri 2.0
后端	Rust
数据库	SQLite、Drizzle ORM
Mod 处理	Unreal Engine pak 集成、ZIP 解包、mod.io API
异步任务	自定义 task queue 插件

本地开发

安装依赖

pnpm install

启动开发环境

pnpm tauri dev

Vite 开发服务使用固定端口：

页面端口：1420
HMR 端口：1421

这是为了适配 Tauri 开发环境。

常用命令

pnpm build
pnpm tauri build
pnpm gen-sql
npx tsc --noEmit

说明：

命令	用途
`pnpm build`	构建前端资源
`pnpm tauri build`	构建生产版桌面应用
`pnpm gen-sql`	基于 Drizzle Schema 生成 SQLite 迁移 SQL
`npx tsc --noEmit`	TypeScript 类型检查

前端目录结构

目录	说明
`src/App.tsx`	应用主入口、路由与布局
`src/core/`	初始化、IoC、基础 ViewModel
`src/pages/`	首页、搜索页、设置页等主页面
`src/dialogs/`	添加 Mod、配置管理、选择游戏等弹窗
`src/components/`	标题栏、状态栏、菜单栏、通用组件
`src/services/`	业务服务层
`src/apis/`	Tauri API、网络 API、平台 API 封装
`src/storage/`	数据库访问、DAO、迁移与数据模型
`src/tasks/`	下载、安装、更新、冲突检查等任务
`src/events/`	事件系统
`src/locales/`	多语言资源

应用初始化流程

主流程：

App.tsx 渲染基础布局。
AppInitializer.initializeCore() 初始化核心能力。
初始化数据库。
注册并初始化核心 ViewModel。
加载主题、语言、用户设置。
根据首次启动状态展示新手引导。
路由进入首页、搜索页或设置页。

MVVM 与 IoC

项目使用 ViewModel 管理页面状态和业务逻辑，配合 IoC 容器获取单例对象。

典型对象：

AppViewModel：应用级设置、认证、主题、语言。
HomeViewModel：添加、删除、启停、分组、导出等首页操作。
TreeViewModel：首页树结构和分组状态。
SearchViewModel：搜索来源、查询、分页、排序、图片缓存。

服务层

src/services/ 负责承载业务逻辑，避免页面组件直接操作数据库或平台 API。

常见服务：

HomeService：首页 Mod 管理。
ProfileService：Profile 和当前配置。
ProfileTreeService：树形结构转换与维护。
ModService：Mod 数据处理。
ModUpdateService：在线更新检查。
ConflictService：冲突检查。
OAuthService：授权相关逻辑。
NetworkClient：网络请求统一封装。

数据库设计

数据库 Schema 位于 src/storage/db/Schema.ts。

核心表：

表	作用
`games`	游戏信息与路径
`users`	用户基础信息
`oauths`	各平台 OAuth 令牌
`mods`	Mod 基础元数据
`mod_versions`	Mod 版本信息
`mod_downloads`	下载与缓存状态
`mod_status`	在线可用性、本地丢失等状态
`profiles`	用户配置文件
`profile_folders`	Profile 内分组
`profile_mods`	Profile 与 Mod 的关联、启用状态、排序、使用版本
`settings`	全局设置

搜索架构

搜索页通过 Provider Registry 管理多个搜索来源。

主要概念：

SearchSource：搜索来源枚举。
ISearchProvider：统一搜索接口。
SearchProviderRegistry：来源注册和获取。
SearchViewModel：根据当前游戏过滤来源，并执行搜索、分页、排序。

新增搜索来源时，应优先实现统一 Provider 接口，而不是在页面里写平台判断逻辑。

任务系统

耗时操作通过任务系统执行，例如：

Mod 下载。
Mod 安装 / 整合。
Mod 更新检查。
冲突检查。

任务系统负责：

进度上报。
错误传播。
队列管理。
UI 状态同步。

Tauri 后端

Rust / Tauri 代码位于 src-tauri/。

常见能力：

文件系统访问。
SQLite 插件。
进程启动。
Deep Link OAuth 回调。
自动更新。
Unreal pak 文件处理。
ZIP 解包。
Steam 游戏路径检测。

构建发布

普通构建：

pnpm tauri build

Windows 交叉编译示例：

pnpm tauri build --runner cargo-xwin --target x86_64-pc-windows-gnu

项目也提供发布脚本：

npm run package

发布签名可能需要本地输入密钥密码，自动化流程无法代替操作者输入。

开发注意事项

TypeScript 当前未启用严格模式。
项目使用 Decorators，需要保留相关 tsconfig 设置。
React Compiler 为实验能力，构建警告需要具体判断。
不要在未确认数据迁移策略时直接修改 Schema。
涉及 OAuth、日志、网络请求时注意脱敏。
修改整合逻辑前建议先准备可回滚的测试 Profile。

技术栈​

本地开发​

安装依赖​

启动开发环境​

常用命令​

前端目录结构​

应用初始化流程​

MVVM 与 IoC​

服务层​

数据库设计​

搜索架构​

任务系统​

Tauri 后端​

构建发布​

开发注意事项​

技术栈