CSS离线加载失败主因是资源未打包或缓存失效，须手动确保CSS随应用分发：检查build.files显式包含*.css、用固定相对路径引用、验证asar包内存在文件、preload中读取注入style标签、禁用@import和远程字体、内联关键CSS，并通过link.sheet和getComputedStyle双重校验加载状态。
CSS在离线状态下加载失败，不是路径问题，而是资源未被正确打包或缓存策略失效。 Electron本身不提供离线CSS自动兜底机制，必须手动确保样式文件随应用分发，并在渲染进程启动前完成加载。关键在于构建阶段的资源包含、运行时的路径解析、以及网络不可用时的 fallback 行为控制。
确保CSS文件被打包进最终应用
Electron打包工具（如electron-builder或electron-packager）默认不会递归包含HTML中href引用的相对路径CSS，尤其当路径含./或../时容易遗漏。
- 检查
build.files配置是否显式包含**/*.css，例如 electron-builder 的package.json中："files": ["dist/**/*", "styles/**/*", "index.html"] - 避免使用动态拼接路径加载CSS（如
href="${theme}.css"），构建工具无法静态分析，会导致离线缺失 - 推荐将CSS放在与
index.html同级或resources/子目录下，并用固定相对路径引用，例如：<link rel="stylesheet" href="resources/styles/main.css"> - 构建后检查生成目录（如
dist/mac/MyApp.app/Contents/Resources/app.asar）是否真包含该CSS文件，可用asar list app.asar | grep main.css验证
用file://协议加载时路径必须绝对化
Electron渲染进程默认以file://协议加载本地HTML，此时相对路径解析基于当前文件位置，而非Web服务器根路径。若HTML由loadFile()加载，其基路径是应用资源根目录；若用loadURL('file://...')，则需手动构造绝对file://路径。
- 错误写法：
<link rel="stylesheet" href="./styles/main.css">—— 在ASAR包内可能解析失败 - 安全写法：在preload脚本中用
path.join(__dirname, 'styles', 'main.css')生成绝对路径，再通过fs.promises.readFile读取内容并注入<style></style>标签，绕过路径解析 - 更轻量做法：在主进程
createWindow()前，用app.getAppPath()拼出CSS完整file://路径，传给渲染进程：mainWindow.webContents.executeJavaScript(`document.head.innerHTML += '<link rel="stylesheet" href="%24%7BcssUrl%7D">';`)
离线时禁用@import和远程字体请求
@import语句和@font-face src: url(...)在file://协议下默认被Chromium拦截（CSP限制或协议不匹配），且无网络时无法fallback，直接导致样式断裂或FOUC（Flash of Unstyled Content）。
立即学习“前端免费学习笔记（深入）”；
- 彻底删除CSS文件中的
@import，改用构建时合并（如PostCSSpostcss-import） - 字体资源必须本地化：把WOFF2文件放入项目目录，
@font-face中用相对路径引用，并确认打包后存在 - 添加内联关键CSS到HTML的
中（如主题色、布局骨架），保证即使后续CSS加载延迟或失败，基础UI仍可读 - 在渲染进程检查
navigator.onLine，若为false，可主动移除可能触发网络请求的<link>（如CDN图标字体）并加载备用本地样式
避免CSS加载阻塞首屏渲染
即使所有CSS都已本地化，<link rel="stylesheet">仍是渲染阻塞资源。Electron窗口show: false时用户看不到白屏，但若CSS加载慢，ready-to-show事件会延迟触发，延长用户等待时间。
- 对非首屏必需的CSS（如打印样式、暗黑模式切换样式），改用
rel="stylesheet" media="print"或动态link.setAttribute('media', 'all')激活 - 启用
webPreferences.preload脚本，在DOM解析早期注入<style></style>，比<link>更快生效 - 不要在CSS中使用
url()引用大图或字体——它们会触发额外HTTP请求（即使file://），应转为base64内联或确保文件已打包 - 实测发现：一个120KB未压缩CSS + 3个本地字体文件（共800KB），在低端设备上可使
ready-to-show延迟增加300ms以上
最易被忽略的一点：CSS加载是否成功，不能只靠link.onload监听，因为file://协议下该事件可能不触发；必须结合link.sheet是否存在、getComputedStyle(document.body).color是否符合预期来双重校验。离线场景下，任何“假设已加载”的逻辑都会导致静默失败。
