OQ桌面端Electron+Vite+Vue3完整打包部署教程（从零到生成安装包）

OQ 桌面端 Electron + Vite + Vue3 完整打包部署教程（从零到生成安装包）

技术栈：Vue3 + Vite (rolldown) + electron + vite-plugin-electron + electron-builder
目标：打包生成 绿色免安装版 exe + NSIS 安装包（支持自动创建桌面快捷方式）
解决痛点：打包网络超时、打包后页面空白、打包卡在扫描 node\_modules、桌面图标空白等坑

前置准备

环境要求

1. Node.js 版本推荐：20.x 或 22.x（LTS 长期支持版）
2. 包管理器：yarn（本项目使用 yarn）
3. 网络：能访问 npm 镜像；打包时需要下载 electron 本体、nsis 工具包
4. 项目目录结构参考

OQ项目根目录
├─ dist/                # vite打包前端产物（打包自动生成）
├─ dist-electron/       # electron主进程打包产物（自动生成）
├─ public/              # 静态资源，放logo.png / logo.ico图标
├─ src/                 # vue前端源码
├─ electron/            # electron主进程源码（main.ts/main.js）
├─ vite.config.js       # vite配置【关键】
├─ package.json         # 项目依赖与打包配置【关键】

⚠️ 重要前置说明：

1. 前端打包必须使用相对路径，否则打包后 exe 打开空白
2. Vue-Router 不能用createWebHistory，必须用createWebHashHistory哈希路由，否则本地打开白屏
3. 图标：想要桌面快捷方式图标正常，需要准备 256×256 的 logo.ico，png 格式打包后桌面图标大概率空白

一、安装依赖（新建项目 / 已有项目）

1. 安装全套依赖

yarn add -D electron electron-builder vite-plugin-electron vite-plugin-electron-renderer
yarn add vue vue-router element-plus vant

本项目使用 rolldown vite，package.json 中 resolutions 锁定 vite 版本。

2. vite.config.js 完整配置（解决白屏核心！）

重点：base: './' 相对路径，必须写

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import electron from 'vite-plugin-electron'
import renderer from 'vite-plugin-electron-renderer'
import path from 'node:path'

export default defineConfig({
  base: './', // ✅ 核心！打包资源使用相对路径，防止electron打包白屏
  plugins: [
    vue(),
    electron([
      {
        // Electron主进程入口文件
        entry: 'electron/main.js',
        onstart(options) {
          options.startup()
        },
        vite: {
          build: {
            sourcemap: false,
            outDir: 'dist-electron',
            rollupOptions: {
              external: ['electron']
            }
          }
        }
      }
    ]),
    renderer()
  ],
  build: {
    outDir: 'dist',
    emptyOutDir: true,
    rollupOptions: {
      // 可选：后续优化大包js代码分割，现在可以注释不影响打包
      // output: {
      //   manualChunks: {
      //     vue: ['vue', 'vue-router'],
      //     ui: ['element-plus','vant']
      //   }
      // }
    }
  }
})

3. Electron 主进程 electron/main.js（窗口代码，生产加载页面）

import { app, BrowserWindow } from 'electron'
import path from 'node:path'

let mainWindow

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    // 全屏配置，按需开启
    // fullscreen: true,
    webPreferences: {
      nodeIntegration: false,
      contextIsolation: true
    }
  })

  // 开发环境：加载vite开发服务器
  if (process.env.NODE_ENV === 'development') {
    mainWindow.loadURL('http://localhost:5173')
  } else {
    // ✅ 生产打包：加载dist下index.html，路径不能写错！
    mainWindow.loadFile(path.join(__dirname, '../dist/index.html'))
  }

  // 打开开发者工具（打包测试阶段可打开，正式发布注释掉）
  // mainWindow.webContents.openDevTools()
}

app.whenReady().then(() => {
  createWindow()
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

4. Vue-Router 路由修改（防止白屏）

src/router/index.js

import { createRouter, createWebHashHistory } from 'vue-router'
import Home from '../views/Home.vue'

const routes = [
  { path: '/', component: Home }
]

const router = createRouter({
  history: createWebHashHistory(), // ✅ 哈希模式！不要用createWebHistory
  routes
})

export default router

5. package.json 完整配置（打包核心配置，直接复制替换）

{
  "name": "dianwan",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "main": "dist-electron/main.js",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "electron:dev": "vite",
    "electron:build": "vite build && electron-builder"
  },
  "dependencies": {
    "element-plus": "^2.13.2",
    "less": "^4.4.1",
    "vant": "^4.9.21",
    "vue": "^3.5.22",
    "vue-router": "^4.5.1"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^6.0.1",
    "axios": "^1.20.0",
    "electron": "^44.5.1",
    "electron-builder": "^26.15.3",
    "vite": "npm:rolldown-vite@7.1.14",
    "vite-plugin-electron": "^1.1.2",
    "vite-plugin-electron-renderer": "^1.0.0"
  },
  "resolutions": {
    "vite": "npm:rolldown-vite@7.1.14"
  },
  "description": "OQ_PC 桌面客户端",
  "author": {
    "name": "魏双喜"
  },
  "build": {
    "appId": "com.dianwan.app",
    "productName": "dianwan",
    "win": {
      "target": "nsis",
      "icon": "public/logo.png"
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true,
      "createDesktopShortcut": true,
      "createStartMenuShortcut": true,
      "shortcutName": "dianwan"
    },
    "files": [
      "dist/**/*",
      "dist-electron/**/*",
      "public/**/*",
      "!node_modules/**/*",
      "!src/**/*"
    ]
  }
}

配置说明：

1. main：electron 主进程打包后的入口文件，不能错
2. files：只打包必要文件，排除 node\_modules、src 源码，解决打包卡在扫描依赖的问题
3. nsis：安装包配置，自动勾选桌面快捷方式、允许用户自定义安装目录
4. win.icon：图标路径，正式发布替换成 public/logo.ico

二、打包完整操作步骤（PowerShell 终端执行）

进入项目根目录，打开 PowerShell 窗口

步骤 1：设置国内镜像（解决 electron 下载超时，必执行）

注意：PowerShell 命令，不要在 cmd 里运行

$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"

这个环境变量仅对当前打开的 PowerShell 窗口生效。关闭窗口后下次打包需要重新输入。

步骤 2：执行一键打包命令

yarn electron:build

打包会自动执行两件事：

1. vite build：打包 Vue 前端代码，输出到dist文件夹
2. electron-builder：打包 electron 程序，生成绿色版 + NSIS 安装包

打包过程中会自动下载资源（只下载一次，缓存本地）

1. electron-v44.5.1-win32-x64.zip（electron 运行本体）
2. nsis 安装程序包、7zip、图标资源包

如果下载超时：手动下载 electron 压缩包放到缓存目录 %LOCALAPPDATA%\electron\Cache，不要解压。

步骤 3：打包成功标志

终端输出：Done in xxx seconds.，无红色报错。

步骤 4：打包产物位置

项目根目录 → dist 文件夹

1. 绿色免安装版（测试优先用这个）
   dist\win-unpacked\dianwan.exe
   直接双击运行，不需要安装，用来优先测试页面、全屏、窗口图标。
2. NSIS 安装包（发给用户使用）
   dist\dianwan Setup 0.0.0.exe
   运行安装向导，安装时自动创建桌面快捷方式、开始菜单图标。

三、打包后测试流程（按顺序）

1. 优先测试绿色版 dist/win-unpacked/dianwan.exe

   • 打开看页面是否正常、有没有白屏
   • 按 Ctrl+Shift+I 调出开发者工具，查看控制台报错
   • 测试功能、窗口、全屏逻辑

2. 绿色版没问题，再测试安装包 dianwan Setup 0.0.0.exe

   • 运行安装包，自定义安装路径
   • 安装完成，查看桌面是否生成 dianwan 快捷图标
   • 打开桌面图标验证程序

⚠️ 图标问题：当前配置使用 png，Windows 桌面快捷图标会空白。
解决：准备 256×256 的logo.ico放入 public 文件夹，修改 package.json "icon": "public/logo.ico"，重新打包。

四、常见坑与排错清单

坑 1：打包打开 exe 空白页面

✅ 原因 1：vite 没有写base:'./'
✅ 原因 2：vue-router 使用 history 模式，改成createWebHashHistory()
✅ 原因 3：主进程加载页面路径错误，loadFile(path.join(__dirname, '../dist/index.html'))

坑 2：打包卡在 searching for node modules

✅ 解决：package.json 的 build -\> files 配置，添加 "!node_modules/**/*"，排除 node\_modules

坑 3：electron 下载超时 ETIMEDOUT

✅ 方案 1：PowerShell 设置淘宝镜像 $env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
✅ 方案 2：手动下载 electron zip 放到 %LOCALAPPDATA%\electron\Cache，不解压

坑 4：打包报 unknown property 'allowMissingDependencies'

✅ 新版 electron-builder26.x 不支持该配置，直接删掉这一行。

坑 5：桌面快捷方式图标空白

✅ 必须使用.ico图标，png 无法在 Windows 快捷方式正常显示。在线工具 png 转 ico，尺寸 256×256。

坑 6：开发环境正常，打包后接口请求失败

✅ 检查接口地址，不要写localhost，使用后端公网地址。

坑 7：打包体积巨大

✅ files 配置排除 src、node\_modules；后续可以做路由懒加载、代码分割减小 js 体积。

五、发布交付

把 dianwan Setup 0.0.0.exe 发给用户，用户双击即可安装，自动生成桌面图标。
绿色版win-unpacked适合内部测试，不建议直接发给普通用户使用。