# electronApp

**Repository Path**: ranjingqiao3_admin/electron-app

## Basic Information

- **Project Name**: electronApp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-11
- **Last Updated**: 2026-03-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BladeX桌面应用 Electron 客户端开发手册

## 1. 项目概览

本项目是基于 Electron + Vue 3 的桌面端 CRM 客户端。

- 应用名称：`BladeX桌面应用`
- 版本号：`1.0.12`
- 主进程入口：`src/main`
- 渲染进程入口：`src/renderer`
- 打包工具：`electron-builder`
- 构建工具：`electron-vite`

## 2. 技术栈与环境要求

- Node.js：建议使用 `22.15.0`（仓库脚本历史上使用该版本）
- 包管理器：`pnpm`（仓库包含 `pnpm-lock.yaml`）
- Electron：`40.2.1`
- 前端框架：Vue 3 + Vue Router + Vuex + Element Plus

## 3. 目录结构说明

```text
.
├─ build/                  # 打包资源与签名脚本、主进程环境变量
├─ resources/              # asarUnpack 资源（加载页、图标等）
├─ src/
│  ├─ main/                # Electron 主进程
│  ├─ preload/             # 预加载脚本
│  └─ renderer/            # Vue 渲染进程
├─ vite/plugins/           # Vite 插件配置
├─ electron.vite.config.js # Electron + Vite 构建配置
└─ electron-builder.yml    # 打包配置
```

## 4. 本地开发

### 4.1 安装依赖

```bash
pnpm install
```

注意：项目配置了 `postinstall=electron-builder`，安装依赖后会触发一次打包流程。

### 4.2 启动开发模式

```bash
pnpm dev
```

- 默认开发端口：`2888`
- 开发代理：`/api -> http://192.168.3.114:18006/`
- 如需切换后端地址，请修改 `electron.vite.config.js` 的 `server.proxy`。

### 4.3 预览构建产物

```bash
pnpm start
```

### 4.4 代码规范

```bash
pnpm lint
pnpm format
```

## 5. 环境变量说明

### 5.1 渲染进程环境变量（根目录）

- `.env.development`
  - `VITE_APP_ENV=development`
  - `VITE_APP_API=/api`
  - `VITE_APP_BASE=/`
- `.env.production`
  - `VITE_APP_ENV=production`
  - `VITE_APP_API`、`VITE_APP_API_BASEURL`
  - `VITE_BUILD_COMPRESS=gzip`

### 5.2 主进程环境变量（build 目录）

- `build/.env`
- `build/.env.development`
- `build/.env.production`

主进程通过 `RENDERER_` 前缀读取配置（见 `electron.vite.config.js`）。

### 5.3 API 基础地址解析规则

见 `src/renderer/src/config/env.js`：

1. 优先使用 `VITE_APP_API`
2. 如果为空，回退到 `VITE_APP_API_BASEURL`
3. 打包后 `file://` 场景下，若 `VITE_APP_API` 是相对路径（如 `/api`），会优先使用 `VITE_APP_API_BASEURL`

## 6. 构建与打包说明

### 6.1 仅构建代码

```bash
pnpm build
```

会执行 `electron-vite build`，生成主进程/预加载/渲染进程构建产物。

### 6.2 按平台打包

```bash
pnpm build:win
pnpm build:mac
pnpm build:linux
```

对应脚本：先执行 `build`，再执行 `electron-builder --<platform> --config`。

### 6.3 打包产物位置与命名

- 输出目录：`dist/`
- Windows 安装包命名：`${name}-${version}-setup.${ext}`
- macOS DMG 命名：`${name}-${version}.${ext}`
- Linux AppImage 命名：`${name}-${version}.${ext}`

### 6.4 electron-builder 关键配置

- 配置文件：`electron-builder.yml`
- `appId`: `cn.garyee.crm`
- `productName`: `CRM`
- Windows：NSIS 安装包，支持自定义安装目录
- Linux：`AppImage`、`snap`、`deb`
- `asarUnpack`：`resources/*`

### 6.5 macOS 公证（Notarize）

- 钩子脚本：`build/notarize.js`
- 仅在 `darwin` 且 `CI` 环境中执行
- 需配置 Apple 账号相关环境变量后才会执行公证

## 7. 自动更新发布说明

项目使用 `electron-updater`，发布源为 `generic`。

- 生产打包更新地址：`electron-builder.yml -> publish.url`
- 开发调试更新地址：`dev-app-update.yml -> url`

发布时请确保将安装包及更新元数据（如 `latest.yml`）同步上传到对应 OSS 目录。

## 8. 常见问题

### 8.1 开发环境接口不通

优先检查：

1. `electron.vite.config.js` 中代理目标地址是否可达
2. `.env.development` 的 `VITE_APP_API` 是否为 `/api`
3. 后端是否允许当前来源访问

### 8.2 打包后接口请求失败

`file://` 协议下相对路径代理不可用，请确保生产环境配置了可访问的 `VITE_APP_API_BASEURL`。