在 VS Code 扩展里安全嵌入 Vue SPA#

这篇文章以“角色卡管理器”为例，演示如何把一个由 Vite 构建的 Vue 单页应用（SPA）无缝嵌入到 VS Code 扩展的 Webview 中，并系统性解决三大痛点：

静态资源路径：确保脚本、样式、图片、动态导入都能正确加载
CSP 限制：在安全的前提下允许必需的资源与请求
Webview ↔ 扩展通信：与扩展后端可靠地交换数据

项目结构建议#

1
packages/
2
  webview/                  # Vue + Vite 前端工程
3
    dist/spa/               # 产物目录（被扩展引用）
4
src/
5
  extension/                # 扩展端代码
6
  media/                    # 运行时辅助脚本（resource-mapper.js 等）

扩展端通过 localResourceRoots 允许访问 dist/spa 与 media，并把 index.html 读入后重写资源路径与注入 CSP。

创建与复用 WebviewPanel#

📄 CC BY-NC 4.0

1
// 代码示例 - 基于 CC BY-NC 4.0 许可证
2
// Code example - Licensed under CC BY-NC 4.0
3
const panel = vscode.window.createWebviewPanel(
4
  "andreaRoleCardManager",
5
  "角色卡管理器",
6
  vscode.ViewColumn.One,
7
  {
8
    enableScripts: true,
9
    retainContextWhenHidden: true,
10
    localResourceRoots: [
11
      spaRoot,
12
      vscode.Uri.joinPath(ctx.extensionUri, "media"),
13
    ],
14
  }
15
);

复用面板时只需 reveal() 并刷新 HTML；首次创建时请设置好 localResourceRoots 与 enableScripts。

资源路径：一切都走 asWebviewUri#

Webview 是隔离环境，磁盘路径或相对路径都不可直接用，必须通过 webview.asWebviewUri(vscode.Uri) 转换成安全 URL。

典型做法：

读取构建后的 index.html
重写标签属性：把 <script|link|img|source|video|audio|iframe> 的 src/href 统一替换为 asWebviewUri 生成的 URL。
处理 JS/CSS 内的路径：补齐 /assets/...、./assets/...，以及 import()、url(...) 等动态引用。

核心思想是“构建期 + 运行时双保险”：

构建期：用正则或解析器把常见的 src/href、/assets/ 统一改写；
运行时：注入资源映射器，拦截后续动态插入的节点与网络请求，确保依旧指向可达的 URL。

运行时资源映射器（最小思路）#

📄 CC BY-NC 4.0

1
// 代码示例 - 基于 CC BY-NC 4.0 许可证
2
// Code example - Licensed under CC BY-NC 4.0
3

4
// 1) 注入全局映射：把 /assets/file → asWebviewUri 对应结果
5
window.__vscode_resource_map__ = { '/assets/app.js': 'https://.../app.js', ... }
6
window.__vscode_resource_baseUri__ = 'https://.../spa'
7

8
// 2) transformPath：把一切本地路径改写成上面的可达 URL
9
function transformPath(p) {
10
  // 放过 http/https/data/blob/javascript
11
  // /assets 与 ./assets、assets 统一拼成 baseUri + /assets/...
12
}
13

14
// 3) 挂钩常见入口：
15
// - 元素属性：HTMLScriptElement.src / HTMLLinkElement.href / HTMLImageElement.src...
16
// - fetch / XMLHttpRequest.open
17
// - MutationObserver 监听新增节点并重写

这样即使 Vue 组件在运行时动态创建 <img>、<script>，或用 fetch('/assets/x.json')，也能被自动修正。

内容安全策略（CSP）#

推荐策略（根据需要裁剪）：

📄 CC BY-NC 4.0

1
<!-- 代码示例 - 基于 CC BY-NC 4.0 许可证 -->
2
<!-- Code example - Licensed under CC BY-NC 4.0 -->
3
<meta
4
  http-equiv="Content-Security-Policy"
5
  content="
6
  default-src 'none';
7
  img-src {{webview.cspSource}} https: data: blob:;
8
  style-src {{webview.cspSource}} 'unsafe-inline';
9
  font-src {{webview.cspSource}} data:;
10
  script-src {{webview.cspSource}} https: 'unsafe-inline';
11
  connect-src {{webview.cspSource}} https:;
12
  frame-src 'none';
13
  worker-src {{webview.cspSource}} blob:;
14
  child-src {{webview.cspSource}} blob:;
15
"
16
/>

说明：

{{webview.cspSource}} 实际运行时由 webview.cspSource 替换
如必须使用内联脚本，尽量控制在“注入全局数据”等极少量场景
如果需要访问接口域名，请把域名加入 connect-src

Webview ↔ 扩展通信#

前端（Webview）：

📄 CC BY-NC 4.0

1
// 代码示例 - 基于 CC BY-NC 4.0 许可证
2
// Code example - Licensed under CC BY-NC 4.0
3
const vscode = acquireVsCodeApi();
4

5
// 请求数据
6
vscode.postMessage({ type: "requestRoleCards" });
7

8
// 接收数据
9
window.addEventListener("message", (e) => {
10
  if (e.data?.type === "roleCards") {
11
    render(e.data.list);
12
  }
13
});
14

15
// 保存
16
function save(list) {
17
  vscode.postMessage({ type: "saveRoleCards", list });
18
}

扩展端：

📄 CC BY-NC 4.0

1
// 代码示例 - 基于 CC BY-NC 4.0 许可证
2
// Code example - Licensed under CC BY-NC 4.0
3
panel.webview.onDidReceiveMessage(async (msg) => {
4
  if (msg?.type === "requestRoleCards") {
5
    panel.webview.postMessage({ type: "roleCards", list });
6
  } else if (msg?.type === "saveRoleCards") {
7
    // 校验并持久化
8
    panel.webview.postMessage({ type: "saveAck", ok: true });
9
  }
10
});

开发与调试建议#

前端使用 vite build --watch 连续输出到 dist/spa
扩展端 F5 启动 “Extension Development Host”，重载即可验证
不直接接入 Vite Dev Server（CSP 与源隔离更复杂，且与发布环境不一致）
打开 Webview 开发者工具观察 Network 与 CSP 报错

常见问题排查#

图片/CSS 不加载：检查 localResourceRoots、路径重写、asWebviewUri 是否覆盖到了
前端路由 404：优先使用 Hash 路由，或自行把导航与内容托管在 Webview 内部状态
CSP 报错：按报错提示补齐 connect-src、script-src 等来源

实战：预处理 HTML 与动态注入 JS 劫持（MPL-2.0）#

下面给出一套可直接落地的实现，分为：

扩展端：读取构建产物的 index.html，批量重写资源路径、注入 CSP 与运行时代码，并输出给 Webview。
Webview 端：动态资源映射器，拦截 DOM 属性、fetch/XMLHttpRequest、MutationObserver 等入口，统一把 /assets 等路径改写为可达 URL。

许可说明：本文非代码部分以 CC BY-NC 4.0 授权；本小节内的“示例代码”以 Mozilla Public License 2.0（MPL-2.0）授权，你可以复制、修改并在满足 MPL-2.0 的前提下分发。

扩展端：HTML 预处理与注入（TypeScript, MPL-2.0）#

📄 Mozilla 公共许可证 2.0

1
/*
2
 * This file is licensed under the Mozilla Public License 2.0 (MPL-2.0).
3
 * SPDX-License-Identifier: MPL-2.0
4
 */
5
import * as vscode from "vscode";
6
import * as fs from "fs";
7

8
export function buildHtml(
9
  webview: vscode.Webview,
10
  spaRoot: vscode.Uri,
11
  opts?: {
12
    connectSrc?: string[];
13
    resourceMapperScriptUri?: string; // 已通过 asWebviewUri 转换
14
  }
15
) {
16
  const indexHtmlPath = vscode.Uri.joinPath(spaRoot, "index.html").fsPath;
17
  if (!fs.existsSync(indexHtmlPath)) {
18
    return `<html><body><h3>Webview</h3><p>index.html 未找到：<code>${indexHtmlPath}</code></p></body></html>`;
19
  }
20

21
  let html = fs.readFileSync(indexHtmlPath, "utf-8");
22
  html = rewriteHtmlToWebviewUris(html, webview, spaRoot);
23
  html = fixAllAssetUrls(html, webview, spaRoot);
24
  html = injectResourceMapper(
25
    html,
26
    webview,
27
    spaRoot,
28
    opts?.resourceMapperScriptUri
29
  );
30
  html = stripBaseTag(html);
31
  html = applyCsp(html, webview, opts?.connectSrc ?? ["https:", "http:"]);
32
  return html;
33
}
34

35
type Attr = "src" | "href";
36
function rewriteHtmlToWebviewUris(
37
  html: string,
38
  webview: vscode.Webview,
39
  spaRoot: vscode.Uri
40
): string {
41
  const fixRelFromVscodeWebview = (u: string) =>
42
    u.replace(/^vscode-webview:\/\/[^/]+\//i, "");
43
  const replaceAttr = (tag: string, attr: Attr) => {
44
    const re = new RegExp(
45
      `<${tag}\\b([^>]*?)\\s${attr}\\s*=\\s*(?:"([^"]+)"|'([^']+)'|([^\\s>]+))([^>]*)>`,
46
      "gi"
47
    );
48
    html = html.replace(re, (m, pre, g1, g2, g3, post) => {
49
      const raw = g1 ?? g2 ?? g3 ?? "";
50
      if (/^(data:|mailto:|javascript:|#|https?:)/i.test(raw)) return m;
51
      const rel = fixRelFromVscodeWebview(raw).replace(/^\.\/?/, "");
52
      const fileUri = vscode.Uri.joinPath(spaRoot, rel);
53
      const webUri = webview.asWebviewUri(fileUri).toString();
54
      const quoted =
55
        g1 != null ? `"${webUri}"` : g2 != null ? `'${webUri}'` : webUri;
56
      return `<${tag}${pre} ${attr}=${quoted}${post}>`;
57
    });
58
  };
59
  ["script", "link", "img", "source", "video", "audio", "iframe"].forEach(
60
    (t) => {
61
      replaceAttr(t, t === "link" ? "href" : "src");
62
    }
63
  );
64
  return html;
65
}
66

67
function fixAllAssetUrls(
68
  html: string,
69
  webview: vscode.Webview,
70
  spaRoot: vscode.Uri
71
): string {
72
  const base = webview.asWebviewUri(spaRoot).toString().replace(/\/$/, "");
73
  html = html.replace(
74
    /(\s(?:href|src)\s*=\s*)(["'])\/assets\//gi,
75
    (_m, p1, q) => `${p1}${q}${base}/assets/`
76
  );
77
  html = html.replace(
78
    /(\s(?:href|src)\s*=\s*)(["'])(?:\.\/)?assets\//gi,
79
    (_m, p1, q) => `${p1}${q}${base}/assets/`
80
  );
81
  html = html.replace(
82
    /(import\s*\(\s*)(["'`])([^"'`]*\/assets\/[^"'`]*)\2/g,
83
    (_m, pre, q, p) => `${pre}${q}${base}/${p.replace(/^\.?\//, "")}${q}`
84
  );
85
  html = html.replace(/(["'`])\/assets\//g, `$1${base}/assets/`);
86
  html = html.replace(/(["'`])\.\/assets\//g, `$1${base}/assets/`);
87
  return html;
88
}
89

90
function injectResourceMapper(
91
  html: string,
92
  webview: vscode.Webview,
93
  spaRoot: vscode.Uri,
94
  mapperScriptUri?: string
95
): string {
96
  const baseUri = webview.asWebviewUri(spaRoot).toString().replace(/\/$/, "");
97
  // 扫描 dist/spa/assets 目录，生成最小映射
98
  const assetsDir = vscode.Uri.joinPath(spaRoot, "assets").fsPath;
99
  const resourceMap: Record<string, string> = {};
100
  if (fs.existsSync(assetsDir)) {
101
    for (const f of fs.readdirSync(assetsDir)) {
102
      const key = `/assets/${f}`;
103
      resourceMap[key] = webview
104
        .asWebviewUri(vscode.Uri.joinPath(spaRoot, "assets", f))
105
        .toString();
106
    }
107
  }
108
  const safeMap = JSON.stringify(resourceMap)
109
    .replace(/</g, "\\u003c")
110
    .replace(/>/g, "\\u003e");
111
  const injectedData = `<script>window.__vscode_resource_map__=${safeMap};window.__vscode_resource_baseUri__="${baseUri}";<\/script>`;
112
  const mapperTag = mapperScriptUri
113
    ? `\n<script src="${mapperScriptUri}"><\/script>`
114
    : "";
115
  return html.replace(
116
    /<head([^>]*)>/i,
117
    `<head$1>\n${injectedData}${mapperTag}`
118
  );
119
}
120

121
function applyCsp(
122
  html: string,
123
  webview: vscode.Webview,
124
  connectSrc: string[] = []
125
): string {
126
  const connect = [webview.cspSource, ...connectSrc].join(" ");
127
  const csp = [
128
    `default-src 'none';`,
129
    `img-src ${webview.cspSource} https: data: blob:;`,
130
    `style-src ${webview.cspSource} 'unsafe-inline';`,
131
    `font-src ${webview.cspSource} data:;`,
132
    `script-src ${webview.cspSource} https: 'unsafe-inline';`,
133
    `connect-src ${connect};`,
134
    `frame-src 'none';`,
135
    `worker-src ${webview.cspSource} blob:;`,
136
    `child-src ${webview.cspSource} blob:;`,
137
  ].join(" ");
138
  const tag = `<meta http-equiv="Content-Security-Policy" content="${csp}">`;
139
  return /<meta http-equiv="Content-Security-Policy"/i.test(html)
140
    ? html.replace(/<meta http-equiv="Content-Security-Policy"[^>]*>/i, tag)
141
    : html.replace(/<head([^>]*)>/i, `<head$1>\n  ${tag}`);
142
}
143

144
function stripBaseTag(html: string): string {
145
  return html.replace(/<base\s+[^>]*>/gi, "");
146
}

使用方式：在创建/复用 WebviewPanel 后，读取 dist/spa/index.html 并调用 buildHtml，把返回的 HTML 赋给 panel.webview.html 即可。

Webview 端：动态资源映射器（JavaScript, MPL-2.0）#

📄 Mozilla 公共许可证 2.0

1
/*
2
 * This file is licensed under the Mozilla Public License 2.0 (MPL-2.0).
3
 * SPDX-License-Identifier: MPL-2.0
4
 */
5
(function () {
6
  var resourceMap = window.__vscode_resource_map__ || {};
7
  var baseUri = (window.__vscode_resource_baseUri__ || "").replace(/\/$/, "");
8

9
  function transformPath(path) {
10
    if (!path || typeof path !== "string") return path;
11
    if (path.startsWith(baseUri)) return path;
12
    try {
13
      const u = new URL(path);
14
      if (
15
        u.protocol === "vscode-webview:" &&
16
        u.pathname.startsWith("/assets/")
17
      ) {
18
        const key = u.pathname;
19
        return resourceMap[key] || baseUri + key;
20
      }
21
      if (/^(https?:|data:|blob:|javascript:)/i.test(u.protocol + ""))
22
        return path;
23
    } catch (_) {}
24
    if (path.startsWith("/assets/")) return resourceMap[path] || baseUri + path;
25
    if (path.startsWith("./assets/") || path.startsWith("assets/")) {
26
      const normalized = path.startsWith("./") ? path.slice(1) : "/" + path;
27
      return resourceMap[normalized] || baseUri + normalized;
28
    }
29
    if (/^(https?:|data:|blob:|javascript:)/i.test(path)) return path;
30
    const full = path.startsWith("/") ? path : "/" + path;
31
    return baseUri + full;
32
  }
33

34
  function patchURLProp(Ctor, prop) {
35
    try {
36
      const proto = Ctor && Ctor.prototype;
37
      if (!proto) return;
38
      const desc = Object.getOwnPropertyDescriptor(proto, prop);
39
      if (!desc || !desc.set || !desc.get) return;
40
      Object.defineProperty(proto, prop, {
41
        configurable: true,
42
        enumerable: desc.enumerable,
43
        get() {
44
          return desc.get.call(this);
45
        },
46
        set(v) {
47
          try {
48
            v = transformPath(String(v));
49
          } catch (_) {}
50
          return desc.set.call(this, v);
51
        },
52
      });
53
    } catch (_) {}
54
  }
55

56
  patchURLProp(HTMLScriptElement, "src");
57
  patchURLProp(HTMLLinkElement, "href");
58
  patchURLProp(HTMLImageElement, "src");
59
  patchURLProp(HTMLSourceElement, "src");
60
  patchURLProp(HTMLIFrameElement, "src");
61
  patchURLProp(HTMLMediaElement, "src");
62

63
  const _setAttr = Element.prototype.setAttribute;
64
  Element.prototype.setAttribute = function (name, value) {
65
    try {
66
      if (
67
        typeof value === "string" &&
68
        /^(src|href|srcset)$/i.test(String(name))
69
      ) {
70
        value = transformPath(value);
71
      }
72
    } catch (_) {}
73
    return _setAttr.call(this, name, value);
74
  };
75

76
  function rewriteCssUrls(cssText) {
77
    if (!cssText) return cssText;
78
    cssText = cssText.replace(
79
      /url\(\s*(['"]?)(?!data:|blob:)(\/?\.?assets\/[^'")\s?#]+(?:[?#][^'")]*)?)\1\s*\)/gi,
80
      (_m, q, p) => {
81
        let path = p;
82
        if (path.startsWith("./")) path = path.slice(1);
83
        if (path.startsWith("assets/")) path = "/" + path;
84
        if (!path.startsWith("/assets/")) return _m;
85
        const mapped = resourceMap[path] || baseUri + path;
86
        return "url(" + (q || "") + mapped + (q || "") + ")";
87
      }
88
    );
89
    cssText = cssText.replace(
90
      /@import\s+(?:url\(\s*(['"]?)(\/?\.?assets\/[^'\")\s;]+)\1\s*\)|(['"])(\/?\.?assets\/[^'\")\s;]+)\3)\s*;/gi,
91
      (_m, q1, p1, q2, p2) => {
92
        let path = p1 || p2;
93
        if (path.startsWith("./")) path = path.slice(1);
94
        if (path.startsWith("assets/")) path = "/" + path;
95
        if (!path.startsWith("/assets/")) return _m;
96
        const mapped = resourceMap[path] || baseUri + path;
97
        const q = q1 || q2 || "";
98
        return "@import url(" + q + mapped + q + ");";
99
      }
100
    );
101
    return cssText;
102
  }
103

104
  async function inlineStylesheet(linkEl) {
105
    try {
106
      if (!linkEl || linkEl.dataset.__inlined_css__) return;
107
      if (!/stylesheet/i.test(linkEl.rel || "")) return;
108
      if (!linkEl.href) return;
109
      const href = transformPath(linkEl.href);
110
      const res = await fetch(href, { credentials: "same-origin" });
111
      if (!res.ok) throw new Error("css fetch " + res.status);
112
      const css = await res.text();
113
      const fixed = rewriteCssUrls(css);
114
      const style = document.createElement("style");
115
      style.setAttribute("data-vscode-webview-inlined", "1");
116
      style.textContent = fixed;
117
      linkEl.dataset.__inlined_css__ = "1";
118
      linkEl.parentNode && linkEl.parentNode.insertBefore(style, linkEl);
119
      linkEl.remove();
120
    } catch (e) {
121
      try {
122
        linkEl.href = transformPath(linkEl.href);
123
      } catch (_) {}
124
      console.warn("inlineStylesheet failed:", e);
125
    }
126
  }
127

128
  var originalFetch = window.fetch;
129
  if (originalFetch) {
130
    window.fetch = function (url, options) {
131
      if (typeof url === "string")
132
        return originalFetch.call(this, transformPath(url), options);
133
      if (url && typeof url.url === "string") {
134
        var req = url;
135
        var newUrl = transformPath(req.url);
136
        if (newUrl !== req.url) {
137
          try {
138
            url = new Request(newUrl, req);
139
          } catch (_) {
140
            return originalFetch.call(
141
              this,
142
              newUrl,
143
              options || { method: req.method, headers: req.headers }
144
            );
145
          }
146
        }
147
      }
148
      return originalFetch.call(this, url, options);
149
    };
150
  }
151

152
  var X = window.XMLHttpRequest && window.XMLHttpRequest.prototype;
153
  if (X && X.open) {
154
    var origOpen = X.open;
155
    X.open = function (method, url) {
156
      try {
157
        if (typeof url === "string") arguments[1] = transformPath(url);
158
      } catch (_) {}
159
      return origOpen.apply(this, arguments);
160
    };
161
  }
162

163
  if (typeof window.__vitePreload !== "undefined") {
164
    var origPreload = window.__vitePreload;
165
    window.__vitePreload = function (fn, deps, path) {
166
      if (deps && Array.isArray(deps)) deps = deps.map((d) => transformPath(d));
167
      if (path) path = transformPath(path);
168
      return origPreload.call(this, fn, deps, path);
169
    };
170
  }
171

172
  function rewriteEl(el) {
173
    const tag = el.tagName;
174
    if (tag === "LINK") {
175
      const rel = (el.rel || "").toLowerCase();
176
      if (rel.includes("stylesheet")) {
177
        inlineStylesheet(el);
178
        return;
179
      }
180
      if (el.href) {
181
        const next = transformPath(el.href);
182
        if (next !== el.href) el.href = next;
183
      }
184
      return;
185
    }
186
    if (tag === "SCRIPT" && el.src) {
187
      const next = transformPath(el.src);
188
      if (next !== el.src) el.src = next;
189
      return;
190
    }
191
    if (
192
      (tag === "IMG" ||
193
        tag === "SOURCE" ||
194
        tag === "VIDEO" ||
195
        tag === "AUDIO") &&
196
      el.src
197
    ) {
198
      const next = transformPath(el.src);
199
      if (next !== el.src) el.src = next;
200
    }
201
    if (el.hasAttribute && el.hasAttribute("srcset")) {
202
      try {
203
        const raw = el.getAttribute("srcset") || "";
204
        const parts = raw
205
          .split(",")
206
          .map((p) => p.trim())
207
          .filter(Boolean);
208
        const fixed = parts
209
          .map((p) => {
210
            const sp = p.split(/\s+/);
211
            sp[0] = transformPath(sp[0]);
212
            return sp.join(" ");
213
          })
214
          .join(", ");
215
        if (fixed !== raw) el.setAttribute("srcset", fixed);
216
      } catch (_) {}
217
    }
218
  }
219

220
  if (typeof MutationObserver !== "undefined") {
221
    const mo = new MutationObserver((muts) => {
222
      for (const m of muts) {
223
        if (m.type === "childList") {
224
          m.addedNodes &&
225
            m.addedNodes.forEach((n) => {
226
              if (n && n.nodeType === 1) {
227
                rewriteEl(n);
228
                n.querySelectorAll?.(
229
                  "link[rel],script[src],img[src],source[src],video[src],audio[src],[srcset]"
230
                ).forEach(rewriteEl);
231
              }
232
            });
233
        } else if (m.type === "attributes") {
234
          rewriteEl(/** @type {Element} */ (m.target));
235
        }
236
      }
237
    });
238
    const start = () => {
239
      mo.observe(document.documentElement || document, {
240
        childList: true,
241
        subtree: true,
242
        attributes: true,
243
        attributeFilter: ["href", "src", "srcset", "rel"],
244
      });
245
      document
246
        .querySelectorAll(
247
          "link[rel],script[src],img[src],source[src],video[src],audio[src],[srcset]"
248
        )
249
        .forEach(rewriteEl);
250
    };
251
    document.readyState === "loading"
252
      ? document.addEventListener("DOMContentLoaded", start, { once: true })
253
      : start();
254
  }
255

256
  console.log("VSCode Webview resource mapper initialized");
257
  console.log("Base URI:", baseUri);
258
})();

要点回顾：

扩展端始终以 webview.asWebviewUri 作为“真相源”；
Webview 端只做兜底修复，确保动态新增节点与网络请求同样可达；
两侧配合 CSP，既安全又稳定。

以上示例代码以 MPL-2.0 授权；若你在项目中使用，请保留许可头与变更说明。

小结#

把 Vue SPA 嵌入 VS Code Webview 的关键是“资源可达且安全”。

通过：

全量走 asWebviewUri 暴露静态资源
运行时资源映射器兜底动态引用
严格且可控的 CSP 配置
明确的数据通信协议

即可实现稳定、安全的嵌入式前端体验。后续你可以叠加数据持久化（全局存储/工作区文件）、多语言与主题适配等能力。