VSCode集成Webview窗口显示前端项目预览-VSCode-PHP中文网

不能把本地开发服务器（如 localhost:3000）地址直接写入 webview.html 的 script src 或 iframe 中，因 vscode webview 默认 csp 仅允许 vscode-webview: 协议资源，http://localhost:3000 会被拦截导致白屏或“refused to load the script”错误。

vscode集成webview窗口显示前端项目预览

直接说结论：不能把本地开发服务器（如 localhost:3000）的地址直接写进 webview.html 的 <script src></script> 或 <iframe></iframe> 里——CSP 会拦截，页面白屏或报错 Refused to load the script。

为什么 `http://localhost:3000` 在 Webview 里加载失败

VSCode Webview 是沙盒环境，强制执行严格的 Content-Security-Policy（CSP），默认只允许加载 vscode-webview: 协议资源。任何 http:// 或 https:// 地址都会被拦截，即使你本地起了 webpack-dev-server 也不行。

错误现象：控制台出现 Refused to load the script 'http://localhost:3000/webview.js'，页面空白
根本原因：Webview 的 webview.cspSource 默认值是 vscode-webview://$(webview-csp-source)，不包含 http: 白名单
别试 webview.options = { enableScripts: true, ... } —— 这只能启用 JS 执行，不放宽 CSP

正确加载前端项目 bundle 的两种方式

必须绕过 CSP 限制，同时保证热更新可用。推荐以下路径：

PigX UI 前端开发

PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。

下载

方式一（推荐）：用 asWebviewUri 加载本地构建产物
前端用 vite build 或 webpack --mode=production 输出到 dist/，再用 webview.asWebviewUri(vscode.Uri.file(path.join(extensionPath, 'dist', 'index.html'))) 转换路径，注入 HTML 字符串中
方式二（开发期）：代理请求到 dev-server，但需改 CSP
在 webview.html 的 <meta http-equiv="Content-Security-Policy"> 中追加 connect-src http://localhost:3000;，并确保 webview.cspSource 与 meta 标签值一致（如 vscode-webview://$(webview-csp-source)）
注意：方式二仅限开发，发布扩展时必须切回方式一，否则用户安装后无法加载

`asWebviewUri` 必须对每个资源单独调用

不是只转换 HTML 文件就行——CSS、JS、图片、字体等所有 href 和 src 属性都得过一遍 asWebviewUri，否则照样 404。

常见错误：只转了 index.html，但 index.html 里引用的 ./assets/main.abc123.js 没转，结果 JS 报错 net::ERR_FILE_NOT_FOUND
正确做法：用 Node.js 读取 dist/index.html 字符串，正则替换所有相对路径（如 href="assets/style.css" → href="${webview.asWebviewUri(...)}"）
更稳妥方案：前端构建时用 base: 'vscode-resource:///'（Vite）或 publicPath: 'vscode-resource:///'（Webpack），再配合 localResourceRoots 配置

热更新怎么接？别依赖 Live Server

VSCode 自带的 Live Server 插件和 Webview 完全无关，它起的是独立 HTTP 服务，Webview 访问不了。真要热更新，得自己搭桥：

前端启动 webpack-dev-server（端口 3000），后端监听文件变化，通过 postMessage 主动通知 Webview 刷新 iframe 或重载 script 标签
或者用 vscode.workspace.onDidChangeTextDocument 监听源码变更，触发 webview.postMessage({ type: 'reload' })，前端接收后 location.reload()
注意：Webview 的 retainContextWhenHidden: true 会影响热更新行为——隐藏后再打开可能还是旧状态，建议开发期设为 false

最麻烦的其实不是代码，而是路径拼写和 CSP 元标签的大小写、空格、分号——少一个分号，整个策略失效；vscode-webview:// 写成 vscode-webview:/ 就加载不了资源。这些细节没报错，只静默失败。