Harness 桌面端封装实战，把 Web UI 变成独立 exe

为什么要把 Harness 包成桌面端DeepSeek Harness 的 Web UI 默认跑在浏览器里对开发者来说够用但离产品化还差口气。每次开终端、输命令、等端口流程不够顺畅而且浏览器标签一多Harness 很容易淹没在一堆页面里。用 Tauri 2 把它包成独立 exe本质上做三件事自动托管服务生命周期、提供原生窗口体验、让配置外置可定制。这篇文章基于社区已有的开源实现拆解这套方案的核心机制如果你也想把类似的 Web 工具桌面化可以直接参考这个思路。三大核心机制拆解自动探测与按需启停桌面端最大的价值是让服务有没有启动这件事对用户透明。实现上Rust 侧在应用启动时先尝试连接127.0.0.1:3080探测成功说明 Harness 服务已在运行直接加载 Web UI退出时不碰现有服务探测失败后台自动拉起服务进程等就绪后再加载退出时只停掉由自己启动的服务避免误伤手动开启的实例这个设计很克制没有粗暴地启动时全拉起来、退出时全杀掉而是区分了服务来源。对开发者来说这意味着你可以先用pnpm dsh web跑起服务再开桌面端两者能和平共处。探测逻辑的核心是轮询检查端口连通性配合超时控制。超时时间、探测地址、启动命令全部外置到配置文件程序本身不硬编码任何路径。harness.json 外置配置配置文件放在 exe 同级目录典型内容如下{ url: http://127.0.0.1:3080, probeAddr: 127.0.0.1:3080, workingDir: D:/deepseek_harness/deepseek-harness-master, command: node, args: [--import, tsx/esm, apps/cli/src/bin.ts, web], startupTimeoutSecs: 60 }几个关键设计点路径用/或\\都可以JSON 里反斜杠记得转义打包时通过bundle.resources把 harness.json 打进安装包装好后用户直接改安装目录里的文件即可生效无需重新编译项目根目录的 harness.json 是源文件改了要重新tauri build才会进安装包找不到配置文件时程序会回退到内置默认值保证开箱可用。这种外置优先、内置兜底的策略既方便了终端用户自定义也不让开发者担心配置丢失导致无法启动。窗口与视觉定制默认窗口尺寸 1280×800支持缩放。需要调整的话改src-tauri/src/lib.rs里的inner_size和min_inner_size即可。图标替换也很直接把src-tauri/icons/下的 png 和 ico 文件换掉或者用npm run tauri icon 图标.png自动生成全套标准尺寸。应用名、版本号、包标识符则在tauri.conf.json里配置。Rust 侧的 probe 逻辑实现虽然具体源码没完全展开但从工程结构可以推断 probe 的实现脉络。src-tauri/src/lib.rs承担核心 orchestration 职责读取配置 → 异步探测端口 → 条件启动子进程 → 创建窗口加载 URL。关键的状态管理在于区分谁启动的服务。桌面端需要维护一个标志位记录当前实例是否拥有这个服务进程这决定了退出时是否要执行清理。Tauri 的命令系统Command Pattern让前端可以调用 Rust 函数但 probe 和启停逻辑更适合放在后台自动完成避免用户感知到延迟。超时处理用到了异步 Rust 的tokio::time::timeout如果startupTimeoutSecs内服务未就绪应该给用户明确的错误提示而不是让窗口一直空白加载。打包产物与平台差异构建完成后产物在src-tauri/target/release/bundle/下格式说明适用场景NSIS (*-setup.exe)安装向导支持自定义安装路径推荐分发给终端用户MSIWindows Installer 标准格式企业部署、组策略分发首次构建需要下载 Rust 依赖并编译耗时约 5–15 分钟取决于网络和机器性能。建议提前配置好 cargo 的 USTC 镜像和 npm 的 npmmirror 镜像避免卡在下载阶段。macOS 打包需要额外注意两点必须在 macOS 本机执行构建无法跨平台编译需要准备icon.icns格式的图标可以用iconutil或在线工具从 png 转换如果暂时不需要 macOS 版本把tauri.conf.json里的bundle.targets改为[nsis]可以缩短构建时间。Tauri 2 vs Electron体积与启动速度把 Web UI 包成桌面端Electron 是最先想到的选择。但在这个场景下Tauri 2 有几个明显优势体积方面Tauri 2 的应用体积显著更小。Electron 每个应用都自带 Chromium 和 Node.js基础体积就过百兆Tauri 2 用系统 WebViewWindows 上基于 Edge WebView2Rust 编译后的二进制本身很紧凑最终安装包可以控制在 10MB 级别。启动速度Tauri 2 冷启动更快。Electron 需要初始化完整的 Chromium 进程而 Tauri 2 的 Rust 主进程轻量得多窗口可以更快出现。对于先探测服务、再加载页面这种有依赖链路的场景主进程启动快意味着整个流程的感知延迟更低。内存占用运行时的差异更明显。Electron 的内存基准线较高开几个窗口就容易吃满内存Tauri 2 的 Rust 进程内存占用更可控长时间运行更稳定。当然Electron 的生态系统更成熟调试工具更丰富。但如果你的需求就是把 Web UI 装进原生窗口再加一些系统级能力文件读写、进程管理Tauri 2 的精简架构反而更贴合不需要为用不到的 Chromium 功能买单。实际构建中的踩坑记录Node.js 版本Harness 本身要求 v22.19构建桌面端前务必确认。版本不对会导致服务起不来但错误提示可能藏在子进程输出里需要手动在终端跑一遍启动命令才能看到。路径问题Windows 上workingDir如果用了未转义的反斜杠JSON 解析会直接失败。建议统一用正斜杠或者确保双反斜杠转义。端口占用3080 被占用时桌面端探测会认为服务已运行但加载的可能是另一个 Harness 实例或其他应用。目前配置里没有端口冲突的检测逻辑如果多人共用机器可能需要手动协调。开发模式与生产模式的配置差异npm run tauri dev默认用内置配置想在调试时测试自定义的 harness.json需要把文件放到调试 exe 旁边。这个细节文档里没强调容易让人误以为改了项目根目录的配置就能在 dev 模式生效。这套方案的边界与适用场景这个 Tauri 2 封装层最适合两类人一是想把 Harness 作为内部工具固定下来的技术团队二是基于 Harness 做二次产品化的开发者。它解决的不是让 Harness 功能更强而是让 Harness 用起来更顺。如果你的需求更复杂——比如要离线运行模型、要深度改造 UI、要集成更多原生能力——那可能需要直接改动 Harness 源码而不是在外面包一层。但对于Web UI 桌面化这个经典需求这套实现已经相当完整从自动服务管理到跨平台打包都覆盖到了。目前项目还是社区驱动v0.1 级别的 Harness 本身也在快速迭代。建议把 harness.json 的自定义配置和 Tauri 的打包流程写成内部文档方便团队新人上手也避免每次更新后重新踩一遍环境的坑。