船长·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

---

快速开始

# 安装依赖
npm install

# 开发模式（Electron + HMR）
npm run dev

# 打包（Windows 个人版）
npm run build:win

---

构建命令

打包

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，支持灵活组合操作：

# 查看帮助
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

版本管理

npm run version:patch            # 0.0.28 → 0.0.29
npm run version:pre-beta         # 0.0.29 → 0.0.30-beta.1

工具命令

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 — 完整架构文档、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	开发者	技术架构、更新系统、环境变量架构、测试流程
UpdateA.md	前端发版	构建命令、发版流程、代码签名
test-server/README.md	后端程序员	API 规格、数据库表结构、实现清单