mobkit

MobKit 为 APICloud / YonBuilder / AVM 移动工程提供现代前端工具链。在保留经典 webview 工作方式的同时，支持以 Vite + Preact/React + TypeScript 开发，并提供真机同步、开发热更、真机自动化与用友云集成。

一个包，多个入口：命令行（mobkit / mk）、构建插件（mobkit/vite、mobkit/rsbuild）、程序化库。浏览器端运行时为独立包 @mobkit/runtime。

要求 Node ≥ 20.18.1（或 Bun ≥ 1.3）。VS Code 与 JetBrains 插件内置同源 CLI，安装插件后无需单独安装本包。

概述

MobKit 面向混合移动工程（以 config.xml 为工程标志）的开发、调试与发布，封装了 WiFi 同步协议、设备工具链（adb / xcrun / hdc）、用友云接口与构建集成。

工程形态

MobKit 支持两类工程，命令与工作流据此区分。

设备端两类工程均由 AppLoader 通过 file:// 加载 widget。现代构建的产物形态处理见生产构建产物。

安装

# 全局命令
npm i -g mobkit

# 或在现代工程中作为构建插件与运行时
pnpm add -D mobkit
pnpm add @mobkit/runtime

mobkit help              # 列出全部命令（mk 为等价短别名）
mobkit version
mobkit <command> --help  # 单个命令的完整参数

快速开始

经典 webview 工程

mobkit wifi start        # 启动同步服务并打印二维码
# 真机 AppLoader 扫码连接（手机与电脑处于同一局域网）
mobkit wifi sync         # 推送改动到真机（--all 全量）
mobkit wifi log          # 查看 App 内 console 输出

现代 Vite 工程（无 IDE 插件也可闭环）

mobkit cloud create-app --name 我的应用 --template modern
cd <应用目录>
pnpm i
pnpm dev                 # Vite + 同步挂载（端口自 10920 起）+ 终端打印二维码
# AppLoader 扫终端二维码 → 首连自动推 dist → 重进 App 进 Vite HMR
pnpm sync                # 验包：自动 build + 全量推 dist 并退出热更

config.xml 的 content 恒为 dist/index.html（单一入口）。热更会话在开发机同步服务内存（GET /_mobkit/dev-lane），不是设备上的 json/门卫 HTML。

vite.config.ts：

import { defineConfig } from 'vite'
import preact from '@preact/preset-vite'
import mobkit from 'mobkit/vite'

export default defineConfig({
  base: './', // build 用相对路径；serve 时插件会强制 base:'/' 以适配真机 WebView
  plugins: [preact(), mobkit({ syncServer: 'mount' })],
  server: { host: true } // 端口勿钉 5174：插件从 10920 起找空闲并 strictPort
})

入口 src/main.tsx：从 @mobkit/runtime 引入并调用 apiReady()（见运行时）。

开发热更（dev lane）

现代工程内环：设备在「Vite 页内 HMR」与「加载 dist 产物」之间切换。

工作原理

1. pnpm dev 挂同步到 Vite 同端口，并在开发机登记热更会话。
2. 设备扫该端口；首连自动全量推 config.xml + dist/（HTML 注入 boot + 同步服务 origin）。
3. 设备开 App → boot 问 {origin}/_mobkit/dev-lane：有会话且 Vite 可达则 location 到 Vite；否则继续 file:// dist。
4. 改码由 Vite HMR 更新；热更中增量 wifi sync 不发 SYNC（避免 AppLoader 整壳重启）。
5. 全量 wifi sync --all / 面板「推构建产物」：自动 build → 推 dist → 退出热更（验包）。

控制方式

注意事项

• 扫码请用 现代挂载口（10920+），不要扫经典 10918（若 IDE 另起了经典服务）。
• 插件默认 strictPort；端口被占用会启动失败并打印占用者，避免漂到陈旧端口。
• 换网络后重扫码；全量 sync 后若要回热更：再 mobkit dev --wait 或重启 pnpm dev，然后设备重进 App。
• 云端上传打的是 widget 产物包（config + dist），不是完整 TS 工程；现代工程上传前会自动 build。

生产构建产物（file:// 备用）

Android AppLoader 通过 file:// 加载 widget 时，<script type="module"> 会因 MIME 为空被拒。mobkit/vite 默认在 build 时输出单文件 IIFE（经典 script），并剥掉 type=module / crossorigin。dev 走 http:// 不受影响。可设 fileProtocol: false 关闭。

命令行参考

命令附加 --json 时输出 NDJSON 事件流，供脚本与 IDE 消费。完整参数见 mobkit <command> --help。

真机同步

开发热更

用友云工作台

环境与工程

真机自动化

AI 集成

构建插件

mobkit/vite

import mobkit from 'mobkit/vite'

plugins: [mobkit({ syncServer: 'mount' })]

插件将现代 Vite 工程接入 MobKit，覆盖开发与构建两侧。

mobkit:windows 虚拟模块（内部契约）

插件与运行时之间的内部契约，应用不直接 import。插件将 src/windows/*/index.tsx 生成为「窗口名到动态导入」的映射（保留代码分割），运行时的 apiReady 消费它按 __page 挂载窗口。实现与具体打包器无关，替代 Vite 专有的 import.meta.glob；每个打包器插件各自提供，从而支持跨打包器。

工程应设 server.strictPort: true（见 dev lane 注意事项）。

mobkit/rsbuild（实验性）

Rspack 生态的适配层，与 mobkit/vite 共用同一插件核心（mobkit:windows 代码生成、dev lane 逻辑）。当前 syncServer 单端口挂载与 fileProtocol 尚未接入，rsbuild 工程需自行处理生产产物形态。

运行时

浏览器端运行时为独立包，用于单基座工程实现原生多窗口，并在浏览器中以 shim 开发。应用入口只需一行：

// src/main.tsx
import { apiReady } from '@mobkit/runtime'

apiReady() // 等待引擎就绪、解析当前窗口、按需加载并渲染

• @mobkit/runtime：应用入口 apiReady（就绪回调 + 可选 fallback / mount 入参）。渲染由构建插件按工程框架（Preact / React / Vue）适配，导入路径不含框架名。
• @mobkit/runtime/win：底层原语（whenReady、resolvePage、win、bus、prefs），供自定义引导。
• @mobkit/runtime/shim：window.api 的浏览器 polyfill；真机由引擎注入，shim 不覆盖。

窗口注册（src/windows/*）与热更由构建插件处理，应用无需感知内部的 mobkit:windows 契约。完整 API 见 @mobkit/runtime。

程序化库

构建工具可在进程内调用，避免启动 CLI 子进程：

import { wifiSync } from 'mobkit'

// 构建后将 dist/ 增量推送到已连接的真机
await wifiSync({ project: process.cwd() })

其他导出：runCli、agentInit，以及 wifi / cloud / project / device 命名空间与 VERSION。

许可

闭源，详见随包 dist/EULA.md（SEE LICENSE IN EULA.md）。