个人桌面端

Appearance

快速开始 ​

环境准备 ​

系统要求 ​

  • Node.js: >= v18.0.0
  • pnpm: >= v8.6.0
  • 操作系统: Windows 7/8/10/11, macOS, Linux

版本限制

项目已通过 package.json 限制了 Node.js 和 pnpm 的最低版本，安装时会自动检查。

安装 pnpm ​

推荐使用 pnpm 作为包管理工具，性能更优且节省磁盘空间。

bash
# 设置 npm 官方源
npm config set registry https://registry.npmjs.org

# 全局安装 pnpm
npm install -g pnpm

# 验证安装
pnpm --version

项目初始化 ​

克隆项目 ​

bash
git clone https://github.com/your-repo/vue3-simple-electron.git
cd vue3-simple-electron

安装依赖 ​

bash
# 安装所有依赖（包括主进程和渲染进程）
pnpm install

Electron 依赖问题

Electron 依赖在国内网络环境下可能会安装失败，即使设置了国内镜像源。

验证 Electron 依赖 ​

bash
# 验证 Electron 是否安装成功
pnpm verify:electron-deps

如果验证失败，执行修复命令：

bash
# 修复 Electron 依赖
pnpm fix:electron-deps

开发模式 ​

启动开发服务器 ​

bash
# 同时启动渲染进程和主进程（推荐）
pnpm dev

# 或者分别启动
pnpm dev:renderer  # 启动 Vue 开发服务器
pnpm dev:main      # 启动 Electron 主进程

启动后，Electron 窗口会自动打开，并加载 Vue 开发服务器（默认 http://localhost:5173）。

开发服务器特性 ​

  • ✅ 热模块替换（HMR）
  • ✅ Vue 3 响应式刷新
  • ✅ 主进程自动重启
  • ✅ 实时错误提示
  • ✅ 开发者工具集成

目录结构 ​

vue3-simple-electron/
├── packages/
│   ├── main/              # 主进程代码
│   │   ├── src/
│   │   │   ├── main.js    # 入口文件
│   │   │   ├── apps/      # 应用初始化
│   │   │   ├── core/      # 核心功能
│   │   │   ├── services/  # 服务层
│   │   │   └── ...
│   │   └── package.json
│   └── renderer/          # 渲染进程代码
│       ├── src/
│       │   ├── main.js    # Vue 入口
│       │   ├── App.vue    # 根组件
│       │   ├── pages/     # 页面
│       │   └── components/# 组件
│       ├── index.html     # 主页面
│       └── vite.config.js # Vite 配置
├── resources/             # 资源文件
│   ├── config/           # 配置文件
│   ├── icons/            # 应用图标
│   └── installers/       # 安装程序
├── docs/                 # 项目文档
├── package.json          # 根配置
└── electron-builder.config.js  # 打包配置

打包构建 ​

开发环境打包（目录形式） ​

适合测试，不生成安装包：

bash
# 打包为未压缩的目录
pnpm build:dir

输出位置：dist/win-unpacked/ 或 dist/mac/

生产环境打包 ​

Windows 平台 ​

bash
# 打包 Windows 安装包（默认 x64）
pnpm build

# 输出文件：
# dist/vue3-simple-electron-1.0.0-setup.exe  # 安装程序
# dist/vue3-simple-electron-1.0.0.exe        # 便携版

Linux 平台 ​

bash
# 在 Linux 上打包
pnpm build:linux

# 在 Windows 上交叉编译 Linux 包
pnpm build:linux

# 输出文件：
# dist/vue3-simple-electron-1.0.0.AppImage
# dist/vue3-simple-electron-1.0.0.deb

Linux 构建特别说明 ​

建议使用docker进行打包(尝试后windows下最简单可靠的方式), 下面步骤就是基于docker打包简短说明，如有其他情况需要自行查询解决。

删除项目依赖 ​

  • 删除当前所有项目的依赖node_modules
  • 删除当前项目的pnpm-lock.yaml文件

配置docker镜像源 ​

建议配置国内的docker镜像源，防止拉取依赖时超时

Docker Engine中配置如下：

json
{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://registry.docker-cn.com"
  ]
}

拉取打包容器 ​

sh
docker pull electronuserland/builder:wine

执行打包命令 ​

注意：如果是在vscode中的话需要使用pwsh(powershell)执行。

sh
docker run --rm -ti -v ${PWD}:/project -w /project electronuserland/builder:wine /bin/bash -c "pnpm install && pnpm run build:linux"

注意：有的时候可能会报下面的错误，再执行一遍即可

报错信息：

json
.../node_modules/electron postinstall$ node install.js
│ RequestError: connect ECONNREFUSED 20.205.243.166:443
│     at ClientRequest.<anonymous> (/project/node_modules/.pnpm/got@11.8.6/node_modules/got/dist/source/core/index.js:970:111)
│     at Object.onceWrapper (node:events:633:26)
│     at ClientRequest.emit (node:events:530:35)
│     ...
└─ Failed in 27.9s at /project/node_modules/.pnpm/electron@33.2.1/node_modules/electron

查看打包结果 ​

等待上述命令执行完成后，再项目的dist文件中会显示打包之后的文件，分发安装即可。

打包配置 ​

编辑 electron-builder.config.js 自定义打包选项：

javascript
module.exports = {
  appId: 'com.yourcompany.app',
  productName: 'YourAppName',
  directories: {
    output: 'dist',
    buildResources: 'resources',
  },
  win: {
    target: ['nsis', 'portable'],
    icon: 'resources/icons/icon.ico',
  },
  nsis: {
    oneClick: false, // 单击安装
    allowToChangeInstallationDirectory: true,
    createDesktopShortcut: true, // 创建桌面快捷方式
    createStartMenuShortcut: true, // 创建开始菜单快捷方式
    shortcutName: 'YourApp',
  },
};

配置应用 ​

修改应用配置 ​

编辑 resources/config/config.ini：

ini
[App]
# 应用标题
electronTitle=Vue3-Simple-Electron

# 加载模式：remote(远程) 或 local(本地)
loadMode=remote

# 远程 URL
electronUrl=https://your-domain.com

# 或使用本地服务器
# loadMode=local
# localWebPath=/resources/web

[Window]
# 窗口尺寸
width=1200
height=800

# 是否最大化启动
maximized=false

[Server]
# 启用本地服务器
enableLocalServer=true
localServerPort=8080

[Plugin]
# 启用插件系统
enablePluginSystem=true

[Update]
# 自动检查更新
autoCheckUpdate=true
updateCheckInterval=3600000  # 1小时

配置代理规则 ​

编辑 resources/config/proxy-rules.yaml：

yaml
proxies:
  # API 代理
  - path: /api
    target: https://api.example.com
    changeOrigin: true
    pathRewrite:
      '^/api': ''

  # 文件上传代理
  - path: /upload
    target: https://upload.example.com
    changeOrigin: true
    timeout: 60000

常见问题 ​

Q1: Electron 安装失败 ​

错误信息：

Electron failed to install correctly, please delete node_modules/electron and try installing again

解决方案：

bash
# 方案 1：执行修复命令
pnpm fix:electron-deps

# 方案 2：清除缓存重装
pnpm store prune
rm -rf node_modules
pnpm install

# 方案 3：使用国内镜像
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
pnpm install

Q2: 开发模式启动失败 ​

检查项：

  1. Node.js 版本是否 >= 18.0.0
  2. pnpm 是否正确安装
  3. 端口 5173 是否被占用
bash
# 查看 Node.js 版本
node --version

# 查看 pnpm 版本
pnpm --version

# 检查端口占用（Windows）
netstat -ano | findstr :5173

# 检查端口占用（Mac/Linux）
lsof -i :5173

Q3: 打包后应用无法启动 ​

可能原因：

  1. 资源文件路径错误
  2. 配置文件缺失
  3. 依赖未正确打包

调试方法：

bash
# 查看打包日志
pnpm build --verbose

# 使用目录模式打包测试
pnpm build:dir

# 检查打包文件
cd dist/win-unpacked
./vue3-simple-electron.exe

Q4: 页面加载空白 ​

检查项：

  1. 开发环境：Vite 服务器是否启动
  2. 生产环境：静态资源是否正确打包
  3. 配置文件中的 URL 是否正确
javascript
// 检查主进程日志
console.log('加载 URL:', loadUrl);

// 开发环境
loadUrl = 'http://localhost:5173';

// 生产环境
loadUrl = path.join(__dirname, '../renderer/index.html');

下一步 ​

开发提示 ​

代码格式化 ​

bash
# ESLint 检查
pnpm lint:eslint

# Prettier 格式化
pnpm lint:prettier

# 拼写检查
pnpm lint:spell-check

提交代码 ​

项目使用 Commitlint 规范提交信息：

bash
# 使用交互式提交
pnpm commit

# 提交格式
# feat: 新功能
# fix: 修复 bug
# docs: 文档更新
# style: 代码格式调整
# refactor: 重构
# test: 测试相关
# chore: 构建/工具变动

版本发布 ​

bash
# 自动生成 CHANGELOG 并打 tag
pnpm release        # 自动判断版本类型
pnpm release:patch  # 补丁版本 1.0.0 -> 1.0.1
pnpm release:minor  # 次版本 1.0.0 -> 1.1.0
pnpm release:major  # 主版本 1.0.0 -> 2.0.0

文档相关 ​

启动文档服务器 ​

bash
# 开发模式
pnpm docs:dev

# 访问 http://localhost:5173

打包文档 ​

bash
# 构建静态文档
pnpm docs:build

# 预览构建结果
pnpm docs:preview

发布文档 ​

版本文件注意

Electron 打包完成后，需要把打包的 zip 包放到 docs/public/versions 目录下，用于版本下载。

由于 Git 对文件大小有限制，docs/public/versions 已添加到 .gitignore，但不影响文档打包和发布。

技术支持 ​

基于 MIT 许可发布

Copyright © 2024-2025 框架作者(LMX) 版权所有