cutThink_lite/docs/BUILD-GUIDE.md

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

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

## 目录
- [系统要求](#系统要求)
- [本地开发](#本地开发)
- [多平台构建](#多平台构建)
- [CI/CD 流程](#cicd-流程)
- [发布流程](#发布流程)
- [故障排除](#故障排除)

## 系统要求

### 基础工具
- **Node.js**: 18.0 或更高版本
- **npm**: 9.0 或更高版本
- **Rust**: 1.70 或更高版本（通过 rustup 安装）

### 平台特定要求

#### Linux (Ubuntu/Debian)
```bash
sudo apt-get update
sudo apt-get install -y \
    libgtk-3-dev \
    libwebkit2gtk-4.0-dev \
    libappindicator3-dev \
    librsvg2-dev \
    patchelf
```

#### macOS
```bash
xcode-select --install
```

#### Windows
下载并安装 [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
安装 "Desktop development with C++" 工作负载

## 本地开发

### 1. 环境检查

运行环境检查脚本：
```bash
./scripts/check-build.sh
```

### 2. 安装依赖

```bash
npm install
```

### 3. 开发模式

启动开发服务器（热重载）：
```bash
npm run tauri:dev
```

### 4. 构建前端

仅构建前端（不打包桌面应用）：
```bash
npm run build
```

## 多平台构建

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

**完整构建**：
```bash
./scripts/build.sh
```

**开发构建**：
```bash
./scripts/dev.sh
```

**仅打包前端**：
```bash
./scripts/package-frontend.sh
```

### 方法 2: 直接使用 npm 命令

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

### 方法 3: 使用 Docker（Linux）

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

```bash
./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 标签**（推荐）：
```bash
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)

## 发布流程

### 发布前检查清单

使用发布检查清单：
```bash
cat docs/RELEASE-CHECKLIST.md
```

### 步骤 1: 准备发布

1. **更新版本号**：
   - `package.json` 中的 `version`
   - `src-tauri/tauri.conf.json` 中的 `version`
   - `src-tauri/Cargo.toml` 中的 `version`

2. **更新 CHANGELOG**：
   ```bash
   # 编辑 CHANGELOG.md
   # 添加新版本的变化内容
   ```

3. **提交更改**：
   ```bash
   git add .
   git commit -m "Release v0.1.0"
   ```

### 步骤 2: 创建标签

```bash
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`

**解决**:
```bash
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`

**解决**:
```bash
sudo apt-get install libgtk-3-dev libwebkit2gtk-4.0-dev
```

### 构建失败

**清理缓存**：
```bash
npm run clean
cargo clean
rm -rf node_modules
npm install
```

### 图标未显示

确保所有图标文件存在：
```bash
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）。

签名命令：
```bash
signtool sign /f certificate.pfx /p password /t timestamp_url cutthink-lite-setup.exe
```

### macOS 代码签名

需要 Apple Developer 账户。

签名命令：
```bash
codesign --deep --force --verify --verbose \
  --sign "Developer ID Application: Your Name" \
  CutThenThink\ Lite.app
```

## 性能优化

### 减小包体积

1. **启用压缩**：
   ```bash
   npm run build:analyze
   ```

2. **删除未使用的依赖**：
   ```bash
   npx depcheck
   ```

3. **使用 Tauri 的 upx 压缩**：
   编辑 `src-tauri/Cargo.toml`：
   ```toml
   [profile.release]
   strip = true
   lto = true
   codegen-units = 1
   opt-level = "z"
   ```

## 调试

### 启用详细日志

```bash
RUST_LOG=debug npm run tauri:dev
```

### 查看构建日志

```bash
npm run tauri build -- --verbose
```

## 参考资源

- [Tauri 官方文档](https://tauri.app/v1/guides/)
- [Rust 学习资源](https://www.rust-lang.org/learn)
- [GitHub Actions 文档](https://docs.github.com/en/actions)

## 许可证

MIT License - 详见 [LICENSE](../LICENSE)