feat: 初始化船长·HeiXiu 桌面应用项目(错误是svg的问题)

Electron + React 19 + TypeScript + Ant Design 6 + Tailwind CSS 4

  【核心架构】
  - Electron 主进程(窗口管理、平台检测、图标适配)
  - Vite 构建链(双产物 dist/ + dist-electron/)
  - 共享层 shared/(类型、常量、工具函数)
  - IPC 通信框架 + 安全守卫

  【主题系统】
  - 蓝紫渐变主题(亮色/暗色双模式)
  - Ant Design ConfigProvider 适配(lightAlgorithm / darkAlgorithm)
  - Tailwind CSS 4 @theme 指令 + CSS 变量
  - 设计令牌三处同步(tokens.ts / globals.css / antd-theme.ts)

  【导航栏】
  - 自定义 H5 导航栏替代系统菜单
  - 个人版/企业版双布局
  - 未登录拦截 + 事件总线驱动登录弹窗

  【登录注册】
  - Modal 弹层(Portal)+ Tabs 切换
  - 登录/注册表单动态字段渲染
  - 记住密码 / 自动登录 / 用户协议

  【更新系统】
  - 自定义 API 版本检查(替代 electron-updater generic provider)
  - 手动下载 + SHA512 校验 + spawn NSIS 安装
  - 渲染进程更新状态机 Hook(useUpdater)
  - 检查更新按钮 + 下载进度展示

  【构建工具链】
  - build.mjs 构建总管(--win/--mac/--linux --personal/--enterprise --build/--clean/--sign/--upload/--publish)
  - scripts/ 自动化脚本(clean / generate-update-info / upload-oss / publish-release)
  - electron-builder NSIS 安装器(可选路径、多版本打包)
  - update-info.json 自动生成(fileSize/sha512/changelog/releaseDate)

  【代码质量】
  - ESLint + TypeScript strict + Prettier
  - husky + lint-staged(提交前自动检查)
  - commitlint(规范提交信息)
  - Playwright E2E + Vitest 单元测试框架
  - rollup-plugin-visualizer 打包体积分析

  【文档】
  - README.md(快速开始 + 目录结构 + 命令速查)
  - UpdateA.md(发布手册:API/签名/发版流程/数据库)
  - CHANGELOG.md(更新日志)
  - .env.example(构建环境变量模板)
This commit is contained in:
2026-06-03 15:00:51 +08:00
commit 767bb8b297
95 changed files with 20814 additions and 0 deletions

25
scripts/clean.mjs Normal file
View File

@@ -0,0 +1,25 @@
// ============================================================
// 清理所有构建产物
// npm run build:clean
// ============================================================
import { rmSync, existsSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = join(__dirname, '..');
const dirs = ['release', 'dist', 'dist-electron'];
for (const dir of dirs) {
const p = join(ROOT, dir);
if (existsSync(p)) {
rmSync(p, { recursive: true, force: true });
console.log(`已清理: ${dir}/`);
} else {
console.log(`跳过(不存在): ${dir}/`);
}
}
console.log('\n清理完成。');

View File

@@ -0,0 +1,170 @@
// ============================================================
// 打包后自动生成 update-info.json
//
// 用法:
// node scripts/generate-update-info.mjs <platform> <edition> [version] [--url <url>]
//
// 两种用法:
// 方式 A预判 URL打包后自动拼接 URL → 适用于 OSS 路径可预测时
// node scripts/generate-update-info.mjs win32 personal
//
// 方式 B指定 URL上传后用实际 URL 重新生成 → 适用于上传后才知道 URL 时
// node scripts/generate-update-info.mjs win32 personal 0.1.0 --url "https://oss.../xxx.exe"
//
// 环境变量(可选):
// UPDATE_DOWNLOAD_BASE — 方式 A 的 URL 基地址,默认 https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases
// UPDATE_FORCE — 是否强制更新,默认 false
// UPDATE_MIN_VERSION — 最低兼容版本,默认 0.0.0
// UPDATE_CHANGELOG — 覆盖 CHANGELOG.md 中的日志内容
// ============================================================
import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { createHash } from 'node:crypto';
const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = join(__dirname, '..');
// ---------- 参数解析 ----------
const args = process.argv.slice(2);
// 提取 --url 参数
let urlOverride = '';
const positional = [];
for (let i = 0; i < args.length; i++) {
if (args[i] === '--url' && args[i + 1]) {
urlOverride = args[++i];
} else if (!args[i].startsWith('--')) {
positional.push(args[i]);
}
}
const platform = positional[0];
const edition = positional[1];
if (!platform || !edition) {
console.error('用法: node scripts/generate-update-info.mjs <platform> <edition> [version] [--url <url>]');
console.error('示例: node scripts/generate-update-info.mjs win32 personal');
console.error(' node scripts/generate-update-info.mjs win32 personal 0.1.0 --url "https://..."');
process.exit(1);
}
const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
const version = positional[2] || pkg.version;
const productName = pkg.build?.productName || '船长·HeiXiu';
// ---------- 查找安装包 ----------
const releaseDir = join(ROOT, 'release', version);
let installerPath;
try {
const files = readdirSync(releaseDir);
// 按扩展名找安装包
const exts = platform === 'win32' ? ['.exe'] : platform === 'darwin' ? ['.dmg'] : ['.AppImage'];
const match = files.find((f) => exts.some((ext) => f.endsWith(ext)));
if (!match) {
console.error(`未在 ${releaseDir} 中找到安装包文件`);
process.exit(1);
}
installerPath = join(releaseDir, match);
console.log(`找到安装包: ${match}`);
} catch {
console.error(`目录不存在: ${releaseDir}\n请先执行构建(如 npm run build:win`);
process.exit(1);
}
// ---------- 计算文件信息 ----------
const fileBuffer = readFileSync(installerPath);
const stats = statSync(installerPath);
// SHA512Base64 编码,与 certutil 输出一致)
const sha512 = createHash('sha512').update(fileBuffer).digest('base64').replace(/\r?\n/g, '');
const fileSize = stats.size;
console.log(`文件大小: ${(fileSize / 1024 / 1024).toFixed(2)} MB`);
console.log(`SHA512: ${sha512.slice(0, 32)}...`);
// ---------- 构建下载 URL ----------
const fileName = installerPath.split(/[/\\]/).pop();
let downloadUrl;
if (urlOverride) {
// 方式 B使用指定的 URL
downloadUrl = urlOverride;
console.log(`下载 URL手动指定: ${downloadUrl}`);
} else {
// 方式 A根据基地址 + 版本号 + 文件名拼接(预判 URL
const downloadBase = process.env.UPDATE_DOWNLOAD_BASE || 'https://heixiu.oss-cn-hangzhou.aliyuncs.com/releases';
downloadUrl = `${downloadBase.replace(/\/+$/, '')}/${version}/${encodeURI(fileName)}`;
console.log(`下载 URL自动拼接: ${downloadUrl}`);
}
// ---------- 读取更新日志 ----------
let changelog;
if (process.env.UPDATE_CHANGELOG) {
// 环境变量覆盖(适用于 CI/CD 流水线)
changelog = process.env.UPDATE_CHANGELOG;
} else {
// 从 CHANGELOG.md 提取最新版本的日志
const changelogPath = join(ROOT, 'CHANGELOG.md');
try {
const changelogContent = readFileSync(changelogPath, 'utf-8');
// 匹配最新版本块:## x.y.z日期 ... ## 或 EOF
const versionSection = changelogContent.match(
/^##\s+(\d+\.\d+\.\d+)[^\n]*\n([\s\S]*?)(?=^##\s|\Z)/m,
);
if (versionSection) {
changelog = versionSection[0].trim();
} else {
changelog = `## ${version}\n\n更新内容待补充`;
}
console.log(`更新日志: 已从 CHANGELOG.md 提取`);
} catch {
changelog = `## ${version}\n\n更新内容待补充`;
}
}
// ---------- 其他配置 ----------
const forceUpdate = process.env.UPDATE_FORCE === 'true';
const minimumVersion = process.env.UPDATE_MIN_VERSION || '0.0.0';
const releaseDate = new Date().toISOString().slice(0, 10);
// ---------- 生成 JSON ----------
const updateInfo = {
// --- 必填API 返回字段 ---
hasUpdate: true,
latestVersion: version,
downloadUrl,
fileSize,
sha512,
changelog,
releaseDate,
forceUpdate,
minimumVersion,
// --- 附加:方便后端录入 ---
_meta: {
platform,
edition,
fileName,
generatedAt: new Date().toISOString(),
},
};
const outputPath = join(
releaseDir,
`${productName}-${platform}-${edition}-v${version}-update-info.json`,
);
writeFileSync(outputPath, JSON.stringify(updateInfo, null, 2), 'utf-8');
console.log(`\n✅ 已生成: ${outputPath}`);
console.log(JSON.stringify(updateInfo, null, 2));

130
scripts/publish-release.mjs Normal file
View File

@@ -0,0 +1,130 @@
// ============================================================
// 发布版本信息到后端 API
//
// 用法:
// node scripts/publish-release.mjs <platform> <edition> [version] [--url <url>]
//
// 环境变量:
// UPDATE_API_URL — API 基地址(默认 https://www.heixiu.com
// UPDATE_API_KEY — API 鉴权 Key通过 Authorization: Bearer 头传递)
// ============================================================
import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import axios from 'axios';
const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = join(__dirname, '..');
// ---------- 参数 ----------
const args = process.argv.slice(2);
const positional = [];
let urlOverride = '';
let jsonOverride = '';
for (let i = 0; i < args.length; i++) {
if (args[i] === '--url' && args[i + 1]) {
urlOverride = args[++i];
} else if (args[i] === '--json' && args[i + 1]) {
jsonOverride = args[++i];
} else if (!args[i].startsWith('--')) {
positional.push(args[i]);
}
}
const platform = positional[0];
const edition = positional[1];
if (!platform || !edition) {
console.error('用法: node scripts/publish-release.mjs <platform> <edition> [version] [--url <url>]');
console.error('示例: node scripts/publish-release.mjs win32 personal 0.1.0');
process.exit(1);
}
const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
const version = positional[2] || pkg.version;
// ---------- 读取 update-info.json ----------
let updateInfo;
if (jsonOverride) {
try {
updateInfo = JSON.parse(jsonOverride);
} catch {
console.error('错误: --json 参数不是有效的 JSON');
process.exit(1);
}
} else {
const releaseDir = join(ROOT, 'release', version);
let infoFile;
try {
const all = readdirSync(releaseDir);
infoFile = all.find((f) =>
f.includes(platform) && f.includes(edition) && f.endsWith('-update-info.json'),
);
if (!infoFile) console.error(`未找到 ${platform}+${edition} 的 update-info.json`);
} catch (err) {
console.error(`错误: ${releaseDir}${err.message}`);
process.exit(1);
}
updateInfo = JSON.parse(readFileSync(join(releaseDir, infoFile), 'utf-8'));
if (urlOverride) updateInfo.downloadUrl = urlOverride;
}
// ---------- 发送到 API ----------
const apiBase = (process.env.UPDATE_API_URL || 'https://www.heixiu.com').replace(/\/+$/, '');
const apiKey = process.env.UPDATE_API_KEY || '';
const payload = {
platform,
edition,
latestVersion: updateInfo.latestVersion || version,
downloadUrl: updateInfo.downloadUrl,
fileSize: updateInfo.fileSize,
sha512: updateInfo.sha512,
changelog: updateInfo.changelog,
releaseDate: updateInfo.releaseDate,
forceUpdate: updateInfo.forceUpdate || false,
minimumVersion: updateInfo.minimumVersion || '0.0.0',
};
const endpoint = `${apiBase}/api/v1/releases`;
console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
console.log('📡 发布版本到 API');
console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
console.log(`POST ${endpoint}`);
console.log(`版本: ${version} (${platform}/${edition})`);
console.log(`URL: ${payload.downloadUrl}\n`);
try {
const response = await axios.post(endpoint, payload, {
headers: {
'Content-Type': 'application/json',
...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
},
timeout: 30000,
});
console.log('✅ 发布成功');
console.log(`响应: ${JSON.stringify(response.data, null, 2)}`);
} catch (err) {
const status = err.response?.status;
const data = err.response?.data;
if (status) {
console.error(`❌ 发布失败 HTTP ${status}: ${JSON.stringify(data)}`);
} else {
console.error(`❌ 请求失败: ${err.message}`);
}
console.log('\n💡 手动备选 — 把以下 JSON 发给后端:');
console.log(JSON.stringify(payload, null, 2));
process.exit(1);
}
console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');

161
scripts/upload-oss.mjs Normal file
View File

@@ -0,0 +1,161 @@
// ============================================================
// 上传安装包到阿里云 OSS
//
// 用法:
// node scripts/upload-oss.mjs <platform> <edition> [version]
//
// 环境变量(使用 Node.js 直传时需要):
// OSS_ENDPOINT — OSS endpoint如 oss-cn-hangzhou.aliyuncs.com
// OSS_BUCKET — Bucket 名称
// OSS_ACCESS_KEY_ID — AccessKey ID
// OSS_ACCESS_KEY_SECRET — AccessKey Secret
// OSS_BASE_PATH — Bucket 内基路径,默认 releases
//
// 不传 OSS 环境变量时 → 打印手动上传命令ossutil / 控制台)
//
// 示例:
// # 仅打印上传命令
// node scripts/upload-oss.mjs win32 personal 0.1.0
//
// # 直接上传
// OSS_BUCKET=heixiu OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com \
// OSS_ACCESS_KEY_ID=xxx OSS_ACCESS_KEY_SECRET=xxx \
// node scripts/upload-oss.mjs win32 personal 0.1.0
// ============================================================
import {readFileSync, readdirSync} from 'node:fs';
import {join, dirname} from 'node:path';
import {fileURLToPath} from 'node:url';
import {createHmac} from 'node:crypto';
const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = join(__dirname, '..');
// ---------- 参数 ----------
const platform = process.argv[2];
const edition = process.argv[3];
if (!platform || !edition) {
console.error('用法: node scripts/upload-oss.mjs <platform> <edition> [version]');
console.error('示例: node scripts/upload-oss.mjs win32 personal 0.1.0');
process.exit(1);
}
const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
const version = process.argv[4] || pkg.version;
// ---------- 查找安装包 ----------
const releaseDir = join(ROOT, 'release', version);
let installerName;
try {
const all = readdirSync(releaseDir);
const exts = platform === 'win32' ? ['.exe'] : platform === 'darwin' ? ['.dmg'] : ['.AppImage'];
installerName = all.find((f) => exts.some((e) => f.endsWith(e)));
if (!installerName) console.error(`错误: ${releaseDir} — 未找到安装包`);
} catch (err) {
console.error(`错误: ${releaseDir}${err.message}`);
process.exit(1);
}
const installerPath = join(releaseDir, installerName);
// ---------- OSS 配置 ----------
const {
OSS_ENDPOINT,
OSS_BUCKET,
OSS_ACCESS_KEY_ID,
OSS_ACCESS_KEY_SECRET,
} = process.env;
const basePath = (process.env.OSS_BASE_PATH || 'releases').replace(/^\/+|\/+$/g, '');
const objectKey = `${basePath}/${version}/${installerName}`;
// ---------- 模式 A无 OSS 配置 → 打印手动命令 ----------
if (!OSS_ENDPOINT || !OSS_BUCKET || !OSS_ACCESS_KEY_ID) {
const exampleBucket = OSS_BUCKET || '<bucket>';
const exampleEndpoint = OSS_ENDPOINT || '<endpoint>';
const downloadUrl = `https://${exampleBucket}.${exampleEndpoint}/${objectKey}`;
console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
console.log('📦 上传安装包(手动)');
console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
console.log(`文件: ${installerPath}`);
console.log(`大小: ${(readFileSync(installerPath).length / 1024 / 1024).toFixed(2)} MB\n`);
console.log('方式 1 — ossutil CLI推荐');
console.log(` ossutil cp "${installerPath}" oss://${exampleBucket}/${objectKey}\n`);
console.log('方式 2 — 阿里云控制台:');
console.log(` 登录 OSS 控制台 → ${exampleBucket} → 上传 → 目标路径: ${objectKey}\n`);
console.log('上传后执行以下命令,用实际 URL 重新生成 info');
console.log(` node scripts/generate-update-info.mjs ${platform} ${edition} ${version} --url "${downloadUrl}"\n`);
console.log('或直接发布到后端 API');
console.log(` node scripts/publish-release.mjs ${platform} ${edition} ${version} --url "${downloadUrl}"`);
console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
process.exit(0);
}
// ---------- 模式 BNode.js 直传 OSS ----------
const fileBuffer = readFileSync(installerPath);
const contentType = platform === 'win32'
? 'application/vnd.microsoft.portable-executable'
: 'application/octet-stream';
const date = new Date().toUTCString();
// 阿里云 OSS Authorization 签名
const stringToSign = [
'PUT',
'',
contentType,
date,
`/${OSS_BUCKET}/${objectKey}`,
].join('\n');
const signature = createHmac('sha1', OSS_ACCESS_KEY_SECRET)
.update(stringToSign)
.digest('base64');
const authHeader = `OSS ${OSS_ACCESS_KEY_ID}:${signature}`;
const downloadUrl = `https://${OSS_BUCKET}.${OSS_ENDPOINT}/${objectKey}`;
console.log(`上传中: ${installerName} (${(fileBuffer.length / 1024 / 1024).toFixed(2)} MB)`);
console.log(`目标: oss://${OSS_BUCKET}/${objectKey}`);
try {
const response = await fetch(downloadUrl, {
method: 'PUT',
headers: {
'Content-Type': contentType,
'Content-Length': String(fileBuffer.length),
'Date': date,
'Authorization': authHeader,
},
body: fileBuffer,
});
if (response.ok) {
console.log(`✅ 上传成功`);
console.log(`下载 URL: ${downloadUrl}\n`);
console.log('接下来:');
console.log(` # 重新生成 update-info.json`);
console.log(` node scripts/generate-update-info.mjs ${platform} ${edition} ${version} --url "${downloadUrl}"`);
console.log(`\n # 或直接发布到后端:`);
console.log(` node scripts/publish-release.mjs ${platform} ${edition} ${version} --url "${downloadUrl}"`);
} else {
const body = await response.text();
console.error(`❌ 上传失败 HTTP ${response.status}: ${body}`);
process.exit(1);
}
} catch (err) {
console.error(`❌ 上传失败: ${err.message}`);
process.exit(1);
}