You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

8.6 KiB

Raw Blame History

开发指南

本文档介绍 Flash Send 的开发环境搭建、开发流程和构建部署。

环境要求

系统要求

平台	最低版本
Windows	Windows 10
macOS	10.15+
Linux	Ubuntu 18.04+

开发工具

工具	版本要求	用途
Node.js	>= 18.0	前端构建
Rust	>= 1.70	后端开发
pnpm/npm/yarn	最新版	包管理

环境搭建

1. 克隆项目

git clone https://github.com/your-repo/flash-send.git
cd flash-send

2. 安装 Node.js 依赖

npm install
# 或
pnpm install
# 或
yarn install

3. 安装 Rust

# 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

npm install -g @tauri-apps/cli
# 或
cargo install tauri-cli

5. 系统依赖 (Linux)

# 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

开发命令

启动开发服务器

npm run tauri dev

这会同时启动：

Vite 开发服务器（前端热重载）
Tauri 开发窗口（后端实时编译）

仅启动前端

npm run dev

类型检查

# 前端 TypeScript
npm run build  # 包含 vue-tsc --noEmit

# 后端 Rust
cd src-tauri
cargo check

代码格式化

# 前端
npx prettier --write src/

# 后端
cd src-tauri
cargo fmt

代码检查

# 后端
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/ 创建或编辑命令文件

// src-tauri/src/commands/my_commands.rs
#[tauri::command]
pub async fn my_command(param: String) -> CommandResult<String> {
    // 实现逻辑
    Ok(format!("Hello, {}!", param))
}

步骤 b: 在 mod.rs 注册命令

// src-tauri/src/commands/mod.rs
pub fn get_handlers() -> impl Fn(tauri::Builder<Wry>) -> tauri::Builder<Wry> {
    |builder| {
        builder.invoke_handler(tauri::generate_handler![
            // ... 其他命令
            my_command,
        ])
    }
}

步骤 c: 在前端调用

// src/api/index.ts
export const myApi = {
  myCommand: (param: string) => invoke<string>('my_command', { param }),
}

2. 新增前端页面

步骤 a: 创建页面组件

<!-- src/pages/MyPage.vue -->
<script setup lang="ts">
import { ref, onMounted } from 'vue'

const data = ref('')

onMounted(async () => {
  // 初始化
})
</script>

<template>
  <div class="p-4">
    <h1>My Page</h1>
  </div>
</template>

步骤 b: 添加路由

// src/router/index.ts
{
  path: '/my-page',
  name: 'myPage',
  component: () => import('../pages/MyPage.vue')
}

3. 新增后端事件

步骤 a: 定义事件

// src-tauri/src/models/events.rs
pub mod event_names {
    pub const MY_EVENT: &str = "my:event";
}

步骤 b: 发送事件

use tauri::Emitter;

app.emit("my:event", payload)?;

步骤 c: 前端监听

import { listen } from '@tauri-apps/api/event'

const unlisten = await listen('my:event', (event) => {
  console.log(event.payload)
})

调试技巧

前端调试

Chrome DevTools: Ctrl+Shift+I 或 F12
Vue DevTools: 安装浏览器扩展
Console 日志: 使用 console.log()

后端调试

日志输出:

log::info!("Debug message: {:?}", value);
log::error!("Error: {}", err);

环境变量:

RUST_LOG=debug npm run tauri dev

查看后端日志: 在终端中查看 Tauri 输出

网络调试

WebSocket: 使用浏览器 DevTools Network 面板
HTTP: 使用 Postman 或 curl 测试
UDP: 使用 Wireshark 抓包

构建发布

构建生产版本

npm run tauri build

输出目录: src-tauri/target/release/bundle/

构建产物

平台	格式
Windows	`.msi`, `.exe` (NSIS)
macOS	`.dmg`, `.app`
Linux	`.deb`, `.AppImage`

配置构建

编辑 src-tauri/tauri.conf.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

{
  "bundle": {
    "windows": {
      "certificateThumbprint": "YOUR_CERT_THUMBPRINT",
      "digestAlgorithm": "sha256",
      "timestampUrl": "http://timestamp.digicert.com"
    }
  }
}

macOS

export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name (XXXXXXXXXX)"
npm run tauri build

测试

单元测试 (Rust)

cd src-tauri
cargo test

集成测试

启动两个实例（不同机器或虚拟机）
测试设备发现
测试聊天功能
测试文件传输

测试清单

设备发现正常
WebSocket 连接稳定
消息收发正常
文件传输完整
取消传输有效
深色模式正常
数据库持久化
重启后数据恢复

常见问题

Q: 编译时出现 OpenSSL 错误

A: 安装 OpenSSL 开发库

# 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: 文件传输失败

检查防火墙设置，确保 TCP 53319 端口开放
检查磁盘空间是否充足
检查下载目录权限

贡献指南

提交规范

使用 Conventional Commits:

feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建/工具变更

分支策略

main: 稳定版本
develop: 开发分支
feature/*: 功能分支
fix/*: 修复分支

PR 流程

Fork 项目
创建功能分支
提交变更
创建 Pull Request
代码审查
合并到 develop

8.6 KiB Raw Blame History