在当下的全栈与前端开发中，使用跨平台框架（如 Electron 或 Tauri）将基于现代前端工具链（如 Vite + TypeScript + React/Vue）构建的单页 Web 应用（SPA）打包发布为桌面客户端，是一种极具性价比的交付方案。
然而，许多开发者在第一次使用 Electron 打包静态资源并运行安装包时，往往会面临一个冰冷、没有任何报错提示的“全白屏”或“全黑屏”窗口。
本文将深入剖析该问题的底层机制，并提供最简单、优雅的 Vite 相对路径一键纠偏方案。
一、 致命白屏/黑屏的根源：file:// 协议与绝对路径
在本地开发模式（npm run dev）下，Vite 会启动一个本地 HTTP/HTTPS 服务器（如 http://localhost:5173），此时所有的静态资源都会在 Web 协议下安全传输。在默认配置中，Vite 打包出来的资源文件引用都是绝对路径（以 / 开头）：
<!-- Vite 默认打包的 index.html 引用格式 --><script type="module" crossorigin src="/assets/index-D7b39f.js"></script><link rel="stylesheet" crossorigin href="/assets/index-C8a12b.css">而在生产环境下，出于网络隔离和性能考量，Electron 桌面壳通常是通过 loadURL 或者是 loadFile，利用浏览器的 file:// 协议 直接读取并渲染本地的 index.html 文件的：
// Electron 主进程中加载本地 HTML 的代码win.loadURL(`file://${__dirname}/../dist/index.html`);问题此时发生：
当浏览器内核（Chromium）在 file:// 协议下解析绝对路径 /assets/index-D7b39f.js 时，会将其误判为当前操作系统根目录下的路径：
- 在 Windows 下，它会被解析为
file:///C:/assets/index-D7b39f.js - 在 Linux/macOS 下，它会被解析为
file:///assets/index-D7b39f.js
系统根目录下当然不存在这个资源文件。这会导致控制台瞬间报出大量 404 (Not Found) 错误。由于 SPA 所有的逻辑与渲染全部由 JS 脚本驱动，核心脚本加载失败，桌面窗口就会彻底处于“白屏（未加载）”或“黑屏（框架阻塞）”的崩溃状态。
二、 终极解决方案：Vite 相对路径配置
要根除该问题，必须让 Vite 在打包静态文件时，将所有的资源引用路径重写为以当前 HTML 文件为基准的相对路径（以 ./ 或空字符串开头）。
我们仅需修改项目根目录下的 vite.config.ts：
import { defineConfig } from 'vite';import vue from '@vitejs/plugin-vue'; // 以 Vue 为例import path from 'path';
export default defineConfig({ plugins: [vue()],
// 关键核心修改：将默认的 '/' 改为 './' 或空字符串 // 这会强制编译引擎将所有的资源引用重写为相对路径 base: './',
resolve: { alias: { '@': path.resolve(__dirname, './src'), }, },
build: { outDir: 'dist', assetsDir: 'assets', // 针对 Electron 的 file:// 协议，建议关闭或优化 cssCodeSplit // 确保 CSS 加载顺序与 DOM 挂载同步，减少界面闪烁 cssCodeSplit: true, }});配置完毕后重新执行 npm run build，再次查看 dist/index.html，可以发现资源引用已完美变更为相对路径：
<!-- 纠偏后的相对路径引用 --><script type="module" crossorigin src="./assets/index-D7b39f.js"></script><link rel="stylesheet" crossorigin href="./assets/index-C8a12b.css">此时，Electron 通过 file:// 协议打开后，能顺利定位并加载位于当前 HTML 同级目录 assets/ 文件夹下的全部资源，应用即可平稳加载，黑屏彻底消除。
三、 联动防踩坑指南
仅修改 Vite 编译的相对路径还不够，在 SPA 打包桌面端时，还需要避开以下两个“连环坑”：
1. 前端路由模式必须切换为 Hash 路由
如果你的 SPA 项目使用了路由（如 Vue Router / React Router），在 Web 开发中常用的 HTML5 History 模式（createWebHistory）在 file:// 协议下会彻底失效：
- 因为 History 模式依赖于 Web 服务器将所有未匹配路径重写（Rewrite）指向
index.html。 file://协议下没有任何 Web 服务器提供重写服务，用户一旦发生路由跳转或直接刷新，浏览器就会因直连物理文件失败报错 404。- 对策：在打包桌面端时，必须将前端路由切换为 Hash 模式（
createWebHashHistory），利用#锚点控制页面逻辑，这能完美兼容file://本地访问。
import { createRouter, createWebHashHistory } from 'vue-router';
const router = createRouter({ // 必须使用 Hash 路由，坚决不用 HTML5 History 路由 history: createWebHashHistory(), routes: [ // ... 路由配置 ]});2. 自定义本地资源加载协议（高级方案）
如果因为特殊原因（如需要支持强隔离的 Cookie 或 Service Worker），项目必须使用标准的绝对路径进行资源引用，建议在 Electron 主进程中使用 protocol 模块，自定义注册一个伪 HTTP 协议，在内部拦截文件系统请求：
// main.js (Electron 主进程)const { app, BrowserWindow, net, protocol } = require('electron');const path = require('path');const { pathToFileURL } = require('url');
const distRoot = path.resolve(__dirname, 'dist');
// 必须在 app ready 之前注册特权协议protocol.registerSchemesAsPrivileged([ { scheme: 'app', privileges: { secure: true, standard: true } }]);
app.whenReady().then(() => { // 只允许 app://bundle/ 下的资源映射到 dist protocol.handle('app', (request) => { const url = new URL(request.url); if (url.host !== 'bundle') { return new Response('Not found', { status: 404 }); }
const relativePath = decodeURIComponent(url.pathname).replace(/^\/+/, '') || 'index.html'; const filePath = path.resolve(distRoot, relativePath); if (filePath !== distRoot && !filePath.startsWith(`${distRoot}${path.sep}`)) { return new Response('Forbidden', { status: 403 }); }
return net.fetch(pathToFileURL(filePath).toString()); });
const win = new BrowserWindow({ width: 800, height: 600 }); win.loadURL('app://bundle/index.html');});通过这一层拦截，应用可以在受限的自定义协议下读取 dist 资源，同时拒绝越过资源根目录的路径。对于一般项目，配置 Vite 相对路径 base: './' 仍然是更简单的方案；需要 Cookie、Service Worker 或安全来源语义时，再考虑自定义协议。
如果这篇文章对你有帮助，欢迎分享给更多人！
部分信息可能已经过时