Electron 中使用自定义协议安全加载本地视频文件的完整实践指南-js教程-PHP中文网

Electron 中使用自定义协议安全加载本地视频文件的完整实践指南

本文详解如何在 electron 应用中通过 protocol.handle() 配合正确配置的 registerschemesasprivileged，安全、可靠地从本地文件系统加载并播放视频（如 mp4），解决黑屏、csp 阻断及沙盒环境下的资源加载失败问题。

本文详解如何在 electron 应用中通过 protocol.handle() 配合正确配置的 registerschemesasprivileged，安全、可靠地从本地文件系统加载并播放视频（如 mp4），解决黑屏、csp 阻断及沙盒环境下的资源加载失败问题。

在 Electron 中直接使用

正确的解决方案是：注册一个自定义协议（如 animation:// 或 appfile://），并为其显式启用 stream: true 和 bypassCSP: true 权限。其中 stream: true 是关键——它允许该协议被用于

✅ 正确配置自定义协议（主进程）

以下为精简、健壮的主进程实现（兼容 Electron ≥ 20）：

// main.ts
import { app, protocol, net, BrowserWindow } from 'electron';
import path from 'path';

// 1. 注册自定义协议，必须包含 stream: true 和 bypassCSP: true
protocol.registerSchemesAsPrivileged([
  {
    scheme: 'appfile',
    privileges: {
      standard: true,      // 启用标准 URL 解析（如路径处理）
      secure: true,        // 允许在 HTTPS 页面中使用（增强安全性）
      supportFetchAPI: true,
      bypassCSP: true,     // 绕过内容安全策略（必需）
      stream: true,        // ✅ 关键！允许用于 <video>/<audio> 流式加载
    }
  }
]);

app.whenReady().then(() => {
  // 2. 实现协议处理器：将 appfile://xxx 转为 file://xxx 并代理请求
  protocol.handle('appfile', (request) => {
    const filePath = request.url.replace(/^appfile:\/\//, '');
    // ⚠️ 安全警告：生产环境务必校验 filePath，防止路径遍历攻击（如 ../）
    // 示例：仅允许访问项目内 videos/ 目录
    if (!filePath.startsWith(path.join(__dirname, '../videos/'))) {
      return new Response('Forbidden', { status: 403 });
    }

    const fileUrl = `file://${filePath}`;
    console.log('[Protocol] Serving video:', fileUrl);
    return net.fetch(fileUrl);
  });

  // 创建窗口（注意：若启用了 sandbox，preload.js 必须存在且不注入 Node.js）
  const win = new BrowserWindow({
    width: 1024,
    height: 768,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      sandbox: true, // 推荐启用沙盒，更安全
      contextIsolation: true,
    }
  });

  win.loadFile('index.html');
});</audio></video>

✅ 渲染进程视频标签写法（React 示例）

在 React 组件中，直接使用自定义协议 URL 即可，无需额外逻辑：

// App.tsx
function VideoPlayer() {
  return (
    <div style="{{" width: height: background:>
      <video width="100%" height="100%" autoplay muted loop controls>
        {/* ✅ 正确格式：协议名后紧跟绝对路径（Linux/macOS 前置 /，Windows 需转义盘符） */}
        <source src="appfile:///home/user/Desktop/project/videos/video1.mp4" type="video/mp4"></source></video>
</div>
  );
}

export default VideoPlayer;

? Windows 路径提示：若需支持 Windows，路径应写作 appfile://C:/Users/.../video.mp4（注意双斜杠和盘符大写），或在主进程做统一路径标准化处理。

⚠️ 关键注意事项与最佳实践

stream: true 不可省略：这是 Electron 20+ 引入的强制要求。缺少它会导致
路径安全校验至关重要：protocol.handle 中直接拼接用户可控路径存在严重路径遍历风险（如 appfile://../../../etc/passwd）。务必使用 path.resolve() + 白名单目录校验，或改用 fs.promises.readFile 读取后返回 Response 流。

避免 net.fetch('file://...') 的潜在问题：某些 Electron 版本对 file:// 的 net.fetch 支持不稳定。更稳健的做法是使用 fs.createReadStream 手动构造流式响应：

import { createReadStream } from 'fs';
import { join } from 'path';

protocol.handle('appfile', async (request) => {
  const filePath = request.url.replace(/^appfile:\/\//, '');
  const safePath = join(__dirname, '../videos', path.basename(filePath)); // 示例白名单
  try {
    const fileStream = createReadStream(safePath);
    return new Response(fileStream, {
      headers: { 'Content-Type': 'video/mp4' }
    });
  } catch (e) {
    return new Response('Not Found', { status: 404 });
  }
});

CSP 设置（HTML 中）：若使用 index.html 而非 React Router，需在中声明允许自定义协议：

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; img-src 'self' data:; media-src 'self' appfile:;">

✅ 总结

要让 Electron 中的

遵循此模式，即可彻底规避黑屏、静默失败与 CSP 报错，构建出安全、稳定、符合 Electron 最佳实践的本地媒体播放应用。