Electron+Vue3+Vite+TypeScript项目手工创建操作手册

长风CodeLab
1,758 阅读5分钟

网络上找过很多关于Electron+Vue3+Vite+TypeScript项目手工创建的资料，都不是很完美，笔者经过尝试整理了下相对完整的操作手册，给有需要的小伙伴参考。

1 创建Vue3+Vite项目

适用范围：有Vue开发经验并且已经具备了Node开发环境熟悉npm、cnpm、yarn等操作的小伙伴

  • 基于模板创建项目

按照交互界面引导按需配置即可，注意选择TypeScript，其他不赘述

npm create vite@latest electron-vue-vite-ts --template vue-ts
  • VSCode打开electron-vue-vite-ts或者cd electron-vue-vite-ts
  • npm i完成初始化
  • npm run dev试运行确认是否有问题

2 安装Electron依赖

  • 安装electron(比较特殊，单独安装)，如果npm安装不成功，可以尝试cnpm install electron -D，如果还是不行，可直接移步最后常见问题查找解决办法
npm install electron -D
  • 其他包安装（就放在一起了），如下为功能大致说明

electron-builder：打包工具

electron-devtools-installer：开发调试工具

vite-plugin-electron、vite-plugin-electron-renderer：集成Vite和Electron，方便后续在渲染进程中使用Node API或Electron API

rimraf：快速删除某些文件和文件夹

npm install electron-builder electron-devtools-installer vite-plugin-electron vite-plugin-electron-renderer rimraf -D

3 创建及管理Electron项目文件

  • 项目根目录创建electron-main文件夹，在electron-main中新建index.ts文件，参考示例代码如下：
// electron-main/index.ts
import { app, BrowserWindow } from "electron"
import path from "path"

const createWindow = () => {
  const win = new BrowserWindow({
    webPreferences: {
      contextIsolation: false, // 是否开启隔离上下文
      nodeIntegration: true, // 渲染进程使用Node API
      preload: path.join(__dirname, "./preload.js"), // 需要引用js文件
    },
  })

  // 如果打包了，渲染index.html
  if (process.env.NODE_ENV !== 'development') {
    win.loadFile(path.join(__dirname, "./index.html"))
    win.webContents.openDevTools()
  } else {
    let url = "http://localhost:5173" // 本地启动的vue项目路径。注意：vite版本3以上使用的端口5173；版本2用的是3000
    win.loadURL(url)
    win.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()
  }
})
  • 项目根目录创建electron-preload目录，在electron-preload目录新建preload.ts文件，参考示例代码如下：

注意避坑：preload.ts不要与preload-main中的index.ts同名，后文会说明为什么，这里先放个彩蛋

// electron-preload/preload.ts
import os from "os";
console.log("platform", os.platform());

4 修改项目配置文件

4.1 修改tsconfig.json

  • 增加electron相关的监听，增加配置内容如下，electron-main/**/*.ts及electron-preload/**/*.ts为新增配置
"include": [
  "src/**/*.ts",
  "src/**/*.d.ts",
  "src/**/*.tsx",
  "src/**/*.vue",
  "electron-main/**/*.ts",
  "electron-preload/**/*.ts"
]

4.2 修改vite.config.ts

  • 将当前独立的vite与electron关联起来

【补充说明】：

  • electron()是可以传入数组对象的，网上很多教程或者案例都是传入对象，导致很多小伙伴只知道electron-main/index.ts(对应electron项目main.js)怎么配，而不知道perload.js怎么配。

  • electron()支持传递数组，因而可以配置main及preload入口，但由于统一输出到outDir: "dist-electron"同一个目录，由此main及preload不建议创建同名的ts文件，否则会有冲突

  • outDir: "dist-electron"交代了输出地址

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

import electron from "vite-plugin-electron"
import electronRenderer from "vite-plugin-electron-renderer"
import polyfillExports from "vite-plugin-electron-renderer"



// https://vitejs.dev/config/
export default defineConfig(({ mode }) => ({
  base: mode == 'development' ? '' : './',
  plugins: [
    vue(),
    electron([{
      entry: "electron-main/index.ts", // 主进程文件
    },
    {
      entry: 'electron-preload/preload.ts'
    }
    ]),
    electronRenderer(),
    polyfillExports(),
  ],
  build: {
    emptyOutDir: false, // 默认情况下，若 outDir 在 root 目录下，则 Vite 会在构建时清空该目录
    outDir: "dist-electron"
  },
}));

4.3 修改package.json文件

  • 删除"type":"module"
  • 增加"main": "dist-electron/index.js"
  • "build"修改为"build": "rimraf dist-electron && vite build && electron-builder"
  • 修改dev运行命令，增加chcp 65001支持中文显示，"scripts": {"dev": "chcp 65001 && vite",...}
  • （如果不涉及打包，可以不配置）增加配置build配置（配置build才能打包成功，具体含义可以官网查询），注意files及output配置的路径，files打包关联路径，output为后续包生成路径
// 参考示例
{
  "name": "electron-vue-vite-ts",
  "private": true,
  "version": "0.0.0",
  "main": "dist-electron/index.js",
  "scripts": {
    "dev": "chcp 65001 && vite",
    "build": "rimraf dist-electron && vite build && electron-builder",
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.2.47"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^4.1.0",
    "electron": "^25.1.0",
    "electron-builder": "^23.6.0",
    "electron-devtools-installer": "^3.2.0",
    "rimraf": "^5.0.1",
    "typescript": "^5.0.2",
    "vite": "^4.3.9",
    "vite-plugin-electron": "^0.11.2",
    "vite-plugin-electron-renderer": "^0.14.5",
    "vue-tsc": "^1.4.2"
  },
  "build": {
    "appId": "com.electron.desktop",
    "productName": "electron",
    "asar": true,
    "copyright": "Copyright © 2022 electron",
    "directories": {
      "output": "release/${version}"
    },
    "files": [
      "./dist",
      "./package.json",
      "./dist-electron"
    ],
    "mac": {
      "artifactName": "${productName}_${version}.${ext}",
      "target": [
        "dmg"
      ]
    },
    "win": {
      "target": [
        {
          "target": "nsis",
          "arch": [
            "x64"
          ]
        }
      ],
      "artifactName": "${productName}_${version}.${ext}"
    },
    "nsis": {
      "oneClick": false,
      "perMachine": false,
      "allowToChangeInstallationDirectory": true,
      "deleteAppDataOnUninstall": false
    },
    "publish": [
      {
        "provider": "generic",
        "url": "http://127.0.0.1:8080"
      }
    ],
    "releaseInfo": {
      "releaseNotes": "版本更新的具体内容"
    }
  }
}

4.4 修改.gitignore

  • 增加忽略dist-electron

5 运行测试

  • dev测试： npm run dev
  • 运行成功会看到经典的count++界面
  • 由于有vite加持，支持hotreload，无需额外配置
  • 打包测试： npm run build

打包涉及远程仓库必要的压缩文件下载，有失败风险，耐心够的话，多尝试几次 正常在release目录下会生成exe文件，安装即可

image.png

6 可能会遇到的问题及解决办法

6.1 electron下载失败

6.1.1 快速尝试（偷懒）办法

  • npm install electron -D切换为cnpm install electron -D，前提是有配置好cnpm
  • npm install electron -D切换为yarn add electron -D

6.1.2 配置镜像源等方法

  • npm设置镜像源后重试

npm config set electron_mirror npm.taobao.org/mirrors/ele…

  • yarn设置镜像源后重试

yarn config set ELECTRON_MIRROR npm.taobao.org/mirrors/ele…

6.1.3 一劳永逸法（不推荐）

  • 全局安装，以npm为例

npm config set ELECTRON_MIRROR npm.taobao.org/mirrors/ele…

npm install electron -g

vue add electron-builder

6.2 electron运行提示找不到preload.js文件

  • vite.config.ts中的electron需要挂载preload.ts，electron()支持存入数组、对象，也即同时支持electron-main/index.ts及electron-preload/preload.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

import electron from "vite-plugin-electron"
import electronRenderer from "vite-plugin-electron-renderer"
import polyfillExports from "vite-plugin-electron-renderer"



// https://vitejs.dev/config/
export default defineConfig(({ mode }) => ({
  base: mode == 'development' ? '' : './',
  plugins: [
    vue(),
    electron([{
      entry: "electron-main/index.ts", // 主进程文件
    },
    {
      entry: 'electron-preload/preload.ts'
    }
    ]),
    electronRenderer(),
    polyfillExports(),
  ],
  build: {
    emptyOutDir: false, // 默认情况下，若 outDir 在 root 目录下，则 Vite 会在构建时清空该目录
    outDir: "dist-electron"
  },
}));

6.3 Electron Security Warning (Insecure Content-Security-Policy) This renderer process has either no Content Security

  • 只是警告，可以不用处理
  • 在根目录下的index.html增加head标签中增加如下信息
<meta http-equiv="Content-Security-Policy" content="script-src 'self'" />

6.4 build打包完成后运行程序页面是白屏

  • 确定环境判断条件是否正确：环境判断应根据process.env.NODE_ENV，而不是app.isPackaged（很多老教程写的是这个，恒不成立）
  • 确定index.html加载路径是否正确：index.html加载路径是win.loadFile(path.join(__dirname, "../dist-electron/index.html"))而非win.loadFile(path.join(__dirname, "../index.html"))

基于如上方法即可愉快地开启Electron+Vue3+Vite+TypeScript项目开发之旅了，不当之处请指正，任何问题也欢迎留言交流。分享转发还请注明出处。

avatar
文章
阅读
粉丝