feat: CutThenThink v3.0 初始版本
完整实现 Tauri + Vanilla JS 轻量级截图工具 Phase 1 - 项目搭建 - Tauri 2.x 项目初始化 - Vite 前端项目搭建 - 基础 UI 框架（CSS 变量、组件库） - 构建配置优化 Phase 2 - 核心截图功能 - 全屏/区域/窗口截图 - 截图预览和管理 - 文件命名和缩略图 - 全局快捷键集成 Phase 3 - 上传与存储 - 多图床上传（GitHub/Imgur/自定义） - 配置管理系统 - SQLite 数据库 Phase 4 - OCR 集成 - 云端 OCR（百度/腾讯云） - 插件管理系统 - 本地 OCR 插件（Go） - OCR 结果处理 Phase 5 - AI 分类系统 - Claude/OpenAI API 集成 - Prompt 模板引擎 - 模板管理界面 - 自动分类流程 Phase 6 - 历史记录与管理 - 图库视图（网格/列表） - 搜索与筛选 - 批量操作 - 导出功能（JSON/CSV/ZIP） Phase 7 - 打包与发布 - 多平台构建配置 - CI/CD 工作流 - 图标和资源 - 安装包配置 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Claude
346
docs/BUILD-GUIDE.md
Normal file
346
docs/BUILD-GUIDE.md
Normal file
@@ -0,0 +1,346 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user