最常见误判是 createWebviewPanel 返回后立即 dispose；实际需等待 webview 初始化完成，应在 panel.onDidDispose 中清理并加入 context.subscriptions 管理。
createWebviewPanel 返回后立即 dispose 是最常见误判
很多人以为调用 vscode.window.createWebviewPanel 就等于面板“已就绪”，其实不然。面板对象创建成功，但其内部 Webview 渲染上下文可能尚未初始化完成，此时若在返回值上直接绑定 onDidDispose 并立刻执行清理逻辑（比如清空缓存、关闭子进程），大概率会漏掉真实销毁事件——因为真正的销毁可能发生在几毫秒后，而监听器还没来得及注册完。
正确做法是：在 panel.webview.onDidReceiveMessage 或 panel.onDidChangeViewState 触发后再确认状态；或更稳妥地，在 panel.onDidDispose 回调里做清理，并确保该回调被加入 context.subscriptions 自动管理。
- 不要在
createWebviewPanel后同步调用panel.dispose()测试生命周期——这会触发静默 fallback，不走完整流程 - 如果面板因 viewColumn 不可用（如编辑器只开一列）而 fallback 到其他列，
onDidDispose仍应被触发，但需注意panel.viewColumn值已变 - 未加入
context.subscriptions的监听器，即使面板关闭也不会自动移除，容易引发内存泄漏
忘记取消 onDidReceiveMessage 监听导致重复响应
webview.onDidReceiveMessage 是长期监听器，只要面板没销毁就会持续接收消息。如果每次打开面板都重新注册（比如在命令回调里反复调用 panel.webview.onDidReceiveMessage(...)），旧监听器不会自动注销，新旧多个监听器会同时响应同一条消息，造成逻辑错乱、重复提交、状态冲突等现象。
典型表现：点击一次按钮，插件执行了三次 vscode.workspace.openTextDocument；或者前端发一次 { type: 'save' }，后端收到三份相同 payload。
- 必须确保每个监听器只注册一次——推荐在
createWebviewPanel后立即注册，并把返回的Disposable推入context.subscriptions - 不要在
panel.webview.html = ...重赋值后重新监听，HTML 替换不会清空已注册的监听器，但可能让前端重复发送消息 - 若需动态切换监听逻辑（如不同面板模式），应先调用前一个
Disposable.dispose()，再注册新的
资源路径转换遗漏导致 dispose 时残留网络请求
当 Webview 加载了未通过 webview.asWebviewUri() 转换的资源（例如硬编码 ./script.js 或 file://...），浏览器会因 CSP 拦截而不断重试加载，产生 404 请求队列。这些请求在面板 dispose 后仍可能滞留在渲染进程中，表现为 DevTools Network 面板里持续出现失败请求，甚至拖慢整个 VSCode 响应速度。
这类残留不是内存泄漏，但属于“隐性资源占用”，且难以定位——因为控制台报错早被刷走，而面板 UI 已关闭。
- 所有
<script src>、<link href>、<img src>中的路径，只要来自插件本地，就必须经webview.asWebviewUri(vscode.Uri.file(...))转换 -
localResourceRoots只控制哪些路径“允许被转换”，不等于“自动转换”；漏配会导致asWebviewUri返回无效 URI - 开发阶段可临时加一句
console.log('loading:', uri.toString())在资源加载前验证 URI 格式是否为vscode-webview://
子进程/定时器未随面板销毁而终止
Webview 面板常需配合后台任务：比如轮询服务状态、监听文件变化、启动轻量 CLI 子进程。这些任务若仅靠前端 JS 控制启停，一旦面板异常关闭（如用户强制关 tab、VSCode 崩溃重启），它们极易变成孤儿进程或悬挂定时器。
尤其要注意 VSCode 的 SIGTERM 信号只发给主扩展进程，不自动透传给子进程——你得自己在 panel.onDidDispose 里显式调用 childProcess.kill() 或 clearInterval()。
- 所有子进程必须保存引用（如
let serverProc: ChildProcess），并在panel.onDidDispose中检查并.kill('SIGTERM') - 使用
setInterval时，务必用let timerId: NodeJS.Timeout记录，并在 dispose 时clearInterval(timerId) - 避免在 Webview 内 JS 中直接
fetch长连接或 SSE，这类连接不会随面板关闭自动中断，必须由主进程代理并可控终止
