Vite + Vue 项目打包为 Electron 桌面应用完整指南

（适配 Windows 环境，解决网络/白屏/配置错误等常见问题）

一、前置准备（解决网络问题，避免安装报错）

1. 清理之前的失败安装残留

打开项目终端（PowerShell），执行：

powershell 复制代码

# 删除损坏的依赖和锁文件
rm -r node_modules
rm package-lock.json
rm yarn.lock

2. 配置国内镜像（解决 Electron 下载失败）

bash 复制代码

# 配置 Electron 镜像
yarn config set electron_mirror https://npmmirror.com/mirrors/electron/
# 配置打包工具镜像
yarn config set electron_builder_binaries_mirror https://npmmirror.com/mirrors/electron-builder-binaries/

二、核心配置（按顺序操作，避免踩坑）

🔴 关键说明：两个 `main.js` 的区别

文件位置	文件名	作用	是否需要修改
`src/main.js`	Vue 项目入口	启动网页项目	完全无需修改，保持原样
`项目根目录/main.js`	Electron 入口	创建桌面窗口、加载打包后的网页	需新建，放在和 `package.json` 同级的根目录

1. 修改 `vite.config.js`（解决打包后白屏问题）

将文件内容替换为以下代码：

javascript 复制代码

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  // 核心：配置相对路径，避免桌面端加载资源失败
  base: './'
})

2. 新建项目根目录 `main.js`（Electron 主进程文件）

在项目根目录 （和 package.json 同级）新建文件 main.js，复制以下代码：

javascript 复制代码

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

// 创建桌面窗口
function createWindow() {
  const win = new BrowserWindow({
    width: 1000,   // 窗口宽度，可自定义
    height: 700,   // 窗口高度，可自定义
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false
    }
  })

  // 加载 Vite 打包后的 dist 文件夹
  win.loadFile(path.join(__dirname, 'dist/index.html'))

  // 调试用：可选打开开发者工具
  // win.webContents.openDevTools()
}

// Electron 初始化完成后创建窗口
app.whenReady().then(createWindow)

// 所有窗口关闭时退出应用
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

3. 修改 `package.json`（完整可直接替换）

将文件内容替换为以下代码（适配你的 temp_project 项目）：

json 复制代码

{
  "name": "temp_project",
  "private": true,
  "version": "0.0.0",
  "main": "main.js",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "electron:dev": "electron .",
    "electron:build": "electron-builder"
  },
  "dependencies": {
    "vue": "^3.5.32"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^6.0.6",
    "electron": "^41.3.0",
    "electron-builder": "^24.13.3",
    "vite": "^8.0.10"
  },
  "build": {
    "appId": "com.tomatoclock.app",
    "win": {
      "target": "nsis",
      "icon": "public/favicon.ico"
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true
    },
    "files": [
      "dist/**/*",
      "main.js"
    ]
  }
}

注意：已删除导致报错的 "type": "module"，无需手动修改。

4. 安装所有依赖

执行命令安装依赖（含 electron 和 electron-builder）：

bash 复制代码

yarn install

三、本地测试（先跑通再打包，避免白屏/报错）

1. 打包 Vue 项目（生成 `dist` 文件夹）

bash 复制代码

yarn build

执行完成后，项目根目录会生成 dist 文件夹，代表 Vue 打包成功。

2. 启动 Electron 桌面窗口

bash 复制代码

yarn electron:dev

✅ 弹出桌面窗口、正常显示你的番茄钟项目，说明配置全部正确。

四、打包为 EXE 桌面应用

执行打包命令，生成可分发的桌面软件：

bash 复制代码

yarn electron:build

打包结果说明

执行完成后，项目根目录会生成 dist_electron 文件夹，包含两个关键文件：

Setup.exe：安装包，可发给他人安装使用
win-unpacked 文件夹：免安装绿色版，直接打开文件夹内的 temp_project.exe 即可运行

五、更新代码后如何生成新版本

修改 Vue 代码后，按以下流程生成最新版桌面软件：

1. 本地快速测试更新（无需打包 EXE）

bash 复制代码

# 1. 重新打包 Vue 代码，更新 dist 文件夹
yarn build
# 2. 启动 Electron 窗口查看最新效果
yarn electron:dev

2. 正式打包最新版 EXE

bash 复制代码

# 1. 重新打包 Vue 代码
yarn build
# 2. 重新打包为最新桌面软件
yarn electron:build

记忆口诀：改代码 → yarn build → yarn electron:build

六、常见问题排查

1. 打包后打开白屏

原因：未配置 vite.config.js 中的 base: './'，或 dist 文件夹路径错误
解决：重新执行 yarn build，确保 dist/index.html 存在，且 vite.config.js 已添加 base: './'

2. 执行 `yarn electron:dev` 报错

原因：main.js 放错位置（需在根目录）、package.json 未配置 "main": "main.js"
解决：检查 main.js 是否在根目录，确认 package.json 中 main 字段正确

3. Electron 安装/打包时网络报错（ECONNRESET）

原因：未配置国内镜像，下载失败
解决：重新执行镜像配置命令，再重新安装依赖/打包

4. 图标不显示

原因：public/favicon.ico 不存在，或 package.json 中 icon 路径错误
解决：将你的图标文件放在 public 文件夹，命名为 favicon.ico（或修改 package.json 中 icon 的路径）

需要我帮你补充一个「自定义窗口图标、修改应用名称」的进阶配置吗？

Vite + Vue 项目打包为 Electron 桌面应用 完整指南