Electron 踩坑实录：主窗口 icon 配置了，打包 Windows 后死活不显示？（全网最细排查+解决方案）

做 Electron 开发，几乎人人都会碰到这个经典坑：

开发环境运行好好的，窗口左上角 icon 正常；打包成 Windows 安装包/exe 后，窗口图标变回默认 Electron 图标，甚至直接空白。

我翻了无数 issue、踩了一遍又一遍路径/格式/配置的坑，今天把完整排查链路 + 可直接复制的正确配置整理出来，按顺序查一遍，99% 的问题都能解决。

核心前提 ：Windows 平台只认 .ico 格式 ，直接用 PNG/重命名改后缀无效；图标尺寸建议 256x256，多尺寸内嵌更稳。

一、先搞懂：你是不是只配了一半？（最常见错误）

很多人以为：在 new BrowserWindow 里传 icon 就完事了。

真相是：Windows 打包后，窗口图标 ≠ 代码里的 icon 路径，它依赖打包工具（electron-builder）把图标打进安装包与资源目录。

你只做了第一步，没做第二步：

✅ 代码里写了 icon: xxx
❌ 没在 electron-builder 配置里指定 win.icon
❌ 图标没被正确打包进 resources
❌ 路径用了相对/开发环境路径，打包后找不到

二、第一步：准备合规的 ICO 文件（别再瞎转格式）

Windows 对图标要求很严格，这一步错了，后面配置全白搭：

必须是 .ico 格式 ：PNG 直接改后缀 .ico 无效，要用工具转换
尺寸标准 ：推荐 256x256，内嵌 16x16/32x32/48x48/256x256 多尺寸
推荐工具：
1. 在线：icoconverter.com
2. 本地：Greenfish Icon Editor、icotool

项目结构建议（固定放根目录 build 文件夹，打包工具默认识别）

css 复制代码

你的项目/
├── build/
│   └── icon.ico   # 256x256 合规 ICO
├── src/
├── main.js        # 主进程
└── package.json

三、第二步：主进程代码正确写法（路径必须用 path 拼接）

开发环境 + 打包环境通用，不要写相对路径，不要用 import/require 图片：

javascript 复制代码

const { app, BrowserWindow } = require('electron')
const path = require('path')

function createWindow() {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    // 关键：用 path.resolve 获取绝对路径，兼容打包后
    icon: path.resolve(__dirname, '../build/icon.ico'),
    webPreferences: {
      nodeIntegration: false,
      contextIsolation: true
    }
  })

  // 加载页面
  if (process.env.NODE_ENV === 'development') {
    mainWindow.loadURL('http://localhost:3000')
  } else {
    mainWindow.loadFile(path.join(__dirname, '../index.html'))
  }
}

app.whenReady().then(createWindow)

小提示：__dirname 是当前文件所在目录，路径层级根据你的项目结构调整，确保打包后依然能定位到 icon.ico。

四、第三步：electron-builder 配置（最关键！决定打包是否生效）

这一步 90% 的人漏配或配错，直接导致窗口图标不生效，在 package.json中添加：

json 复制代码

{
  "name": "your-app",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "dev": "electron .",
    "build:win": "electron-builder --win"
  },
  "build": {
    "appId": "com.yourapp.id",
    "win": {
      "icon": "build/icon.ico",   // 必须指定，打包进 exe/安装包
      "target": "nsis"            // 安装包格式
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true
    },
    "files": [
      "dist/**/*",
      "main.js",
      "build/icon.ico"  // 把图标强制打包进资源目录
    ]
  }
}

五、第四步：按顺序排查（打包后依然不显示？查这 5 点）

1. 清理缓存 + 重建打包（最容易忽略）

bash 复制代码

# 删除旧打包产物
rm -rf dist build win-unpacked
# 清除 electron-builder 缓存
rm -rf node_modules/.cache/electron-builder
# 重新打包
npm run build:win

2. 检查图标是否被打包进去

打开 win-unpacked/resources
确认 icon.ico 存在，路径和代码一致

3. 清理 Windows 图标缓存（系统显示旧图标）

Windows 会缓存图标，导致新图标不刷新，新建fix-icon.bat 右键以管理员运行：

bash 复制代码

taskkill /f /im explorer.exe
cd /d %localappdata%
del IconCache.db /a
start explorer.exe

4. 不要用管理员权限运行测试（权限导致图标不加载）

以管理员身份运行 exe，有时会因权限问题无法加载资源图标，普通双击运行 测试。

5. 确认 ICO 文件未损坏、尺寸合规

直接双击 icon.ico，Windows 能正常预览才是合格文件；预览异常就重新转换。

六、高频误区总结（别再踩了）

❌ 只用 PNG 格式，不转 ICO
❌ 代码里写相对路径（如 ./build/icon.ico）
❌ 只配代码 icon，不配 package.json 的 win.icon
❌ 打包后用管理员运行测试
❌ 不清理旧缓存，直接覆盖打包

七、最终验证

重新打包完成
进入 win-unpacked，双击 exe 运行
查看窗口左上角、任务栏图标，已变成自定义 ICO

Electron 在 Windows 上的图标问题，本质就是格式合规 + 路径绝对 + 打包配置齐全 + 缓存清理，按上面流程走一遍，基本一次搞定。

如果你用的是 electron-packager 而非 electron-builder，原理一致，只需在打包命令加上 --icon=build/icon.ico 即可。

觉得有用就点赞收藏，下次打包碰到图标问题直接回来抄作业，少走半天弯路～