Electron 中 file:// 协议失效的根本原因是其解析逻辑与浏览器不同且平台路径容忍度不一；应优先使用 loadFile() 加载 HTML，配合 <base> 标签指定绝对路径，并保持 webSecurity 为 true 以提前暴露路径问题。
Electron 中用 file:// 协议加载本地 HTML 时，路径错误或协议处理不当会导致白屏、资源 404、脚本不执行等问题——根本原因不是“写法不对”，而是 Electron 对 file:// 的解析逻辑与浏览器存在关键差异，且不同平台对路径格式容忍度不同。
为什么 file:// 在 Electron 里经常失效
Chrome 浏览器允许 file:///path/to/index.html（三个斜杠），但 Electron 主进程的 win.loadFile() 不走 file:// 协议，而是直接读取文件系统；而渲染进程内通过 file:// 加载子资源（如 <script src="js/main.js">）时，实际拼接的是相对路径 + 当前 URL 基址，容易因路径分隔符或 base href 错误崩掉。
- Windows 下
file://C:\app\index.html会被解析为file:///C:/app/index.html，但反斜杠未转义会中断 URL 解析 - macOS/Linux 下
file:///Users/name/app/index.html看似正确，但若 HTML 中引用./assets/logo.png，Electron 渲染器可能因缺少<base>或当前工作目录偏差而 404 -
win.loadURL('file://' + path)是危险写法：未标准化路径、未 encodeURI、未适配平台分隔符
loadFile() 比 loadURL() + file:// 更可靠
主进程创建窗口时，优先用 win.loadFile()，它绕过 URL 解析层，直接由 Electron 内部读取并注入 file:// 协议，自动处理路径标准化和平台适配。
- ✅ 正确：
win.loadFile('index.html')（路径相对于process.cwd()） - ✅ 安全增强：
win.loadFile(path.join(__dirname, 'index.html'))（__dirname确保绝对路径） - ❌ 避免：
win.loadURL('file://' + path.resolve('index.html'))（需手动 encodeURI、处理 Windows 盘符、跨平台分隔符） - ⚠️ 注意：
loadFile()不支持 query 参数，传参要用 IPC 或 URL hash
渲染进程内资源引用必须用 <base> + 相对路径
当 HTML 通过 loadFile() 加载后，其 base URL 是 file:///absolute/path/to/。但 Electron 渲染器对相对路径解析不如 Chrome 严格，尤其在嵌套子目录或使用 <iframe> 时易出错。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- ✅ 必须在
<head>中声明：<base href="file:///<absolute-path>/">（路径末尾带斜杠） - ✅ 生成 base href 的安全方式：
pathToFileURL(path.join(__dirname, 'index.html')).href→ 取 dirname 部分 - ❌ 不要依赖
window.location.origin：在file://下它返回"null"，不可靠 - ⚠️ 图片/CSS/JS 引用统一用相对路径，如
src="./assets/icon.svg"，避免../跨级跳转
开发阶段禁用 webSecurity 会掩盖真实路径问题
设 webPreferences: { webSecurity: false } 后，file:// 资源加载看似正常，但上线打包后 ASAR 归档会让所有 file:// 路径指向 app.asar/ 内部，此时未标准化的路径直接失败。
- ✅ 开发时保持
webSecurity: true（默认），尽早暴露路径错误 - ✅ 打包前验证：用
electron-builder构建后，手动检查app.asar.unpacked/结构是否匹配 HTML 中的src和href - ⚠️
asar: false仅用于调试，不能作为长期方案——它让应用体积暴涨且失去 ASAR 的加载性能优势
真正麻烦的不是怎么写路径，而是 Electron 在 loadFile()、ASAR 封装、<base> 解析三者之间的隐式耦合。漏掉任意一环，跨平台就变成“在 macOS 上跑通，在 Windows 上报错，Linux 上白屏”。
