YoungestSongMo
337d6c1205
## 构建、打包与分发系统重构 (build/) - 构建系统收敛至 build/ 目录：build.mjs + electron-builder.js + 6 个脚本 - electron-builder 配置从 package.json 提取为 build/electron-builder.js - 新增 --edition (personal/enterprise) 和 --channel (stable/beta/alpha) 参数 - OSS 路径按渠道隔离 - 新增 pre-build-check.mjs：Git/CHANGELOG/版本/环境变量校验 - 新增 bump-version.mjs：版本号管理 + CHANGELOG 自动生成 - updater.ts 发送 channel/edition/deviceFingerprint - 新增 src/shared/utils/rollout.ts 灰度测试工具 - 新增 10 条 NPM 脚本 ## VCHSM 五层架构迁移 - 7 个业务模块 + ~500 处导入路径同步 ## 修复 - MediaCardContextMenu 改用共享 ContextMenu 组件 - ComboBox 尺寸参数显示统一 (size-format.ts) ## 文档 - UpdateA.md / build/README.md / README.md / .env.example 更新 Co-Authored-By: Claude <noreply@anthropic.com>
184 lines
8.1 KiB
Markdown
184 lines
8.1 KiB
Markdown
# 船长·HeiXiu
|
||
|
||
> 桌面效率工作台 — Electron + React 19 + TypeScript + Ant Design + Tailwind CSS
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|----|--------------------------------|
|
||
| 框架 | Electron 42 |
|
||
| 前端 | React 19 + TypeScript + Vite 8 |
|
||
| UI | Ant Design 6 + Tailwind CSS 4 |
|
||
| 主题 | 蓝紫渐变（亮色 / 暗色） |
|
||
| 更新 | 自定义 API + 阿里云 OSS |
|
||
| 打包 | electron-builder + NSIS |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发模式（Electron + HMR）
|
||
npm run dev
|
||
|
||
# 打包（Windows 个人版）
|
||
npm run build:win
|
||
```
|
||
|
||
---
|
||
|
||
## 构建命令
|
||
|
||
### 打包
|
||
|
||
```bash
|
||
npm run build:win # Windows 个人版 Stable
|
||
npm run build:win:enterprise # Windows 企业版
|
||
npm run build:win:beta # Windows Beta 渠道（灰度测试）
|
||
npm run build:win:alpha # Windows Alpha 渠道（内部测试）
|
||
npm run build:mac # macOS 个人版
|
||
npm run build:linux # Linux 个人版
|
||
```
|
||
|
||
### 构建总管 `build/build.mjs`
|
||
|
||
所有打包命令最终调用 `build/build.mjs`，支持灵活组合操作：
|
||
|
||
```bash
|
||
# 查看帮助
|
||
node build/build.mjs --help
|
||
|
||
# 仅打包
|
||
node build/build.mjs --win
|
||
|
||
# 打包 + 上传 OSS + 发布到 API
|
||
node build/build.mjs --win --upload --publish
|
||
|
||
# Beta 渠道全流程（清理 → 构建 → 签名 → 上传 → 发布）
|
||
node build/build.mjs --win --channel beta --all
|
||
|
||
# 带签名打包
|
||
node build/build.mjs --win --sign --cert ./cert.pfx --cert-password xxx
|
||
```
|
||
|
||
| 操作 | 说明 |
|
||
|-------------|------------------------------------------------------------|
|
||
| `--build` | 构建（校验 → tsc → vite → electron-builder → update-info.json） |
|
||
| `--clean` | 构建前清理 release/ dist/ dist-electron/ |
|
||
| `--sign` | 代码签名（需配合 `--cert` 或 `CSC_LINK` 环境变量） |
|
||
| `--upload` | 上传安装包到 OSS |
|
||
| `--publish` | POST 版本信息到后端 API |
|
||
| `--all` | 全流程 |
|
||
| `--edition` | 版本类型：personal（默认）/ enterprise |
|
||
| `--channel` | 发布渠道：stable（默认）/ beta / alpha |
|
||
|
||
### 版本管理
|
||
|
||
```bash
|
||
npm run version:patch # 0.0.28 → 0.0.29
|
||
npm run version:pre-beta # 0.0.29 → 0.0.30-beta.1
|
||
```
|
||
|
||
### 工具命令
|
||
|
||
```bash
|
||
npm run build:clean # 清理所有构建产物
|
||
node build/scripts/upload-oss.mjs win32 0.1.0 # 手动上传 OSS
|
||
node build/scripts/publish-release.mjs win32 0.1.0 # 手动发布到 API
|
||
node build/scripts/generate-update-info.mjs win32 0.1.0 # 重新生成 info
|
||
```
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
ele-heixiu/
|
||
├── build/ # 构建、打包与分发系统
|
||
│ ├── build.mjs # 构建总管
|
||
│ ├── electron-builder.js # electron-builder 配置
|
||
│ └── scripts/ # 构建辅助脚本（6 个）
|
||
├── CHANGELOG.md # 更新日志
|
||
├── UpdateA.md # 发布手册
|
||
├── package.json # 项目配置
|
||
│
|
||
├── electron/ # Electron 主进程
|
||
│ ├── main.ts # 入口：窗口创建 / IPC 注册
|
||
│ ├── preload.ts # 预加载脚本
|
||
│ └── main/
|
||
│ ├── logger.ts # 日志核心
|
||
│ ├── updater.ts # 自动更新
|
||
│ ├── net-request.ts # HTTP 请求封装
|
||
│ ├── menu/ # 系统菜单
|
||
│ ├── ipc/ # IPC handler（log/safe-storage/storage/canvas）
|
||
│ └── utils/ # 平台判断 / 图标
|
||
│
|
||
├── src/ # 渲染进程（React 19 + Vite）
|
||
│ ├── app/ # 应用壳
|
||
│ │ ├── App.tsx # 根组件
|
||
│ │ ├── main.tsx # 渲染入口
|
||
│ │ ├── providers/ # 全局 Provider（App/Theme/Settings）
|
||
│ │ └── layout/ # Layout.tsx + PageDispatcher.tsx
|
||
│ ├── modules/ # 7 个业务模块（VCHSM 五层架构）
|
||
│ │ ├── navbar/ # 导航栏 UI 壳
|
||
│ │ ├── announcement/ # 公告（Badge + 轮询缓存）
|
||
│ │ ├── auth/ # 认证（登录/注册/密码/Token）
|
||
│ │ ├── home/ # 主工作区（左/中/右 三栏）
|
||
│ │ ├── account/ # 账户与支付（6 子功能）
|
||
│ │ ├── canvas/ # 无限画布 + 项目管理
|
||
│ │ └── settings/ # 应用设置
|
||
│ └── shared/ # 跨模块共享
|
||
│ ├── components/ # 通用 UI
|
||
│ ├── hooks/ # 全局 Hooks
|
||
│ ├── services/ # HTTP 客户端
|
||
│ ├── utils/ # 工具函数（bus/env/...）
|
||
│ ├── infrastructure/ # 本地加密数据库
|
||
│ └── theme/ # 主题系统
|
||
│
|
||
├── shared/ # 主进程 & 渲染进程共享（@shared 别名）
|
||
│ ├── constants/ # IPC 通道 / 应用常量
|
||
│ ├── types/ # Platform / Theme / Logging
|
||
│ └── utils/ # 脱敏 / 工具函数
|
||
│
|
||
├── release/ # 构建产物
|
||
└── build/ # 构建系统（见上）
|
||
```
|
||
|
||
> 详见 [PROJECT.md](./PROJECT.md) — 完整架构文档、VCHSM 五层说明及各模块文件清单。
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
主进程加载顺序：`.env.{mode}` → `.env.local` → OS 环境变量 → 代码默认值。
|
||
|
||
| 变量 | 默认值 | 用途 |
|
||
|-------------------------|--------------------------------------------------------|---------------|
|
||
| `UPDATE_API_URL` | `https://www.heixiu.com` | 版本检查 API |
|
||
| `UPDATE_API_KEY` | — | 发布 API 鉴权 |
|
||
| `UPDATE_DOWNLOAD_BASE` | `https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases` | OSS 下载基地址 |
|
||
| `OSS_ENDPOINT` | — | OSS endpoint |
|
||
| `OSS_BUCKET` | — | OSS bucket |
|
||
| `OSS_ACCESS_KEY_ID` | — | OSS AccessKey |
|
||
| `OSS_ACCESS_KEY_SECRET` | — | OSS Secret |
|
||
| `CSC_LINK` | — | 签名证书路径 |
|
||
| `CSC_KEY_PASSWORD` | — | 签名证书密码 |
|
||
| `VITE_API_BASE_URL` | `http://8.160.179.64:8000`（dev） | 业务 API 基地址 |
|
||
|
||
> **`.env.local`**（不进 git）用于个人特殊配置，如打包后覆盖 `UPDATE_API_URL` 指向本地测试服务器。
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
| 文档 | 面向 | 内容 |
|
||
|--------------------------------------------------|-------|-----------------------|
|
||
| [PROJECT.md](./PROJECT.md) | 开发者 | 技术架构、更新系统、环境变量架构、测试流程 |
|
||
| [UpdateA.md](./UpdateA.md) | 前端发版 | 构建命令、发版流程、代码签名 |
|
||
| [test-server/README.md](./test-server/README.md) | 后端程序员 | API 规格、数据库表结构、实现清单 |
|