最常见原因是通信通道未建立：未启用脚本（enableScripts: false）、onDidReceiveMessage注册过晚、CSP拦截、未调用acquireVsCodeApi()、webview已销毁或数据不可序列化。
webview.postMessage 为什么没被主进程收到？
最常见的情况是消息发出去了，但 webview.onDidReceiveMessage 根本没触发——这通常不是代码写错了，而是通信通道压根没建好。
- 确保创建 Webview 时传入的
enableScripts: true，否则 JS 不执行，vscode.postMessage就是空操作 -
webview.onDidReceiveMessage必须在createWebviewPanel返回后立即注册，不能等 DOM 加载完再绑；延迟注册会漏掉初始化阶段的消息（比如页面 onload 后立刻发的配置） - 检查是否误用了
window.addEventListener('message', ...)去监听主进程发来的消息：这是错的，主进程发消息用的是webview.postMessage，前端要靠window.addEventListener('message', ...)接收，但反过来不成立 - 如果插件有多个 Webview 实例，确认你监听的是对应 panel 的实例，而不是全局或旧 panel 的引用（容易因重开面板导致监听丢失）
主进程发消息到 webview，前端收不到？
这类问题往往卡在 CSP（Content Security Policy）或资源加载阶段，消息根本没机会进 JS 执行环境。
- 必须在 HTML 中显式调用
acquireVsCodeApi()，且只能调用一次；没这句，vscode.postMessage和vscode.getState全部无效 - CSP 配置错误会直接拦截
postMessage监听器注册。检查webview.options是否设置了enableScripts: true，并确认 HTML<meta>或<script>标签里没有拼错 CSP 值（如误写script-src 'self'而没加vscode-webview:协议） - 主进程调用
webview.postMessage(data)时，若webview已销毁（比如用户关掉了面板），该调用静默失败，无报错；建议加if (!webview?.visible) return;防御 - 数据不可序列化（如含
function、undefined、Symbol或循环引用对象）会导致消息被丢弃，控制台也不报错；用JSON.stringify(data)预检可避免
如何在 DevTools 里断点调试 webview 的消息流？
VSCode 的 Webview DevTools 不支持直接 attach 到源码 TS 文件，但可以高效定位运行时问题。
- 打开 Webview 后按
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入 “Developer: Open Webview Developer Tools”，选中当前面板 - 在 DevTools 的 Sources 面板里，找到
vscode-webview://开头的脚本，直接打断点；注意不要在动态插入的<script>字符串里设断点（它不会映射） - 在 Console 里手动测试通信：
vscode.postMessage({type:'test'})看主进程是否响应；或在主进程加console.log('received:', e)配合event.data检查原始 payload 结构 - 如果消息收发都正常但 UI 没反应，大概率是前端状态更新逻辑没触发 re-render（比如 React 组件没用
useState或useEffect响应message事件）
跨平台下 postMessage 数据结构不一致怎么办？
Windows/macOS/Linux 上 V8 引擎对 postMessage 序列化的容忍度不同，尤其涉及日期、正则、Map/Set 时，行为可能分裂。
- 永远只传 plain object、array、string、number、boolean、null；避免 Date（转成 ISO 字符串）、RegExp（转成
{ pattern: '', flags: '' }）、Map/Set（转成 array of entries） - 主进程和 Webview 双端统一使用一个类型守卫函数校验消息，例如：
function isValidMessage(msg: unknown): msg is { type: string; payload?: any } { return typeof msg === 'object' && msg !== null && 'type' in msg; } - 在 Windows 上遇到
postMessage后数据字段消失？检查是否用了Object.defineProperty设置了不可枚举属性——序列化只保留可枚举字段 - Android/iOS 真机调试暂不支持 Webview DevTools，此时建议在消息体里加
debug: process.env.NODE_ENV === 'development'字段，主进程根据该标记决定是否写日志到输出通道
