# electronTemplate

**Repository Path**: xbkjlm/electron-template

## Basic Information

- **Project Name**: electronTemplate
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-04
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# My Electron App

基于 Electron Forge + Webpack 的桌面应用模板，面向“低维护、易扩展”。

## 目录
1. 项目概览
2. 快速开始
3. 目录结构
4. 首次配置必做（更新源/上传源/仓库）
5. IPC 服务（自动发现）
6. 前端如何调用后端函数
7. 菜单与托盘（配置驱动）
8. 自动更新（generic/HTTP）
9. 版本管理
10. 发布与上传
11. 常见问题

## 1. 项目概览

核心能力：
- 主进程服务自动发现与 IPC 自动暴露
- 菜单/托盘配置驱动（只改 `ui.js` + action 文件）
- 版本号自动递增（满 10 进 1）
- `electron-updater` 更新检查（generic/HTTP）
- 打包后自动生成 `latest.yml` 并支持多种上传方式

## 2. 快速开始

```bash
npm install
npm run start
```

常用命令：
```bash
npm run start
npm run make
npm run publish
```

## 3. 目录结构

- `src/main/`：主进程
- `src/renderer/`：渲染进程
- `src/shared/ipc/`：IPC 描述与自动生成 manifest
- `src/main/services/`：主进程服务（自动发现）
- `src/main/menu-actions/`：菜单动作（自动发现）
- `src/main/tray-actions/`：托盘动作（自动发现）
- `src/main/config/ui.js`：菜单/托盘配置（你主要改这个）
- `src/main/config/release.js`：更新/上传/Git 配置
- `scripts/`：构建与发布脚本

## 4. 首次配置必做（更新源 / 上传源 / 仓库）

### 4.1 更新源（更新服务器地址）
在 `src/main/config/release.js` 中设置：
```js
update: {
  serverUrl: 'https://your-update-server.example.com/updates'
}
```
该地址需要能访问到 `latest.yml` 和更新包。

### 4.2 上传源（发布上传地址）
同样在 `src/main/config/release.js` 中设置：
```js
upload: {
  method: 'http', // http | copy | ftp
  httpUrl: 'https://your-upload-server.example.com/upload',
  copyDir: 'D:\publish\my-app',
  ftp: {
    host: 'ftp.example.com',
    user: 'youruser',
    pass: 'yourpass',
    remoteDir: '/my-app'
  }
}
```
选择一种方式即可，未配置的方式会自动跳过。

### 4.3 仓库地址（Git）
在 `package.json` 中配置：
```json
"repository": {
  "type": "git",
  "url": "git@gitee.com:xbkjlm/electron-template.git"
}
```
`git:auto-commit` 会读取该地址并自动设置 `origin`。

## 5. IPC 服务（自动发现）

### 5.1 新增服务
在 `src/main/services/` 新建文件：
```js
// src/main/services/userService.js
class UserService {
  static channel = 'user-api';

  async getProfile() {
    return { name: 'Alice' };
  }
}

module.exports = { UserService };
```

服务名默认等于文件名：`userService.js` -> `userService`。

### 5.2 自动生成 manifest
启动时会自动执行：
```bash
npm run services:gen
```
生成：`src/shared/ipc/services.manifest.json`

## 6. 前端如何调用后端函数

前端通过 `electronAPI.<服务名>.<方法>` 调用主进程服务方法，所有方法统一返回 Promise。

后端示例：
```js
// src/main/services/mainApi.js
class MainAPIService {
  static channel = 'main-api';

  async getMessage() {
    return 'Hello';
  }
}

module.exports = { MainAPIService };
```

前端调用：
```js
import { electronAPI } from './api';

const message = await electronAPI.mainApi.getMessage();
console.log(message);
```

## 7. 菜单与托盘（配置驱动）

你只需要修改 `src/main/config/ui.js`。

### 7.1 是否隐藏菜单栏
```js
menu: {
  autoHideMenuBar: true,
  menuBarVisible: false
}
```

### 7.2 自定义菜单（列名 + 功能）
```js
menu: {
  columnsOrder: ['文件', '视图', '帮助'],
  items: [
    { menu: '文件', label: '刷新', action: 'reload' },
    { menu: '文件', label: '退出', action: 'quit' },
    { menu: '视图', label: '切换开发者工具', action: 'toggleDevTools' },
    { menu: '帮助', label: '关于', action: 'showAbout' }
  ]
}
```

### 7.3 托盘配置
```js
tray: {
  enabled: true,
  tooltip: 'My Electron App',
  icon: path.join(__dirname, '..', '..', '..', 'assets', 'tray.png'),
  menu: [
    { label: '显示主窗口', action: 'showWindow' },
    { label: '隐藏主窗口', action: 'hideWindow' },
    { type: 'separator' },
    { label: '退出', action: 'quit' }
  ]
}
```

### 7.4 Action 实现位置
- 菜单动作：`src/main/menu-actions/*.js`
- 托盘动作：`src/main/tray-actions/*.js`

示例：
```js
// src/main/menu-actions/reload.js
const action = (mainWindow) => () => mainWindow?.reload();
module.exports = { action };
```

## 8. 自动更新（generic/HTTP）

### 8.1 客户端配置
更新源地址从 `src/main/config/release.js` 读取：
```js
update: {
  serverUrl: 'https://your-update-server.example.com/updates'
}
```

### 8.2 发布端生成 `latest.yml`
打包完成后自动生成：
- `release/latest.yml`
- `out/make/latest.yml`

### 8.3 更新检查
主进程已调用：
```js
autoUpdater.checkForUpdatesAndNotify();
```

## 9. 版本管理（满 10 进 1）

手动执行：
```bash
npm run version:bump
```

规则示例：
- `1.0.9 -> 1.1.0`
- `1.9.9 -> 2.0.0`

## 10. 发布与上传

上传方式统一从 `src/main/config/release.js` 读取：
```js
upload: {
  method: 'http', // http | copy | ftp
  httpUrl: 'https://your-upload-server.example.com/upload',
  copyDir: 'D:\publish\my-app',
  ftp: {
    host: 'ftp.example.com',
    user: 'youruser',
    pass: 'yourpass',
    remoteDir: '/my-app'
  }
}
```

上传脚本：`scripts/release/upload.js`

## 11. 常见问题

### 11.1 `package.json` JSON 解析报错
如果提示 `Unexpected token`，通常是 BOM 导致。请保存为 UTF‑8 无 BOM。

### 11.2 托盘不显示
检查 `assets/tray.png` 是否存在，路径是否正确。

### 11.3 IPC 调用不到
确认服务类有 `static channel`，方法名未以下划线 `_` 开头。

## 许可
MIT