Webview 安全性

Webview 页面运行在真实浏览器内核中，加载的内容默认拥有较高权限：可以发网络请求、读取部分本地状态。如果页面被注入恶意脚本，就能冒充插件行为、窃取用户数据。Content Security Policy（CSP）是 Webview 的第一道防线，必须显式配置。

为什么必须配置 CSP

VS Code 官方安全指南要求每个 Webview 的 html 必须包含 CSP 元标签。不配置 CSP 的 Webview 在开发者工具里会看到警告，更严重的是，一旦页面引入了外部内容或被 XSS 注入，脚本可以在你的插件上下文中执行任意操作。

CSP 通过一个 meta 标签声明，浏览器据此限制页面的资源加载与脚本执行：

html

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'none'; style-src ${webview.cspSource}; img-src ${webview.cspSource} data:; script-src ${webview.cspSource};"
/>

指令体系

CSP 指令按资源类型分组，每条指令控制一类资源的加载来源：

指令	控制的资源	典型来源值
`default-src`	所有未单独指定类型的资源（兜底）	`'none'`、`self`
`script-src`	JavaScript 脚本	`self`、`nonce-xxx`
`style-src`	CSS 样式（内联样式、样式表）	`self`、`unsafe-inline`
`img-src`	图片	`self`、`data:`、`https:`
`connect-src`	fetch/XHR/WebSocket 请求	`https:`、`self`
`font-src`	字体文件	`self`、`data:`
`media-src`	音视频	`self`、`https:`
`frame-src`	iframe 嵌入	`'none'`、`self`

严格原则

原则	做法
最小权限	没有用到的资源类型一律不给来源
兜底设 none	`default-src 'none'`，再逐个放行
拒绝 unsafe-inline	脚本绝不使用内联执行
拒绝 unsafe-eval	禁用 `eval`、`new Function`
白名单而非通配	用具体域名，不用 `*`

禁用 eval 与内联脚本

问题：内联脚本被 CSP 拦截

CSP 配置为 script-src 'self' 后，<script> 标签里直接写的代码、onclick="..." 属性、eval() 全部失效。原因是内联脚本无法被「验明正身」，浏览器一律不执行。

两种合规方案：

方案	原理	适用场景
nonce 随机数	每次生成一次性随机数，合法脚本携带相同 nonce	少量脚本、html 由插件动态拼接
外部脚本文件	脚本放到独立 js 文件，用 `script-src self` 加载	脚本较大、模块化组织

nonce 方案

插件在生成 html 时生成随机 nonce，写进 CSP 与脚本标签：

typescript

// extension.ts
import * as vscode from 'vscode';
import * as crypto from 'crypto';

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand('myExt.securePanel', () => {
      const panel = vscode.window.createWebviewPanel(
        'myExt.secure',
        '安全面板',
        vscode.ViewColumn.One,
        { enableScripts: true }
      );

      // 每次打开生成新的随机 nonce
      const nonce = crypto.randomBytes(16).toString('base64');
      panel.webview.html = getHtml(nonce);
      context.subscriptions.push(panel);
    })
  );
}

function getHtml(nonce: string): string {
  return `<!DOCTYPE html>
    <html lang="zh-CN">
      <head>
        <meta charset="UTF-8">
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'none'; script-src 'nonce-${nonce}';
                   style-src 'nonce-${nonce}'; img-src data:;"
        >
      </head>
      <body>
        <h1>安全示例</h1>
        <!-- 携带相同 nonce 的脚本才会执行 -->
        <script nonce="${nonce}">
          const vscode = acquireVsCodeApi();
          document.addEventListener('click', () => {
            vscode.postMessage({ type: 'clicked' });
          });
        </script>
      </body>
    </html>`;
}

注意：nonce 必须每次刷新页面重新生成（面板重开、html 重设都会触发）。如果插件代码里能拿到 nonce，说明攻击者也能通过 XSS 拿到——nonce 防的是「外部注入的脚本」，不防「页面内部自身被攻破」。

外部脚本文件方案

脚本量大时放独立文件，由 asWebviewUri 转换后加载：

typescript

function getHtmlWithExternalScript(
  webview: vscode.Webview,
  context: vscode.ExtensionContext
): string {
  // 把 media/main.js 转换为可加载的 webview URI
  const scriptUri = webview.asWebviewUri(
    vscode.Uri.joinPath(context.extensionUri, 'media', 'main.js')
  );

  return `<!DOCTYPE html>
    <html lang="zh-CN">
      <head>
        <meta charset="UTF-8">
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'none';
                   script-src ${webview.cspSource};
                   style-src ${webview.cspSource};
                   img-src ${webview.cspSource} data:;"
        >
      </head>
      <body>
        <div id="app"></div>
        <script src="${scriptUri}"></script>
      </body>
    </html>`;
}

webview.cspSource 是 VS Code 自动注入的源标识，指向「扩展本身」的虚拟地址，CSP 里写上它，页面就能加载 asWebviewUri 生成的资源 URI。

外部资源白名单控制

Webview 可以加载远程资源，但必须显式声明。以图片为例，img-src 决定哪些域名下的图片允许显示：

html

<!-- 只允许加载 https 协议下的图片，http 一律拒绝 -->
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'none';
           img-src https: data:;
           connect-src https:;"
/>

各指令的白名单写法

场景	指令写法	说明
只允许本扩展资源	`img-src ${webview.cspSource}`	最严格
允许 https 任意域名	`img-src https:`	按协议放行
允许指定域名	`img-src https://cdn.example.com`	精确控制
允许 base64 图片	`img-src data:`	内嵌小图
需要请求远程 API	`connect-src https://api.example.com`	fetch 目标

为什么要控制 connect-src

connect-src 控制 fetch/XHR。如果页面被注入脚本，它会优先尝试把数据外传——限制 connect-src 后，恶意脚本连不到外部服务器，数据「出不去」，损失被限制在页面内部。

javascript

// 页面内只能请求白名单内的地址
const res = await fetch('https://api.example.com/sync');
// 访问 https://evil.com 会被 CSP 拦截并报错

asWebviewUri 安全引用扩展内资源

为什么要转换

asWebviewUri 把扩展包内的磁盘路径转换成 Webview 可用的安全 URI。直接写 file:///C:/... 路径在 Webview 里无法加载，且会破坏 Webview 的隔离模型。它返回的 URI 形如：

vscode-webview://webviewId-.../extension/media/logo.png

localResourceRoots 配合

localResourceRoots 声明「扩展中哪些目录允许被 Webview 加载」，是 asWebviewUri 的配套白名单：

typescript

const panel = vscode.window.createWebviewPanel(
  'myExt.resources',
  '资源面板',
  vscode.ViewColumn.One,
  {
    enableScripts: true,
    // 只允许加载 media 目录下的文件
    localResourceRoots: [
      vscode.Uri.joinPath(context.extensionUri, 'media')
    ]
  }
);

// 目录外（如根目录下的 secret.json）即使知道路径也无法加载
const blockedUri = vscode.Uri.joinPath(context.extensionUri, 'secret.json');
// blockedUri 不在 localResourceRoots 内，Webview 无法访问

完整引用示例

typescript

function buildHtml(
  webview: vscode.Webview,
  context: vscode.ExtensionContext
): string {
  // 转换三个资源：脚本、样式、图片
  const scriptUri = webview.asWebviewUri(
    vscode.Uri.joinPath(context.extensionUri, 'media', 'app.js'));
  const styleUri = webview.asWebviewUri(
    vscode.Uri.joinPath(context.extensionUri, 'media', 'app.css'));
  const logoUri = webview.asWebviewUri(
    vscode.Uri.joinPath(context.extensionUri, 'media', 'logo.svg'));

  return `<!DOCTYPE html>
    <html lang="zh-CN">
      <head>
        <meta charset="UTF-8">
        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'none';
                   script-src ${webview.cspSource};
                   style-src ${webview.cspSource};
                   img-src ${webview.cspSource} data:;"
        >
        <link rel="stylesheet" href="${styleUri}">
      </head>
      <body>
        <img src="${logoUri}" alt="logo" width="64">
        <div id="app"></div>
        <script src="${scriptUri}"></script>
      </body>
    </html>`;
}

要点：CSP 里的 img-src ${webview.cspSource} 放行了 asWebviewUri 生成的 URI 域，二者必须同时配置才能加载扩展内资源。

XSS 风险防范实践

常见注入面

风险点	危害
把文档内容直接拼进 html	文档中的脚本被执行
`innerHTML` 拼接用户输入	插入恶意标签
未校验的消息数据	伪造插件行为
动态执行字符串	eval 通道被滥用

消息数据校验

来自页面的消息不可信。处理前做结构校验，拒绝格式错误的消息：

typescript

// 插件侧：白名单校验消息
interface SafeMessage {
  type: 'save' | 'load' | 'clear';
  payload?: unknown;
}

function isSafeMessage(msg: unknown): msg is SafeMessage {
  if (!msg || typeof msg !== 'object') return false;
  const m = msg as Record<string, unknown>;
  // 只接受三个已知类型
  return m.type === 'save' || m.type === 'load' || m.type === 'clear';
}

panel.webview.onDidReceiveMessage((msg) => {
  if (!isSafeMessage(msg)) {
    console.warn('丢弃非法消息', msg);
    return;
  }
  switch (msg.type) {
    case 'save': handleSave(msg.payload); break;
    case 'load': handleLoad(); break;
    case 'clear': handleClear(); break;
  }
}, undefined, context.subscriptions);

页面侧防注入渲染

页面渲染不可信文本时，禁止用 innerHTML 直接拼接，使用文本节点或转义函数：

javascript

// 危险写法：文档内容含 <img onerror="..."> 时会被执行
// element.innerHTML = '<div>' + docContent + '</div>';

// 安全写法一：textContent 自动转义
const div = document.createElement('div');
div.textContent = docContent; // 永远按纯文本渲染

// 安全写法二：手动 HTML 转义后再拼接
function escapeHtml(text) {
  return text
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;');
}
element.innerHTML = `<pre>${escapeHtml(docContent)}</pre>`;

禁用不安全 API

javascript

// 禁止使用（在 CSP 中已禁用 unsafe-eval）
// eval(code);
// new Function(code);

// 替代：把「代码」当作「数据」处理
// 需要执行逻辑时，用消息通知插件侧执行，
// 或使用受限的解析器（如 JSON.parse）代替代码执行

完整示例：安全配置全家桶

typescript

// extension.ts 完整安全示例
import * as vscode from 'vscode';
import * as crypto from 'crypto';

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand('myExt.secureApp', () => {
      const panel = vscode.window.createWebviewPanel(
        'myExt.secureApp',
        '安全应用',
        vscode.ViewColumn.One,
        {
          enableScripts: true,
          // 白名单：只允许加载 media 目录
          localResourceRoots: [
            vscode.Uri.joinPath(context.extensionUri, 'media')
          ]
        }
      );

      const nonce = crypto.randomBytes(16).toString('base64');
      panel.webview.html = buildSecureHtml(panel.webview, context, nonce);

      // 校验后的消息处理
      panel.webview.onDidReceiveMessage((msg) => {
        if (!isKnownMessage(msg)) {
          vscode.window.showWarningMessage('收到未知消息类型');
          return;
        }
        if (msg.type === 'openUrl') {
          // 校验 URL 协议，防止外部重定向滥用
          const url = String(msg.payload?.url ?? '');
          if (/^https:\/\/vscode\.dev|^https:\/\/code\.visualstudio\.com/.test(url)) {
            vscode.env.openExternal(vscode.Uri.parse(url));
          }
        }
      }, undefined, context.subscriptions);

      context.subscriptions.push(panel);
    })
  );
}

// 消息白名单校验
function isKnownMessage(msg: unknown): boolean {
  if (!msg || typeof msg !== 'object') return false;
  return (msg as { type?: unknown }).type === 'openUrl';
}

function buildSecureHtml(
  webview: vscode.Webview,
  context: vscode.ExtensionContext,
  nonce: string
): string {
  const scriptUri = webview.asWebviewUri(
    vscode.Uri.joinPath(context.extensionUri, 'media', 'app.js'));
  const styleUri = webview.asWebviewUri(
    vscode.Uri.joinPath(context.extensionUri, 'media', 'app.css'));

  // 白名单常量集中管理，避免散落各处
  const csp = [
    `default-src 'none'`,
    `script-src 'nonce-${nonce}'`,
    `style-src ${webview.cspSource}`,
    `img-src ${webview.cspSource} data:`,
    `font-src ${webview.cspSource}`,
    `connect-src https:`,
    `frame-src 'none'`,
    `object-src 'none'`,
    `base-uri 'none'`
  ].join('; ');

  return `<!DOCTYPE html>
    <html lang="zh-CN">
      <head>
        <meta charset="UTF-8">
        <meta http-equiv="Content-Security-Policy" content="${csp}">
        <link rel="stylesheet" href="${styleUri}">
      </head>
      <body>
        <div id="app"></div>
        <!-- 外部脚本，无需 nonce；nonce 方案与外部文件二选一即可 -->
        <script src="${scriptUri}"></script>
      </body>
    </html>`;
}

对应的 media/app.js 使用文本节点渲染，杜绝注入：

javascript

// media/app.js
const vscode = acquireVsCodeApi();

// 监听消息并渲染（只使用 textContent）
window.addEventListener('message', (event) => {
  const msg = event.data;
  if (msg.type !== 'render') return;

  const app = document.getElementById('app');
  app.innerHTML = ''; // 清空容器本身是安全的
  const pre = document.createElement('pre');
  pre.textContent = JSON.stringify(msg.data, null, 2); // 纯文本
  app.appendChild(pre);
});

安全检查清单

检查项	做法
CSP 元标签	html 中必须存在，`default-src 'none'` 兜底
脚本执行	用 nonce 或外部文件，禁用 unsafe-inline/unsafe-eval
资源加载	图片/样式/连接按需放行，用白名单域名
扩展资源	全部经 `asWebviewUri` 转换
本地根目录	`localResourceRoots` 只放必要的目录
消息校验	插件侧白名单过滤消息类型
页面渲染	不可信文本用 textContent 或转义函数
外链跳转	`vscode.env.openExternal` 前校验协议与域名

常见问题

问题	处理
页面脚本完全不执行	检查 CSP 的 script-src 是否放行该脚本来源
内联脚本被拦截	改用 nonce 方案或抽到外部文件
图片加载失败	检查 img-src 是否包含该图片来源
fetch 被拒绝	在 connect-src 中添加目标域名
扩展资源 404	确认路径在 localResourceRoots 白名单内且经 asWebviewUri
控制台 CSP 报错	按报错中的指令与来源逐条放行

调试 CSP

手段	说明
Webview 开发者工具 Console	被 CSP 拦截的资源会打印具体指令与来源
Network 面板	检查被阻止请求的失败原因
临时放宽	开发期可放宽后验证，发布前恢复严格配置

安全配置不是「可选项」。CSP、资源白名单、消息校验三者配合，Webview 才能真正成为隔离良好的可信页面。

Webview 安全性 ​

为什么必须配置 CSP ​

指令体系 ​

严格原则 ​

禁用 eval 与内联脚本 ​

问题：内联脚本被 CSP 拦截 ​

nonce 方案 ​

外部脚本文件方案 ​

外部资源白名单控制 ​

各指令的白名单写法 ​

为什么要控制 connect-src ​

asWebviewUri 安全引用扩展内资源 ​

为什么要转换 ​

localResourceRoots 配合 ​

完整引用示例 ​

XSS 风险防范实践 ​

常见注入面 ​

消息数据校验 ​

页面侧防注入渲染 ​

禁用不安全 API ​

完整示例：安全配置全家桶 ​

安全检查清单 ​

常见问题 ​

调试 CSP ​

Webview 安全性

为什么必须配置 CSP

指令体系

严格原则

禁用 eval 与内联脚本

问题：内联脚本被 CSP 拦截

nonce 方案

外部脚本文件方案

外部资源白名单控制

各指令的白名单写法

为什么要控制 connect-src

asWebviewUri 安全引用扩展内资源

为什么要转换

localResourceRoots 配合

完整引用示例

XSS 风险防范实践

常见注入面

消息数据校验

页面侧防注入渲染

禁用不安全 API

完整示例：安全配置全家桶

安全检查清单

常见问题

调试 CSP