React+WebView白屏/404/通信失效的根本原因是VSCode Webview沙盒机制与前端常规逻辑冲突；需严格匹配viewType、正确配置localResourceRoots、所有资源用asWebviewUri转换、消息通信经vscode API中转、注入nonce适配CSP、监听主题变化同步变量。
React + WebView 能跑起来，但默认配置下大概率白屏、404、postMessage 失效——根本原因不是 React 有问题，而是 VSCode Webview 的沙盒机制和资源加载规则与前端常规开发逻辑天然冲突。
createWebviewPanel 参数必须对齐 package.json 声明
面板创建后秒退或无法响应命令，90% 出在 viewType 不匹配。它不是随便起的字符串，必须和 package.json 中 contributes.webviews 下声明的值完全一致（大小写、空格、连字符都不能差）。
-
viewType若漏声明，createWebviewPanel不报错，但面板会在渲染前被主进程静默销毁 -
viewColumn传undefined或非法值（如-1）会导致 fallback 到默认列，但webview.onDidDispose可能不触发，造成内存泄漏 -
options中enableScripts: true是硬性前提；localResourceRoots必须是vscode.Uri[]，传字符串路径会直接抛"Invalid URI"
React 构建产物必须用 asWebviewUri 转换所有静态资源
直接把 build/index.html 读出来塞进 webview.html，CSS 和 JS 一定 404。VSCode Webview 不识别相对路径，也不允许 file:// 协议——所有资源都得走 webview.asWebviewUri() 显式转换。
- 入口 HTML 文件本身也要转：
webview.asWebviewUri(vscode.Uri.file(path.join(context.extensionPath, 'build', 'index.html'))) - CSS 中的
@import、字体url()、图片src都得单独构造vscode.Uri再转，不能只转 HTML -
context.extensionUri是唯一可靠的插件根路径，别用__dirname，打包后它指向临时目录
React 应用内通信必须绕过全局作用域直连
React 组件里不能直接调用 vscode.window.showInformationMessage，也不能用 fetch 请求本地文件——Webview 是隔离沙箱，所有跨边界操作必须经消息中转。
- 前端需在
useEffect里调用window.acquireVsCodeApi()（且只能调一次），否则vscode.postMessage静默失败 - 主进程监听用
webview.onDidReceiveMessage，推荐绑定到context.subscriptions自动清理 - 消息体只能是可序列化纯对象：禁止传
function、Date、RegExp、undefined、DOM 节点 - 敏感操作（如写文件、执行终端命令）必须在主进程校验参数合法性，WebView 发来的数据一律不可信
CSP 与主题适配是上线前最容易翻车的环节
样式错乱、按钮不响应、控制台报 CSP 错误，往往是因为没处理好两件事：nonce 注入和主题变量注入。
- HTML 模板中每个
<script>和<style>标签必须带nonce属性，且值要和webview.options中设置的cspSource匹配，否则脚本被拦截 - React 组件想适配 VSCode 当前主题（比如深色/浅色），不能靠
prefers-color-scheme，得监听vscode.workspace.onDidChangeConfiguration并把主题色变量通过postMessage推给前端 - 第三方 UI 库（如 MUI、Ant Design）的默认样式大概率被 VSCode 主题 CSS 覆盖，要用
!important或 shadow DOM 封装
真正难的不是让 React 渲染出来，而是让整个链路在 VSCode 的沙盒约束下稳定运转：资源路径、消息时序、CSP 策略、主题同步，任何一环松动都会导致白屏或交互失效。调试时优先看浏览器控制台的 CSP 报错和 Network 面板的 404 请求，而不是查 React 报错。
