# 开发指南 本文档介绍 Flash Send 的开发环境搭建、开发流程和构建部署。 ## 环境要求 ### 系统要求 | 平台 | 最低版本 | |------|----------| | Windows | Windows 10 | | macOS | 10.15+ | | Linux | Ubuntu 18.04+ | ### 开发工具 | 工具 | 版本要求 | 用途 | |------|----------|------| | Node.js | >= 18.0 | 前端构建 | | Rust | >= 1.70 | 后端开发 | | pnpm/npm/yarn | 最新版 | 包管理 | ### 推荐 IDE - **VS Code** + 插件： - Vue - Official - rust-analyzer - Tailwind CSS IntelliSense - Tauri - **RustRover** / **WebStorm** --- ## 环境搭建 ### 1. 克隆项目 ```bash git clone https://github.com/your-repo/flash-send.git cd flash-send ``` ### 2. 安装 Node.js 依赖 ```bash npm install # 或 pnpm install # 或 yarn install ``` ### 3. 安装 Rust ```bash # Windows (使用 rustup-init.exe) # https://rustup.rs/ # macOS / Linux curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # 验证安装 rustc --version cargo --version ``` ### 4. 安装 Tauri CLI ```bash npm install -g @tauri-apps/cli # 或 cargo install tauri-cli ``` ### 5. 系统依赖 (Linux) ```bash # Ubuntu/Debian sudo apt update sudo apt install libwebkit2gtk-4.0-dev \ build-essential \ curl \ wget \ file \ libssl-dev \ libgtk-3-dev \ libayatana-appindicator3-dev \ librsvg2-dev ``` --- ## 开发命令 ### 启动开发服务器 ```bash npm run tauri dev ``` 这会同时启动： - Vite 开发服务器（前端热重载） - Tauri 开发窗口（后端实时编译） ### 仅启动前端 ```bash npm run dev ``` ### 类型检查 ```bash # 前端 TypeScript npm run build # 包含 vue-tsc --noEmit # 后端 Rust cd src-tauri cargo check ``` ### 代码格式化 ```bash # 前端 npx prettier --write src/ # 后端 cd src-tauri cargo fmt ``` ### 代码检查 ```bash # 后端 cd src-tauri cargo clippy ``` --- ## 项目结构说明 ``` flash-send/ ├── src/ # Vue 前端源码 │ ├── api/ # Tauri API 封装 │ ├── components/ # Vue 组件 │ ├── pages/ # 页面组件 │ ├── stores/ # Pinia 状态 │ ├── hooks/ # 组合式函数 │ ├── types/ # TypeScript 类型 │ ├── router/ # Vue Router │ ├── styles/ # 全局样式 │ ├── App.vue # 根组件 │ └── main.ts # 入口文件 │ ├── src-tauri/ # Rust 后端源码 │ ├── src/ │ │ ├── commands/ # Tauri 命令 │ │ ├── discovery/ # 设备发现 │ │ ├── websocket/ # WebSocket │ │ ├── http/ # HTTP 传输 │ │ ├── tls/ # TLS 加密 │ │ ├── database/ # SQLite │ │ ├── models/ # 数据模型 │ │ ├── utils/ # 工具函数 │ │ ├── state.rs # 全局状态 │ │ ├── main.rs # 程序入口 │ │ └── lib.rs # 库入口 │ ├── Cargo.toml # Rust 依赖 │ └── tauri.conf.json # Tauri 配置 │ ├── document/ # 项目文档 ├── public/ # 静态资源 ├── index.html # HTML 入口 ├── package.json # Node 依赖 ├── vite.config.ts # Vite 配置 ├── tailwind.config.js # Tailwind 配置 └── tsconfig.json # TypeScript 配置 ``` --- ## 开发流程 ### 1. 新增 Tauri 命令 **步骤 a**: 在 `src-tauri/src/commands/` 创建或编辑命令文件 ```rust // src-tauri/src/commands/my_commands.rs #[tauri::command] pub async fn my_command(param: String) -> CommandResult { // 实现逻辑 Ok(format!("Hello, {}!", param)) } ``` **步骤 b**: 在 `mod.rs` 注册命令 ```rust // src-tauri/src/commands/mod.rs pub fn get_handlers() -> impl Fn(tauri::Builder) -> tauri::Builder { |builder| { builder.invoke_handler(tauri::generate_handler![ // ... 其他命令 my_command, ]) } } ``` **步骤 c**: 在前端调用 ```typescript // src/api/index.ts export const myApi = { myCommand: (param: string) => invoke('my_command', { param }), } ``` ### 2. 新增前端页面 **步骤 a**: 创建页面组件 ```vue ``` **步骤 b**: 添加路由 ```typescript // src/router/index.ts { path: '/my-page', name: 'myPage', component: () => import('../pages/MyPage.vue') } ``` ### 3. 新增后端事件 **步骤 a**: 定义事件 ```rust // src-tauri/src/models/events.rs pub mod event_names { pub const MY_EVENT: &str = "my:event"; } ``` **步骤 b**: 发送事件 ```rust use tauri::Emitter; app.emit("my:event", payload)?; ``` **步骤 c**: 前端监听 ```typescript import { listen } from '@tauri-apps/api/event' const unlisten = await listen('my:event', (event) => { console.log(event.payload) }) ``` --- ## 调试技巧 ### 前端调试 1. **Chrome DevTools**: `Ctrl+Shift+I` 或 `F12` 2. **Vue DevTools**: 安装浏览器扩展 3. **Console 日志**: 使用 `console.log()` ### 后端调试 1. **日志输出**: ```rust log::info!("Debug message: {:?}", value); log::error!("Error: {}", err); ``` 2. **环境变量**: ```bash RUST_LOG=debug npm run tauri dev ``` 3. **查看后端日志**: 在终端中查看 Tauri 输出 ### 网络调试 1. **WebSocket**: 使用浏览器 DevTools Network 面板 2. **HTTP**: 使用 Postman 或 curl 测试 3. **UDP**: 使用 Wireshark 抓包 --- ## 构建发布 ### 构建生产版本 ```bash npm run tauri build ``` **输出目录**: `src-tauri/target/release/bundle/` ### 构建产物 | 平台 | 格式 | |------|------| | Windows | `.msi`, `.exe` (NSIS) | | macOS | `.dmg`, `.app` | | Linux | `.deb`, `.AppImage` | ### 配置构建 编辑 `src-tauri/tauri.conf.json`: ```json { "productName": "Flash Send", "version": "1.0.0", "identifier": "com.flashsend.app", "bundle": { "active": true, "targets": "all", "icon": ["icons/icon.ico", "icons/icon.png"], "windows": { "certificateThumbprint": null, "digestAlgorithm": "sha256", "timestampUrl": "" } } } ``` ### 代码签名 #### Windows ```json { "bundle": { "windows": { "certificateThumbprint": "YOUR_CERT_THUMBPRINT", "digestAlgorithm": "sha256", "timestampUrl": "http://timestamp.digicert.com" } } } ``` #### macOS ```bash export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name (XXXXXXXXXX)" npm run tauri build ``` --- ## 测试 ### 单元测试 (Rust) ```bash cd src-tauri cargo test ``` ### 集成测试 1. 启动两个实例（不同机器或虚拟机） 2. 测试设备发现 3. 测试聊天功能 4. 测试文件传输 ### 测试清单 - [ ] 设备发现正常 - [ ] WebSocket 连接稳定 - [ ] 消息收发正常 - [ ] 文件传输完整 - [ ] 取消传输有效 - [ ] 深色模式正常 - [ ] 数据库持久化 - [ ] 重启后数据恢复 --- ## 常见问题 ### Q: 编译时出现 OpenSSL 错误 **A**: 安装 OpenSSL 开发库 ```bash # Ubuntu sudo apt install libssl-dev # macOS brew install openssl ``` ### Q: Windows 上编译失败 **A**: 安装 Visual Studio Build Tools 下载地址: https://visualstudio.microsoft.com/visual-cpp-build-tools/ ### Q: 设备无法发现 **A**: 检查防火墙设置，确保 UDP 53317 端口开放 ### Q: WebSocket 连接失败 **A**: 检查防火墙设置，确保 TCP 53318 端口开放 ### Q: 文件传输失败 **A**: 1. 检查防火墙设置，确保 TCP 53319 端口开放 2. 检查磁盘空间是否充足 3. 检查下载目录权限 --- ## 贡献指南 ### 提交规范 使用 Conventional Commits: ``` feat: 添加新功能 fix: 修复 bug docs: 更新文档 style: 代码格式调整 refactor: 代码重构 test: 添加测试 chore: 构建/工具变更 ``` ### 分支策略 - `main`: 稳定版本 - `develop`: 开发分支 - `feature/*`: 功能分支 - `fix/*`: 修复分支 ### PR 流程 1. Fork 项目 2. 创建功能分支 3. 提交变更 4. 创建 Pull Request 5. 代码审查 6. 合并到 develop --- ## 参考资源 - [Tauri 官方文档](https://tauri.app/v2/guides/) - [Vue 3 文档](https://vuejs.org/) - [Rust 官方文档](https://doc.rust-lang.org/) - [TailwindCSS 文档](https://tailwindcss.com/docs) - [Pinia 文档](https://pinia.vuejs.org/)