▶_MiniApp Toolkit

Kbone

框架维护中

微信官方开源的小程序/Web 同构解决方案。通过适配层在小程序中模拟浏览器 DOM 环境,让 Vue/React/Preact 等 Web 框架的代码几乎无改动地运行在微信小程序中。

4,913🕒 最近更新 2025-10
前端框架Web同构微信官方

特性

  • Web与小程序同构
  • 模拟浏览器DOM/BOM环境
  • 支持Vue/React/Preact/Omi
  • 微信官方维护
  • 可使用小程序原生组件
  • webpack构建

详细文档

Kbone — 微信小程序 Web 同构方案#

资源概述#

Kbone 是微信官方开源的小程序/Web 同构解决方案。它的核心思路是:在小程序运行时中实现一个适配层,模拟出浏览器环境(DOM/BOM),让 Web 端代码(Vue、React、Preact、Omi 等)几乎不做改动就能运行在微信小程序里。

为什么需要 Kbone:

  • 小程序底层模型与 Web 不同,无法直接运行 Web 框架代码
  • 传统跨端方案(如 Taro、uni-app)通过编译转换实现,会损失部分框架特性
  • Kbone 通过运行时适配,保留了 Web 框架的完整能力(如 Vue 的 v-html、Vue Router)

核心优势:

  • 框架兼容性好:大部分流行前端框架都能直接运行(Vue/React/Preact/Omi)
  • 特性完整:不删改框架底层,保留如 v-html、Vue Router 等特性
  • DOM/BOM 接口:提供 documentwindownavigatorhistory 等常用接口
  • 原生组件可用:在小程序端仍可使用 live-player、分包等小程序原生能力

适用场景: 已有 Web 项目(Vue/React)需要快速迁移到微信小程序,且不想重写代码。

权衡: 适配层引入了额外性能开销(模拟 DOM),节点数极多(>1000)的页面性能不如原生开发。

设计规范#

架构模型#

code
┌─────────────────────────────┐
│   你的代码 (Vue/React/...)   │
├─────────────────────────────┤
│   Web 框架运行时              │
├─────────────────────────────┤
│   Kbone 适配层 (模拟 DOM/BOM) │
├─────────────────────────────┤
│   微信小程序运行时             │
└─────────────────────────────┘

Kbone 在小程序逻辑层中创建了一个 window 对象,包含 DOM 事件系统、节点树管理等。Web 框架操作虚拟 DOM → Kbone 适配层将其映射为小程序自定义组件的渲染和数据更新。

构建配置#

Kbone 使用 webpack 构建,核心配置项在 mp-webpack-plugin 中:

code
// build/miniprogram.config.js
module.exports = {
  origin: 'https://test.miniprogram.com',
  entry: '/index.html',
  router: {
    index: ['/', '/home'],
    list: ['/list'],
  },
  redirect: {
    notFound: 'index',
    accessDenied: 'index',
  },
  generate: {
    autoBuildWXCom: true, // 自动生成小程序自定义组件
  },
}

审核规范#

Kbone 项目编译后输出标准微信小程序代码(自定义组件 + 页面),审核流程与原生小程序一致。需注意:

  • 主体需在微信公众平台注册并通过认证
  • 业务域名需配置合法域名白名单
  • iOS 端虚拟支付需走 iOS 内购
  • 适配层不改变审核规则,仍需遵守微信小程序运营规范

开发指南#

快速上手#

code
# 方式一:使用 kbone-cli(推荐)
npm install -g kbone-cli
kbone init my-app    # 选择 Vue/React/Preact 模板

cd my-app

# 开发小程序端
npm run mp

# 开发 Web 端
npm run web

# 构建 Web 端
npm run build
code
# 方式二:直接 clone 模板
# Vue 模板
git clone https://github.com/wechat-miniprogram/kbone-template-vue.git
# React 模板
git clone https://github.com/wechat-miniprogram/kbone-template-react.git

Vue + Kbone 示例#

code
<!-- src/App.vue -->
<template>
  <div class="container">
    <h1>{{ title }}</h1>
    <button @click="handleClick">点击 {{ count }}</button>
    <div v-html="htmlContent"></div>
  </div>
</template>

<script>
export default {
  data() {
    return {
      title: 'Kbone + Vue',
      count: 0,
      htmlContent: '<span style="color:red">v-html 可用</span>'
    }
  },
  methods: {
    handleClick() {
      this.count++
      // 直接调用小程序原生 API
      wx.showToast({ title: `点击了 ${this.count} 次` })
    }
  }
}
</script>

常见陷阱#

  1. 包体较大:适配层运行时 + Web 框架运行时约占 500KB-1MB,实际业务可用包体空间显著减少
  2. 性能损耗:每次 DOM 操作需经过适配层转换,高频更新场景(长列表滚动、动画)性能不如原生
  3. 节点数限制:微信小程序 wxml 节点数上限约 1000 个(层级受限),复杂页面可能触顶
  4. 不完全兼容:部分 DOM/BOM 接口未实现(如 getComputedStyle 有简化版扩展),需查阅兼容性文档
  5. 调试复杂:出问题时需判断是框架层、适配层还是小程序运行时的问题
  6. 不支持所有小程序平台:Kbone 专注于微信小程序,不适用于支付宝/百度/抖音等

何时选 Kbone vs 原生/跨端框架#

场景推荐原因
已有 Vue/React Web 项目迁移Kbone改动最少,保留框架完整特性
新项目,需多端Taro / uni-app编译方案性能更好,多端覆盖
性敏场景(长列表/动画)原生开发无适配层开销
需要 v-html 等高级特性Kbone编译方案无法实现

生态资源#

项目模板#

模板框架地址
kbone-template-vueVue 2GitHub
kbone-template-reactReactGitHub
kbone-template-preactPreactGitHub
kbone-template-kboneuiVue + Kbone UIGitHub
omi template-kboneOmiGitHub

UI 库#

说明
Kbone UI微信官方配套 UI 库,对齐 WeUI 样式,支持 Vue 语法在小程序和 H5 双端运行

社区资源#

版本更新#

  • 维护状态:微信团队维护,更新频率较低(最近更新 2025 年 10 月)
  • 文档:官方文档持续可访问,有备份镜像
  • 兼容性:跟随微信基础库版本更新适配层,但可能存在滞后
  • 注意事项:Kbone 为 Web 同构的专用方案,如需跨端编译建议使用 Taro / uni-app