原生能力在现代前端开发中的实战应用与常见陷阱

我的写法，亲测靠谱

原生能力调用，尤其是 Hybrid 场景下（比如 WebView 里调 JSBridge），我踩过最多坑的地方不是「怎么调」，而是「什么时候能调」「调了为什么没反应」「为什么 iOS 正常 Android 报错」——这仨问题加起来，够我改三天夜。

我现在项目里统一用这套封装，跑了快一年，线上零 crash，灰度期也没人反馈「拍照失败」「定位没响应」这类问题。核心就三点：兜底、防重、异步对齐。

先上最常用也最容易翻车的「调相机」代码：

// 统一 bridge 调用入口（简化版，实际项目里会挂到 window.$bridge）
function invokeNative(method, params = {}, options = {}) {
  const { timeout = 5000, retry = 1 } = options;
  
  return new Promise((resolve, reject) => {
    // 防重：同一个请求正在 pending 中，直接 reject
    const key = ${method}_${JSON.stringify(params)};
    if (window._bridgePending && window._bridgePending[key]) {
      return reject(new Error('bridge request duplicated'));
    }

    const timer = setTimeout(() => {
      delete window._bridgePending?.[key];
      reject(new Error(bridge timeout: ${method}));
    }, timeout);

    window._bridgePending = window._bridgePending || {};
    window._bridgePending[key] = true;

    // 这里才是真正发给 native 的逻辑（iOS/Android 不同，但上层不用管）
    if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.invoke) {
      // iOS WKWebView
      try {
        window.webkit.messageHandlers.invoke.postMessage({
          method,
          params,
          callbackId: key
        });
      } catch (e) {
        clearTimeout(timer);
        delete window._bridgePending[key];
        reject(e);
      }
    } else if (window.JSBridge) {
      // Android WebViewClient 注入的 JSBridge
      window.JSBridge.invoke(method, params, (res) => {
        clearTimeout(timer);
        delete window._bridgePending[key];
        if (res.code === 0) {
          resolve(res.data);
        } else {
          reject(res);
        }
      });
    } else {
      clearTimeout(timer);
      delete window._bridgePending[key];
      reject(new Error('no native bridge available'));
    }
  });
}

// 使用示例：打开相机
async function openCamera() {
  try {
    const result = await invokeNative('camera.takePhoto', {
      quality: 0.8,
      allowEdit: true
    }, { timeout: 8000 });

    // result 是 native 返回的 base64 或文件路径，按业务处理
    console.log('拍完了', result);
    return result;
  } catch (err) {
    console.error('调相机失败', err);
    // 这里可以 fallback 到 input[type=file]，别硬扛
    return fallbackToInput();
  }
}

为什么这么写？因为我在三个项目里都吃过亏：

• 没防重：用户手抖连点两次「拍照」，native 层收到两个指令，结果只返回一个 callback，另一个永远 pending；
• 没超时：Android 某些低版本 WebView 在 native crash 后不回调，JS 卡死，整个页面白屏；
• 没降级：相机权限被拒、系统禁用摄像头、甚至某些厂商 ROM 把 camera API 给阉了 —— 这时候不 fallback，用户就只能关网页。

这几种错误写法，别再踩坑了

下面这些，全是我自己亲手写过、上线后被打脸的写法，列出来当反面教材：

❌ 错误写法一：直接 window.location.href 跳 native 协议

早期为了省事，写过这种：

window.location.href = 'myapp://camera?quality=0.8';

结果 iOS 13+ 直接拦截，Android 8+ 也会弹「未知来源应用」警告，而且根本拿不到返回结果。更惨的是，有些厂商 ROM（比如华为 EMUI）看到这个跳转会直接杀掉 WebView 进程。别试，真不行。

❌ 错误写法二：callback 写成匿名函数 + 没清引用

以前这么干过：

window.JSBridge.invoke('getLocation', {}, function(res) {
  console.log(res);
});

问题在哪？每次调用都注册新函数，native 回调时找不到旧函数引用（尤其在 SPA 页面跳转后），内存泄漏 + callback 丢失。现在一律用唯一 callbackId 字符串 + 全局 map 管理。

❌ 错误写法三：拿到 native 返回就直接 JSON.parse

native 返回的 data 字段，有时候是 string，有时候是 object，取决于 native 层有没有帮你序列化。我之前在小米某机型上遇到过 native 返回的是未 stringify 的对象，JSON.parse 直接报错。现在统一加一层类型判断：

function safeParse(data) {
  if (typeof data === 'string') {
    try {
      return JSON.parse(data);
    } catch (e) {
      return data; // 原样返回，不 throw
    }
  }
  return data;
}

实际项目中的坑

说几个让我半夜改完又睡不着的细节：

• iOS WKWebView 的 postMessage 有长度限制：超过 2MB 直接静默失败。我们有个项目要传整张高清图 base64，最后改成 native 先存本地，JS 只收个临时路径；
• Android 微信 X5 内核不支持 messageHandlers：必须检测 window.qbjs 或走 X5 自定义方案，否则白屏；
• 定位权限状态不能只靠 native 返回：iOS 14+ 用户可能点了「仅在使用期间」，但 native 仍返回 success，实际后台无法持续获取。我们加了定时 checkLocationEnabled() 主动轮询；
• 唤起 App 失败没提示：window.location.href = 'myapp://' 失败时没有任何回调。现在统一用 iframe src + setTimeout 检测 visibilitychange，失败就引导用户手动打开。

还有一个血泪教训：千万别信 native 同学说的「这个 API 所有版本都支持」。我们曾经因为一个 getBatteryStatus 接口，在 vivo Y70（Android 11）上发现系统返回 null 而不是抛异常，导致 JS 里 res.level.toFixed() 直接崩。后来所有字段访问前都加了空值检查：

const level = res?.level ?? 0;

关于 jztheme.com 的一点说明

我们项目里有些接口地址配在 JS 里，比如：

const API_URL = 'https://jztheme.com/api';

这只是个技术演示用的域名示例，跟任何公司或团队无关，纯属 placeholder。别搜，也别点，它不指向任何真实服务 —— 就是个写 demo 时随手敲的字符串。

结语

以上是我过去一年在多个 Hybrid 项目中，围绕原生能力调用总结出的核心实践。没有银弹，只有「少踩坑 + 快降级 + 易排查」。有些方案看起来啰嗦（比如每个 bridge 调用都带 timeout 和防重），但线上事故少了，晚上就能早睡半小时。

这个封装目前还在迭代，比如最近加了离线队列（网络断开时暂存请求）、自动重试策略（针对 network error）。如果你有更好的思路，比如怎么优雅处理 native 层升级后的 API 不兼容，或者怎么在 Vue/React 里更好地封装 bridge hooks，欢迎评论区交流 —— 我真的会一条条看，有启发的马上加进我们内部 Wiki。

以上是我踩坑后的总结，希望对你有帮助。