MFCMouseEffect Web设置页开发指南：Svelte + Vite + 内嵌HTTP服务器实现跨平台统一设置界面

MFCMouseEffect 是一款跨平台鼠标特效与输入可视化引擎，支持点击、轨迹、滚轮、悬停等效果，并可通过手势映射实现快捷键自动化。它的 Web 设置页 用 Svelte 5 + Vite 5 构建，由主程序内嵌的零依赖 C++ HTTP 服务器直接托管，Windows / macOS / Linux 共用同一套界面，真正做到「修改即生效，跨平台统一」。

为什么选择「浏览器里的设置页」？

传统桌面软件通常用原生窗口做设置界面，每加一个功能都要同步维护多套 UI。MFCMouseEffect 的做法是：

• 🎨 一套界面，全平台通用：设置页是纯 Web 技术栈，任何平台只需托管静态文件 + 提供 API；
• ⚡ 修改即生效：设置保存在 config.json，无需重启应用；
• 🔒 本地安全：服务器只监听本机回环地址，且每次启动生成随机 Token，防止未授权访问；
• 📦 零额外依赖：HTTP 服务器由 C++ 实现并内嵌进可执行文件，用户不需要安装 Node.js 或其他运行时。

整体架构：三层结构一览

整个 Web 设置系统可以拆成三层，职责非常清晰：

层级	技术	位置	职责
前端界面	Svelte 5 + Vite 5	WebUIWorkspace/	组件、表单、国际化、API 调用
静态资源	原生 JS + CSS	WebUI/	构建产物与运行时入口
内嵌服务器	零依赖 C++ HTTP	MouseFx/Server/	静态文件托管 + REST API + Token 鉴权

前端技术栈：Svelte 5 多入口 + Vite 构建

工作区 package.json 里只声明了三个 devDependencies：svelte@5、vite@5、@sveltejs/vite-plugin-svelte，用 pnpm 管理。

构建的核心思路是按设置分区拆分多入口 IIFE 包。在 vite.config.js 中定义了 TARGETS 映射表，每个分区（general、effects、trail、automation、wasm 等）对应一个入口文件和产物文件，例如：

vite build --mode general   →  general-settings.svelte.js
vite build --mode effects   →  effects-settings.svelte.js
vite build --mode automation →  automation-ui.svelte.js

一条 pnpm run build 会依次构建 11 个包（dialog / shell / workspace / general / mouse-companion / effects / text / trail / indicator / automation / wasm），再由 copy-output.mjs 把产物拷入 WebUI/ 并同步到 x64/Debug|Release/webui/ 运行时目录。

一个容易踩坑的细节：桌面运行时只引用 WebUI/styles.css，所以构建时会将组件 CSS 内联进各自 bundle（emitCss: false），否则静态运行时会丢失样式。

最终页面由 WebUI/index.html 依次加载这些 bundle，形成「外壳 + 分区」的挂载结构。

内嵌 HTTP 服务器：零依赖 + Token 鉴权

服务器入口是 WebSettingsServer.h，底层是 HttpServer.h 实现的极简 HTTP 服务。几个关键设计：

1. Token 机制：Start() 时通过 MakeToken() 生成随机 Token，Web 端所有 /api/* 请求需携带 x-mfcmouseeffect-token 请求头；
2. 闲置自动关闭：idleTimeoutMs_ 默认为 5 分钟，内置 monitor 线程监控最后一次请求时间，无访问自动停服，不占用端口；
3. 路由分层：路由按业务拆分到 routes/core、routes/automation、routes/wasm、routes/testing 四个子目录，详见架构文档 server-structure.md；
4. 静态托管：webui/WebUiAssets.cpp 负责将 WebUI/ 目录文件按路径返回给浏览器。

这种「内嵌服务器 + 浏览器设置」的组合，正是跨平台统一界面能低成本落地的关键。

六大设置分区如何组织

分区列表定义在 sections.js，与侧边栏导航一一对应：

分区 ID	名称	对应入口
general	一般	general-main.js
mouse-companion	鼠标伴侣	mouse-companion-main.js
active	光标特效	effects-main.js
input-indicator	鼠标/键盘指示器	input-indicator-main.js
automation	自动化映射	automation-main.js
plugins	插件管理	wasm-main.js

其中 自动化映射 支持把手势、滚轮、鼠标动作映射为快捷键、延时、URL 或启动应用；插件管理 则负责 WASM 特效插件的导入、导出与目录检查。

开发工作流：本地代理调试

修改前端后不必每次重新编译 C++。vite.config.js 内置了一个 mfx-dev-runtime 插件：

• 开发模式下所有 /api/* 请求会被代理到真实运行的 MFCMouseEffect 后端；
• 后端地址和 Token 从 probe 文件（默认 /tmp/mfx-core-websettings.probe）或环境变量 MFX_WEBUI_DEV_BASE_URL / MFX_WEBUI_DEV_TOKEN 中解析；
• GET /__mfx/dev-runtime 可探测后端连通性状态。

日常调试只需：启动应用 → pnpm run dev → 打开本地 Vite 地址，前端改动热更新、API 直连真实后端。

关键路径速查

资源	路径
前端工作区	WebUIWorkspace/
构建配置	vite.config.js
分区定义	sections.js
运行时静态文件	WebUI/
内嵌服务器核心	core/WebSettingsServer.cpp
HTTP 实现	http/HttpServer.h
服务器架构文档	server-structure.md

总结

MFCMouseEffect 的 Web 设置页用 Svelte 5 + Vite 多入口构建 产出按分区拆分的静态 bundle，再由 零依赖 C++ 内嵌 HTTP 服务器 托管，配合 Token 鉴权与 5 分钟闲置自动关闭，实现了跨平台统一、开箱即用的设置体验。如果你想给鼠标特效工具加上手势自动化映射或 WASM 插件管理，这套「内嵌服务器 + Web 设置」架构非常值得参考。