cutThink_lite/docs/BUILD-GUIDE.md

CutThenThink Lite - 构建与发布完整指南

本文档提供了 CutThenThink Lite 应用的完整构建和发布流程。

目录

• 系统要求
• 本地开发
• 多平台构建
• CI/CD 流程
• 发布流程
• 故障排除

系统要求

基础工具

• Node.js: 18.0 或更高版本
• npm: 9.0 或更高版本
• Rust: 1.70 或更高版本（通过 rustup 安装）

平台特定要求

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y \
    libgtk-3-dev \
    libwebkit2gtk-4.0-dev \
    libappindicator3-dev \
    librsvg2-dev \
    patchelf

macOS

xcode-select --install

Windows

下载并安装 Microsoft C++ Build Tools 安装 "Desktop development with C++" 工作负载

本地开发

1. 环境检查

运行环境检查脚本：

./scripts/check-build.sh

2. 安装依赖

npm install

3. 开发模式

启动开发服务器（热重载）：

npm run tauri:dev

4. 构建前端

仅构建前端（不打包桌面应用）：

npm run build

多平台构建

方法 1: 使用构建脚本（推荐）

完整构建：

./scripts/build.sh

开发构建：

./scripts/dev.sh

仅打包前端：

./scripts/package-frontend.sh

方法 2: 直接使用 npm 命令

npm run build              # 构建前端
npm run tauri:build        # 构建 Tauri 应用

方法 3: 使用 Docker（Linux）

如果不想安装本地依赖，可以使用 Docker：

./scripts/docker-build.sh

构建输出位置

构建完成后，产物位于：

Linux:

src-tauri/target/release/bundle/
├── appimage/          # .AppImage 文件
├── deb/               # .deb 安装包
└── release/           # 未打包的二进制文件

Windows:

src-tauri/target/release/bundle/
├── nsis/              # .exe 安装程序
└── msi/               # .msi 安装程序

macOS:

src-tauri/target/release/bundle/
├── dmg/               # .dmg 磁盘映像
└── macos/             # .app 应用包

CI/CD 流程

项目使用 GitHub Actions 进行自动化构建。

工作流文件

• .github/workflows/test.yml - PR 测试
• .github/workflows/build.yml - 发布构建

触发构建

通过 Git 标签（推荐）：

git tag v0.1.0
git push origin v0.1.0

通过 GitHub 界面：

1. 进入 Actions 页面
2. 选择 "Build and Release" 工作流
3. 点击 "Run workflow"
4. 选择分支并运行

构建矩阵

CI/CD 自动构建以下平台：

• ✅ Ubuntu (x86_64)
• ✅ Windows (x86_64)
• ✅ macOS (x86_64 + ARM64)

发布流程

发布前检查清单

使用发布检查清单：

cat docs/RELEASE-CHECKLIST.md

步骤 1: 准备发布

1. 更新版本号：

   • package.json 中的 version
   • src-tauri/tauri.conf.json 中的 version
   • src-tauri/Cargo.toml 中的 version

2. 更新 CHANGELOG：

   # 编辑 CHANGELOG.md
   # 添加新版本的变化内容
   

3. 提交更改：

   git add .
   git commit -m "Release v0.1.0"
   

步骤 2: 创建标签

git tag -a v0.1.0 -m "Release v0.1.0"
git push origin main
git push origin v0.1.0

步骤 3: CI/CD 构建

推送标签后，GitHub Actions 会自动：

1. 构建所有平台
2. 运行测试
3. 创建构建产物

等待构建完成（大约 10-20 分钟）。

步骤 4: 创建 GitHub Release

1. 前往 GitHub Releases 页面
2. 点击 "Draft a new release"
3. 选择刚创建的标签
4. 填写 Release Notes
5. 上传构建产物（如果 CI 未自动创建）
6. 点击 "Publish release"

步骤 5: 验证发布

下载并测试：

• Windows 安装程序
• Linux AppImage
• macOS DMG（如果可访问）

故障排除

Rust 相关问题

错误: cargo: command not found

解决:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Linux 依赖问题

错误: fatal error: gtk/gtk.h: No such file or directory

解决:

sudo apt-get install libgtk-3-dev libwebkit2gtk-4.0-dev

构建失败

清理缓存：

npm run clean
cargo clean
rm -rf node_modules
npm install

图标未显示

确保所有图标文件存在：

ls -la src-tauri/icons/

应该包含：

• 32x32.png
• 128x128.png
• 128x128@2x.png
• icon.ico
• icon.icns

Windows SmartScreen 警告

Windows 可能会显示 SmartScreen 警告，因为应用未经签名。

临时解决:

1. 点击 "更多信息"
2. 点击 "仍要运行"

永久解决: 使用代码签名证书对应用进行签名。

数字签名

Windows 代码签名

需要购买代码签名证书（如 DigiCert, Sectigo）。

签名命令：

signtool sign /f certificate.pfx /p password /t timestamp_url cutthink-lite-setup.exe

macOS 代码签名

需要 Apple Developer 账户。

签名命令：

codesign --deep --force --verify --verbose \
  --sign "Developer ID Application: Your Name" \
  CutThenThink\ Lite.app

性能优化

减小包体积

1. 启用压缩：

   npm run build:analyze
   

2. 删除未使用的依赖：

   npx depcheck
   

3. 使用 Tauri 的 upx 压缩： 编辑 src-tauri/Cargo.toml：

   [profile.release]
   strip = true
   lto = true
   codegen-units = 1
   opt-level = "z"
   

调试

启用详细日志

RUST_LOG=debug npm run tauri:dev

查看构建日志

npm run tauri build -- --verbose

参考资源

• Tauri 官方文档
• Rust 学习资源
• GitHub Actions 文档

许可证

MIT License - 详见 LICENSE