微信小程序 WebView 双向通信实战指南 | 极客日志

JavaScriptWeChat大前端

微信小程序 WebView 双向通信实战指南

微信小程序通过 WebView 组件嵌入网页时，需借助 postMessage 实现原生与页面的数据交互。核心在于配置域名白名单、引入微信 JS-SDK 并封装消息桥接类。需注意 bindmessage 事件的延迟触发特性，高频场景建议采用 URL 参数或 WebSocket 方案。同时应严格校验数据来源以防 XSS 攻击，确保通信安全与实时性。

指针猎手发布于 2026/3/29更新于 2026/4/274 浏览

微信小程序 WebView 双向通信实战指南

需求背景

在微信小程序中嵌入 web-view 组件是常见场景，但原生代码与内嵌网页之间的数据交互往往需要精心设计。虽然官方提供了 postMessage 接口，但在实际工程中直接调用容易遇到延迟、类型安全及维护性问题。本文基于多年实战经验，梳理一套稳定、可扩展的通信方案。

基础配置

通信前需确保环境合规，否则消息会被静默丢弃。

小程序端配置

在 app.json 或页面配置文件中声明权限：

{
  "usingComponents": {},
  "permission": {
    "scope.webView": {
      "desc": "用于网页和小程序通信"
    }
  }
}

网页端配置

内嵌 H5 页面必须引入微信 JS-SDK，并校验域名白名单。

<!-- 引入官方 SDK -->
<script src="https://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>

注意：务必在微信公众平台后台配置合法域名，否则 wx.miniProgram 对象可能不可用。

通信实现

原生 API 调用

小程序向网页发送

通过 selectComponent 获取实例后调用 postMessage：

// page.js
Page({
  data: { webViewUrl: 'https://your-domain.com/page.html' },
  
  onLoad() {
    // 初始化逻辑
  },

  sendToWebPage() {
     webview = .();
     (webview) {
      webview.({
        : {
          : ,
          : ,
          : .()
        }
      });
    }
  },

  () {
    .(, e..);
     { type, data } = e..;
     (type === ) {
      
    }
  }
});

<web-view src="{{webViewUrl}}" bindmessage="onMessage" bindload="onWebViewLoad" />
<button bindtap="sendToWebPage">发送消息到网页</button>

// H5 页面脚本
document.addEventListener('message', function(e) {
  const data = e.data;
  console.log('收到小程序消息:', data);

  if (data.type === 'from_miniprogram') {
    // 执行操作
    if (window.wx && window.wx.miniProgram) {
      window.wx.miniProgram.postMessage({
        data: {
          type: 'from_web',
          reply: 'Message received!',
          original: data.message
        }
      });
    }
  }
});

function sendToMiniProgram() {
  if (window.wx && window.wx.miniProgram) {
    window.wx.miniProgram.postMessage({
      data: {
        type: 'user_action',
        action: 'button_click',
        value: 'some_value',
        timestamp: new Date().getTime()
      }
    });
  }
}

// utils/webviewBridge.js
class WebViewBridge {
  constructor(webviewRef) {
    this.webview = webviewRef;
    this.messageHandlers = new Map();
  }

  postMessage(type, data) {
    if (!this.webview) return false;
    this.webview.postMessage({
      data: {
        type,
        payload: data,
        timestamp: Date.now(),
        source: 'miniprogram'
      }
    });
    return true;
  }

  onMessage(type, handler) {
    this.messageHandlers.set(type, handler);
  }

  handleMessage(event) {
    const { type, payload, source } = event.detail.data;
    if (source === 'web') {
      const handler = this.messageHandlers.get(type);
      if (handler) handler(payload);
    }
  }

  offMessage(type) {
    this.messageHandlers.delete(type);
  }
}

export default WebViewBridge;

// webview-bridge.js
class MiniProgramBridge {
  constructor() {
    this.handlers = new Map();
    this.init();
  }

  init() {
    document.addEventListener('message', (e) => {
      const { type, payload, source } = e.data;
      if (source === 'miniprogram') {
        this.dispatch(type, payload);
      }
    });

    window.addEventListener('beforeunload', () => {
      this.postMessage('page_unload', {});
    });
  }

  postMessage(type, data) {
    if (window.wx && window.wx.miniProgram) {
      window.wx.miniProgram.postMessage({
        data: {
          type,
          payload: data,
          timestamp: Date.now(),
          source: 'web'
        }
      });
      return true;
    }
    return false;
  }

  on(type, handler) {
    if (!this.handlers.has(type)) {
      this.handlers.set(type, []);
    }
    this.handlers.get(type).push(handler);
  }

  dispatch(type, data) {
    const typeHandlers = this.handlers.get(type);
    if (typeHandlers) {
      typeHandlers.forEach(handler => handler(data));
    }
  }

  off(type, handler) {
    const typeHandlers = this.handlers.get(type);
    if (typeHandlers) {
      const index = typeHandlers.indexOf(handler);
      if (index > -1) {
        typeHandlers.splice(index, 1);
      }
    }
  }
}

window.MiniProgramBridge = new MiniProgramBridge();

import WebViewBridge from '../../utils/webviewBridge';

Page({
  data: { url: 'https://example.com' },
  onLoad() {
    // 等待加载完成再初始化
  },
  onWebViewLoad() {
    const webview = this.selectComponent('#webview');
    this.bridge = new WebViewBridge(webview);

    // 注册监听
    this.bridge.onMessage('user_login', (data) => {
      console.log('用户登录:', data);
    });

    this.bridge.onMessage('payment_success', (data) => {
      console.log('支付成功:', data);
      wx.showToast({ title: '支付成功' });
    });
  },

  sendUserInfo() {
    this.bridge.postMessage('user_info', {
      userId: '123',
      nickname: '张三',
      avatar: 'url'
    });
  }
});

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <button onclick="sendMessage()">发送消息到小程序</button>
  <script src="https://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>
  <script src="webview-bridge.js"></script>
  <script>
    // 监听小程序消息
    MiniProgramBridge.on('user_info', (data) => {
      console.log('收到用户信息:', data);
      document.getElementById('user-name').innerText = data.nickname;
    });

    function sendMessage() {
      MiniProgramBridge.postMessage('button_click', {
        buttonId: 'submit',
        value: 'confirmed'
      });
    }

    // 通知页面已加载
    window.addEventListener('load', () => {
      MiniProgramBridge.postMessage('page_loaded', {
        title: document.title,
        url: window.location.href
      });
    });
  </script>
</body>
</html>

// H5 端
function updateState(state) {
  window.location.hash = 'state=' + encodeURIComponent(JSON.stringify(state));
  // 或使用 query 参数
  // window.history.replaceState({}, '', '/path?data=' + encodeURIComponent(JSON.stringify(state)));
}

// H5 端
function sendViaStorage(data) {
  localStorage.setItem('web_to_miniprogram', JSON.stringify({ data, timestamp: Date.now() }));
}

// 小程序端
setInterval(() => {
  const storage = wx.getStorageSync('web_to_miniprogram');
  if (storage) {
    this.handleMessage(storage.data);
    wx.removeStorageSync('web_to_miniprogram');
  }
}, 100);

const ws = new WebSocket('wss://your-server.com');
ws.onmessage = (e) => {
  // 小程序通过后端接收消息
};