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 接口:提供
document、window、navigator、history等常用接口 - 原生组件可用:在小程序端仍可使用
live-player、分包等小程序原生能力
适用场景: 已有 Web 项目(Vue/React)需要快速迁移到微信小程序,且不想重写代码。
权衡: 适配层引入了额外性能开销(模拟 DOM),节点数极多(>1000)的页面性能不如原生开发。
设计规范#
架构模型#
┌─────────────────────────────┐
│ 你的代码 (Vue/React/...) │
├─────────────────────────────┤
│ Web 框架运行时 │
├─────────────────────────────┤
│ Kbone 适配层 (模拟 DOM/BOM) │
├─────────────────────────────┤
│ 微信小程序运行时 │
└─────────────────────────────┘
Kbone 在小程序逻辑层中创建了一个 window 对象,包含 DOM 事件系统、节点树管理等。Web 框架操作虚拟 DOM → Kbone 适配层将其映射为小程序自定义组件的渲染和数据更新。
构建配置#
Kbone 使用 webpack 构建,核心配置项在 mp-webpack-plugin 中:
// 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 内购
- 适配层不改变审核规则,仍需遵守微信小程序运营规范
开发指南#
快速上手#
# 方式一:使用 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
# 方式二:直接 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 示例#
<!-- 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>
常见陷阱#
- 包体较大:适配层运行时 + Web 框架运行时约占 500KB-1MB,实际业务可用包体空间显著减少
- 性能损耗:每次 DOM 操作需经过适配层转换,高频更新场景(长列表滚动、动画)性能不如原生
- 节点数限制:微信小程序 wxml 节点数上限约 1000 个(层级受限),复杂页面可能触顶
- 不完全兼容:部分 DOM/BOM 接口未实现(如
getComputedStyle有简化版扩展),需查阅兼容性文档 - 调试复杂:出问题时需判断是框架层、适配层还是小程序运行时的问题
- 不支持所有小程序平台:Kbone 专注于微信小程序,不适用于支付宝/百度/抖音等
何时选 Kbone vs 原生/跨端框架#
| 场景 | 推荐 | 原因 |
|---|---|---|
| 已有 Vue/React Web 项目迁移 | Kbone | 改动最少,保留框架完整特性 |
| 新项目,需多端 | Taro / uni-app | 编译方案性能更好,多端覆盖 |
| 性敏场景(长列表/动画) | 原生开发 | 无适配层开销 |
| 需要 v-html 等高级特性 | Kbone | 编译方案无法实现 |
生态资源#
项目模板#
| 模板 | 框架 | 地址 |
|---|---|---|
| kbone-template-vue | Vue 2 | GitHub |
| kbone-template-react | React | GitHub |
| kbone-template-preact | Preact | GitHub |
| kbone-template-kboneui | Vue + Kbone UI | GitHub |
| omi template-kbone | Omi | GitHub |
UI 库#
| 库 | 说明 |
|---|---|
| Kbone UI | 微信官方配套 UI 库,对齐 WeUI 样式,支持 Vue 语法在小程序和 H5 双端运行 |
社区资源#
- 官方文档:wechat-miniprogram.github.io/kbone
- 备份文档:developers.weixin.qq.com/kbone
- GitHub:wechat-miniprogram/kbone
- 社区:Kbone 微信社区
版本更新#
- 维护状态:微信团队维护,更新频率较低(最近更新 2025 年 10 月)
- 文档:官方文档持续可访问,有备份镜像
- 兼容性:跟随微信基础库版本更新适配层,但可能存在滞后
- 注意事项:Kbone 为 Web 同构的专用方案,如需跨端编译建议使用 Taro / uni-app