XuqmGroup 1567c673ea feat(bugcollect): 集成符号化服务支持移动端堆栈解析

- 添加 symbolicator 服务配置到 docker-compose.yml
- 配置 bugcollect-service 连接 symbolicator URL
- 设置 symbolicator 端口映射和资源限制
- 添加源码映射文件挂载目录
- 为 RN/Android/iOS/Flutter 堆栈符号化提供支持

docs(xwebview): 更新已知问题文档

- 记录 RN 0.85 Bridgeless 模式下 react-native-blob-util 崩溃问题
- 说明 react-native-blob-util 在 JSI/TurboModule 下初始化失败原因
- 提供宿主 app 使用 XWebViewContent 替代方案
- 添加待修复方案说明

2026-06-22 17:43:00 +08:00

4.9 KiB

原始文件 Blame 文件历史

@xuqm/rn-xwebview

XuqmGroup RN SDK WebView 模块。提供增强型 WebView 组件和 JSBridge 通信能力。

安装

yarn add @xuqm/rn-xwebview react-native-webview react-native-blob-util react-native-svg

Peer dependencies：react >= 18，react-native >= 0.76，@react-navigation/native >= 7.0.0

组件

import { XWebViewScreen } from '@xuqm/rn-xwebview'

// 在导航中使用
<XWebViewScreen />
// URL 通过 openXWebView() 预设

XWebViewView — 嵌入式 WebView 组件

import { XWebViewView } from '@xuqm/rn-xwebview'

<XWebViewView
  config={{
    url: 'https://example.com',
    title: '嵌入式网页',
    jsBridgeName: 'XWebViewBridge',
  }}
/>

XWebViewProgress — 进度条

import { XWebViewProgress } from '@xuqm/rn-xwebview'

<XWebViewProgress progress={50} />

API

API	说明
`openXWebView(url, options?)`	打开 WebView 页面
`setXWebViewController(controller)`	设置全局 WebView 控制器
`getXWebViewConfig()`	获取当前 WebView 配置
`XWebViewControl`	WebView 控制器类

XWebViewConfig 参数

参数	类型	说明
`url`	string	初始加载地址
`title`	string	页面标题
`jsBridgeName`	string	JS 桥接对象名（默认 `'XWebViewBridge'`）
`hideToolbar`	boolean	隐藏顶栏
`userAgent`	string?	自定义 User-Agent
`injectedJavaScript`	string?	页面加载后注入的 JS
`onMessage`	(event) => void	H5 发送消息回调

JSBridge 通信

// H5 → Native
window.XWebViewBridge.postMessage(JSON.stringify({ type: 'login', token: '...' }))

// Native → H5
controller.postMessageToWeb("window.dispatchEvent(new CustomEvent('nativeMsg', { detail: { key: 'value' } }))")

内置 JSBridge Handler

Action	说明	参数
`xuqm.getDeviceInfo`	获取设备信息	—
`xuqm.getToken`	获取当前用户 token	—
`xuqm.getUserInfo`	获取用户信息	—
`xuqm.openNativePage`	打开原生页面	`{ route, params? }`
`xuqm.closeWebView`	关闭 WebView	—
`xuqm.showToast`	显示 Toast	`{ message }`
`xuqm.scanQRCode`	打开扫码页（需宿主注册 handler）	—

文件下载

XWebView 内置文件下载支持，自动拦截以下场景：

URL 以常见下载扩展名结尾（.pdf, .zip, .apk 等）
<a download="..."> 标签点击
blob: URL 下载（通过 injected JS 拦截）

使用 `handleDownloadRequest`

import { handleDownloadRequest } from '@xuqm/rn-xwebview'

const handle = await handleDownloadRequest(url, hintFilename, {
  autoDownload: true,
  downloadConflict: 'rename',
  onDownloadProgress: (p) => console.log(`${p.percentage}%`),
  onDownloadComplete: (r) => console.log('saved to', r.filePath),
  onDownloadError: (url, err) => console.error(err),
})
// handle?.cancel() 可取消下载

XWebViewConfig 下载相关参数

参数	类型	说明
`autoDownload`	boolean	自动下载（默认 true），false 时需 onDownloadDecide
`downloadConflict`	`'rename' \| 'overwrite'`	文件名冲突策略（默认 rename）
`onDownloadStart`	(request) => void	下载开始回调
`onDownloadProgress`	(progress) => void	下载进度回调
`onDownloadComplete`	(result) => void	下载完成回调
`onDownloadError`	(url, error) => void	下载失败回调
`onDownloadDecide`	(request) => Decision	非自动模式下的下载决策回调

低级 API

API	说明
`fetchDownloadInfo(url, hintFilename?)`	HEAD 请求获取文件名/MIME/大小
`saveBase64File(base64, filename, savePath?, conflict)`	保存 base64 数据为文件
`startDownload(url, filename, savePath?, conflict, onProgress, onComplete, onError)`	开始下载，返回 DownloadHandle

详细 handler 列表见 @xuqm/rn-common 的 xwebview/ 目录。

已知问题

RN 0.85 Bridgeless 模式下 `react-native-blob-util` 崩溃

现象：宿主 app 使用 RN 0.85 Bridgeless 模式时，引入 XWebViewView 会触发 XWebViewDownload.ts 中 react-native-blob-util 的模块级初始化，导致 Cannot read property 'getConstants' of null。

根因：react-native-blob-util 目前在 RN 0.85 JSI/TurboModule 路径下 ReactNativeBlobUtil 原生模块为 null，PackageList.java 的旧架构注册方式不足以在 Bridgeless 模式下完成初始化。

临时方案：宿主 app 的 XWebViewContent 直接使用 react-native-webview，跳过 XWebViewView，功能对等（无下载拦截和 JSBridge，纯内容展示场景够用）。

待修复：

升级 react-native-blob-util 到支持 Bridgeless 的版本，或
在 XWebViewDownload.ts 中对 ReactNativeBlobUtil 为 null 做防御，延迟到实际下载时才初始化

4.9 KiB 原始文件 Blame 文件历史 Unescape Escape