更新记录

1.0.0（2026-08-06）

• 新版发布

平台兼容性

uni-app(4.76)

uni-app x(4.76)

yt-x5web

腾讯 TBS / X5 内核 UTS 插件：提供装核 / 初始化 API + 真正的 X5 WebView 组件 <yt-x5web>（com.tencent.smtt.sdk.WebView）。

特别提醒

• 购买本插件前，请先试用，请先试用，请先试用，确认满足需求之后再行购买。虚拟物品一旦购买之后无法退款。
• 如有使用上的疑问、bug，可以进交流群联系作者；
• 请在合法范围内使用，若使用本插件做非法开发，本方概不负责；
• 插件需先引入再打自定义基座后运行测试

同时支持 uni-app 与 uni-app-x 项目。

仅调用 initX5Environment 不会让系统自带 <web-view> 自动变成 X5。 要稳定使用 X5 渲染网页，请直接使用本插件的 <yt-x5web> 组件。

功能概览

1. 离线 / 网络安装 TBS 内核（本地 assets 或 CDN 直链）
2. 初始化 X5 环境、诊断 ABI / 是否可加载、查询当前内核
3. 强制杀进程并重启（装核后必须，否则进程内仍可能用旧核）
4. <yt-x5web> 组件：真正的 smtt WebView，带加载进度、错误、UA、是否 X5 等回调
5. 减小包体积：可删减单架构内核，或把 .tbs 放到自有服务器用网络安装

兼容性与限制（必读）

关于「系统 <web-view> 也走 X5」与 HBuilderX 版本

• 若希望 HBuilderX 打包后系统内置 <web-view> 也使用 X5 内核，请将 HBuilderX 降到 4.x。
• 在 HBuilderX 5.x 及更高版本中，常见现象是：X5 内核已经安装且 canLoadX5 提示可用，但 <web-view> 实际仍是系统内核。
• 推荐做法（与 HBX 版本无关）：页面里使用本插件的 <yt-x5web>，不要依赖系统 <web-view>。

目录结构

uni_modules/yt-x5web/
├── readme.md
├── package.json
└── utssdk/
    ├── interface.uts          # 对外类型定义
    ├── unierror.uts
    └── app-android/
        ├── index.uts          # 装核 / 初始化 API
        ├── index.vue          # <yt-x5web> 兼容模式组件
        ├── X5Web.kt           # 继承 smtt WebView
        ├── config.json
        ├── libs/
        │   └── tenxunX5-release.aar
        └── assets/tbs/        # 可选：本地内核（体积很大）
            ├── tbs_core_..._armeabi_....tbs      # armeabi-v7a，版本 46514
            └── tbs_core_..._arm64-v8a_....tbs    # arm64-v8a，版本 46515

减小 APK 体积（强烈建议阅读）

assets/tbs 下两个 .tbs 合计约 90MB+，会直接打进安装包。

方案 A：网络安装（推荐超包时使用）

1. 把 utssdk/app-android/assets/tbs/ 里的 .tbs 文件拷到本地备份
2. 从工程中删除 assets/tbs 目录（或清空其中的 .tbs），减小打包体积
3. 将 .tbs 上传到自有 CDN / 服务器，得到直链
4. 运行时用 loadUrl 按当前 ABI 下载并安装

import { checkAbiType, getX5Constants, loadUrl, forceStopAndRestartApp } from '@/uni_modules/yt-x5web'

const abi = checkAbiType()
const c = getX5Constants()
let url = ''
if (abi.code === c.ABI_ARM32) {
  url = 'https://your.cdn.com/tbs_core_armeabi.tbs'      // 46514
} else if (abi.code === c.ABI_ARM64) {
  url = 'https://your.cdn.com/tbs_core_arm64-v8a.tbs'    // 46515
}

loadUrl({
  coreVersion: abi.coreVersion,
  url: url,
  Update: (p) => { console.log('progress', p) },
  success: (msg) => {
    console.log('install ok', msg)
    forceStopAndRestartApp({ delayMs: 1500 })
  },
  fail: (code, msg) => { console.error(code, msg) }
})

方案 B：只兼容一种架构

若 App 只发一种 ABI（例如仅 arm64-v8a，或仅 armeabi-v7a）：

1. 打开 utssdk/app-android/assets/tbs/
2. 删除不需要的那一个 .tbs 文件
   • 只保留 32 位：删除 *arm64-v8a*.tbs
   • 只保留 64 位：删除 *armeabi*.tbs
3. 打包体积约可减少一半

注意：删除后，对应架构的设备无法本地装核；请配合云打包 ABI 过滤，或改用网络安装兜底。

推荐业务流程

App 启动尽早 prepareBeforeInit()
        ↓
canLoadX5() === false ?
        ↓ 是
loadLocalForCurrentAbi() 或 loadLocal() 或 loadUrl()
        ↓
forceStopAndRestartApp()   ← 装核成功后必须重启进程
        ↓
重启后 canLoadX5() === true
        ↓
initX5Environment()
        ↓
用 <yt-x5web> 打开页面，看 @pagefinish 的 isX5Core / ua（UA 应含 TBS/）

一、装核 / 初始化 API

引入方式

// 按需
import {
  prepareBeforeInit,
  canLoadX5,
  loadLocalForCurrentAbi,
  loadLocal,
  loadUrl,
  initX5Environment,
  forceStopAndRestartApp,
  getCurrentCoreName,
  getX5Constants,
  checkAbiType,
  diagnose
} from '@/uni_modules/yt-x5web'

// 或命名空间
import * as X5Web from '@/uni_modules/yt-x5web'
X5Web.prepareBeforeInit()

不要直接 import { ABI_ARM32 } from '...'，请用 getX5Constants()。

API 一览

1. getX5Constants()

无参数。返回常量对象。

const c = getX5Constants()
// c.ABI_ARM32 / ABI_ARM64 / ABI_OTHER
// c.CORE_VERSION_ARM32=46514  CORE_VERSION_ARM64=46515
// c.ASSET_ARM32 / ASSET_ARM64 / ASSET_DIR / FILE_ARM32 / FILE_ARM64

2. checkAbiType()

无参数。返回：

const abi = checkAbiType()
console.log(abi.code, abi.coreVersion, abi.assetPath)

3. prepareBeforeInit() / applyTbsSettings() / makeTbsDexReadOnly()

无参数，无返回值。建议启动时先 prepareBeforeInit()。

prepareBeforeInit()
applyTbsSettings()      // 可选
makeTbsDexReadOnly()    // 可选，异常时再试

4. diagnose() / canLoadX5() / 版本与内核查询

const d = diagnose()
console.log(d.message)           // 可读多行诊断文本
console.log(d.canLoadX5, d.tbsVersion, d.assetExists)

const r = canLoadX5()
console.log(r.can, r.detail)

console.log(getTbsVersion())
console.log(getCurrentCore())      // { type, isX5, message, ... }
console.log(getCurrentCoreName())
console.log(isUsingX5Core())
console.log(isX5InitFinished())
console.log(getLastInitIsX5())

5. initX5Environment(options?)

传 null 或不传表示无回调预热。

if (canLoadX5().can) {
  initX5Environment({
    success: (isX5) => { console.log('init done, isX5=', isX5) },
    complete: (isX5) => { console.log('complete', isX5) }
  })
}

6. loadLocalForCurrentAbi(options) — 本地自动装核

按当前 ABI 自动选择 assets/tbs 内对应文件。

loadLocalForCurrentAbi({
  isCanLoadX5: (can) => console.log('before canLoad=', can),
  Update: (p) => console.log(p),
  success: (msg) => {
    console.log(msg)
    forceStopAndRestartApp({ delayMs: 1500 })
  },
  fail: (code, msg) => console.error(code, msg)
})

7. loadLocal(options) — 指定 assets 路径装核

const abi = checkAbiType()
loadLocal({
  coreVersion: abi.coreVersion,
  assetPath: abi.assetPath,
  Update: (p) => {},
  success: (msg) => forceStopAndRestartApp(null),
  fail: (code, msg) => {}
})

8. loadUrl(options) — 网络装核

见上文「减小 APK 体积 → 方案 A」。

9. forceStopAndRestartApp(options?) / killProcess() / resetCore()

// 装核成功后：延迟拉起（建议 delayMs ≥ 800，默认 1500）
forceStopAndRestartApp({ delayMs: 1500 })
forceStopAndRestartApp(null) // 使用默认延迟

killProcess()   // 只杀进程，不自动拉起
resetCore()     // 重置内核相关状态

二、组件 <yt-x5web>

真正的腾讯 smtt WebView，不是系统 <web-view>。

使用限制

• uni-app：只能写在 .nvue 页面
• uni-app-x：只能写在 .uvue 页面
• 必须给组件明确宽高（如 width:750rpx;height:600px）；仅靠 flex:1 时高度常为 0（能 load 但看不见）

属性

组件方法（ref 调用）

返回值差异：

• uni-app-x：可直接使用方法的 同步 return
• uni-app（nvue）：同步 return 不可靠，请监听下方「方法结果事件」里的 result

带返回值的方法会 同时 return + $emit 同名事件（不做环境判断）。

页面生命周期事件

方法结果事件

调用带返回值的方法后触发，参数 Map 统一为 result：

示例：uni-app（nvue）

<template>
  <view class="page">
    <yt-x5web
      ref="x5"
      :src="url"
      :style="'width:750rpx;height:' + webHeight + 'px;'"
      @pagestart="onPageStart"
      @pagefinish="onPageFinish"
      @error="onError"
      @progress=""
      @getisx5core="onGetIsX5Core"
      @getuseragent="onGetUserAgent"
      @cangoback="onCanGoBack"
      @goback="onGoBack"
    ></yt-x5web>
  </view>
</template>

<script>
export default {
  data() {
    return { url: 'https://www.baidu.com', webHeight: 600 }
  },
  onReady() {
    setTimeout(() => {
      const x5 = this.$refs.x5
      if (x5 && x5.loadUrl) x5.loadUrl(this.url)
    }, 400)
  },
  methods: {
    pick(e, key) {
      if (!e) return ''
      if (e[key] != null) return e[key]
      if (e.detail && e.detail[key] != null) return e.detail[key]
      if (typeof e.get === 'function') return e.get(key)
      return ''
    },
    onPageStart(e) {
      console.log('pagestart', this.pick(e, 'url'))
    },
    onPageFinish(e) {
      console.log('isX5=', this.pick(e, 'isX5Core'), 'ua=', this.pick(e, 'ua'))
      // nvue：用事件拿方法返回值
      this.$refs.x5 && this.$refs.x5.getIsX5Core && this.$refs.x5.getIsX5Core()
      this.$refs.x5 && this.$refs.x5.getUserAgent && this.$refs.x5.getUserAgent()
    },
    onError(e) {
      console.log('error', this.pick(e, 'description'))
    },
    (e) {
      console.log('progress', this.pick(e, 'progress'))
    },
    onGetIsX5Core(e) {
      console.log('getIsX5Core result=', this.pick(e, 'result'))
    },
    onGetUserAgent(e) {
      console.log('UA result=', this.pick(e, 'result'))
    },
    onCanGoBack(e) {
      console.log('canGoBack result=', this.pick(e, 'result'))
    },
    onGoBack(e) {
      console.log('goBack result=', this.pick(e, 'result'))
    }
  }
}
</script>

示例：uni-app-x（uvue）

事件参数请声明为 Map<string, any>；方法可直接拿同步返回值。

<template>
  <view class="page">
    <yt-x5web
      ref="x5"
      :src="url"
      :style="'width:750rpx;height:' + webHeight + 'px;'"
      @pagestart="onPageStart"
      @pagefinish="onPageFinish"
      @error="onError"
      @progress=""
      @getisx5core="onGetIsX5Core"
      @getuseragent="onGetUserAgent"
    ></yt-x5web>
  </view>
</template>

<script>
type YtX5webRef = {
  loadUrl: (url: string) => void
  getIsX5Core: () => boolean
  getUserAgent: () => string
  goBack: () => boolean
  canGoBack: () => boolean
  getUrl: () => string
}

export default {
  data() {
    return {
      url: 'https://www.baidu.com',
      webHeight: 600 as number,
      info: ''
    }
  },
  onReady() {
    setTimeout(() => {
      const x5 = this.$refs['x5'] as YtX5webRef | null
      if (x5 != null) {
        x5.loadUrl(this.url)
      }
    }, 400)
  },
  methods: {
    pick(e: Map<string, any> | null, key: string): any | null {
      if (e == null) return null
      return e.has(key) ? e.get(key) : null
    },
    onPageStart(e: Map<string, any>) {
      console.log('pagestart', this.pick(e, 'url'))
    },
    onPageFinish(e: Map<string, any>) {
      console.log('isX5=', this.pick(e, 'isX5Core'), 'ua=', this.pick(e, 'ua'))
      // uni-app-x：可直接用 return
      const x5 = this.$refs['x5'] as YtX5webRef | null
      if (x5 != null) {
        console.log('method isX5=', x5.getIsX5Core(), 'ua=', x5.getUserAgent())
      }
    },
    onError(e: Map<string, any>) {
      console.log('error', this.pick(e, 'description'))
    },
    (e: Map<string, any>) {
      console.log('progress', this.pick(e, 'progress'))
    },
    onGetIsX5Core(e: Map<string, any>) {
      console.log('@getisx5core', this.pick(e, 'result'))
    },
    onGetUserAgent(e: Map<string, any>) {
      console.log('@getuseragent', this.pick(e, 'result'))
    }
  }
}
</script>

常见问题

Q: canLoadX5 为 true，但页面还是系统内核？ A: 系统 <web-view> 在 HBX 5.x 上常无法切到 X5。请改用 <yt-x5web>，或将 HBX 降到 4.x 再验证系统 web-view。

Q: 组件白屏 / 看不见内容？ A: 检查是否给了明确 px 高度；确认页面是 nvue（uni-app）或 uvue（uni-app-x）。

Q: 装核成功但下次启动仍不可用？ A: 安装成功后必须 forceStopAndRestartApp()，让新进程加载已安装内核。

Q: 如何确认真的在用 X5？ A: 看 @pagefinish 的 isX5Core===true，或 UA 字符串中包含 TBS/；也可调 getIsX5Core() / getCurrentCoreName()。

Q: Android 14+ 装不上？ A: 本插件附带的免费旧核主要面向 Android 5–13；更高系统可能无法加载，需自行评估更换内核方案。

更多好用插件推荐

• 高德定位连续定位后台定位保活定位
• 百度汽车摩托车导航插件
• 百度鹰眼轨迹插件支持后台采集、保活
• 百度定位插件、连续定位、保活、坐标系转换、支持双端
• 计步器插件，支持Android、iOS双端
• uts经典蓝牙插件、蓝牙电子秤
• 获取唯一标识、ServiceID、卸载更新不变iOS+Android
• Android经典蓝牙
• 华为ScanKit统一扫码插件支持iOS+Android原生插件
• 【华为扫码】统一扫码插件支持多码连续扫码支持半屏扫码uts插件iOS+Android+HarmonyOS
• 截屏、录屏、防截屏、录屏iOS、Android
• 人脸采集插件 最新百度SDK 离线人脸采集、活体检测
• 页面截长图、截取WebView内容，生成长截图Android+iOS
• Android无预览拍照、录制、静默拍照、静默录制、抓拍插件支持
• uni高德地图功能拓展地图截图
• 科大讯飞离线合成插件支持iOS、android
• iOS保活Android保活鸿蒙保活定位插件系统定位
• 高德定位、猎鹰轨迹插件
• 海康威视综合安防平台视频播放插件
• 支持NFC读写功能检测支持Android iOS HarmonyOS
• 自定义相机
• VLC视频播放器-兼容式组件
• VLC视频播放器-标准模式组件
• 桌面小组件
• 海康网络摄像头
• 百度OCR
• 录音pcm播放插件
• 原生离线语音合成原生TTS
• 科大讯飞离线语音合成、识别插件
• 科大讯飞离线语音听写

Demo

• uni-app：pages/x5webview/x5webview.nvue（同级 X5Demo 工程）
• uni-app-x：pages/x5wbview/x5webview.uvue（同级 X5Uniapp-x 工程）
• 首页可完整试装核 API：pages/index