HuLa 项目入门手册 🚀

基于 Tauri、Vite 7、Vue 3 和 TypeScript 构建的跨平台即时通讯系统完整开发指南

📋 目录

环境要求
环境配置与安装
项目启动
项目目录结构
服务地址配置
如何提交 Issues 和 PR

🔧 环境要求

在开始开发之前，请确保您的系统满足以下要求：

必需环境

环境	版本要求	说明
Node.js	`^20.19.0` 或 `>=22.12.0`	JavaScript 运行环境
pnpm	`>=10.x`	包管理器，必须使用 pnpm
Rust	`最新稳定版`	Tauri 后端开发需要
Git	`2.0+`	版本控制

操作系统支持

平台	支持版本
Windows	Windows 10, Windows 11
macOS	macOS 10.15+
Linux	Ubuntu 20.04+
iOS/iPadOS	iOS 13.0+, iPadOS 13.0+
Android	Android 8.0+ (API 26+)

⚙️ 环境配置与安装

1. 安装 Node.js 和 pnpm

Windows:

# 方法1: 使用 winget 安装 Node.js
winget install OpenJS.NodeJS

# 方法2: 从官网下载安装包
# 访问 https://nodejs.org/ 下载 LTS 版本

# 安装 pnpm
npm install -g pnpm@latest

macOS:

# 使用 Homebrew 安装
brew install node pnpm

# 或使用 nvm 管理 Node.js 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22
npm install -g pnpm@latest

Linux (Ubuntu/Debian):

# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 pnpm
npm install -g pnpm@latest

2. 安装 Rust 和 Tauri 环境

所有平台:

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 验证安装
rustc --version
cargo --version

Windows 额外要求:

详细安装步骤：

安装 Microsoft C++ Build Tools

# 方法1: 使用 winget 安装
winget install Microsoft.VisualStudio.2022.BuildTools

# 方法2: 下载安装包
# 访问 https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022

或者安装 Visual Studio Community 2022

# 使用 winget 安装
winget install Microsoft.VisualStudio.2022.Community

# 必须勾选以下工作负载：
# - 使用 C++ 的桌面开发
# - MSVC v143 编译器工具集
# - Windows 10/11 SDK (最新版本)

安装 WebView2 Runtime (通常已预装)

# 检查是否已安装 WebView2
winget list --name "Microsoft Edge WebView2"

# 如未安装，执行：
winget install Microsoft.EdgeWebView2Runtime

重启命令行工具 安装完成后，重新打开 PowerShell 或 CMD 以确保环境变量生效。

Linux 额外要求:

# Ubuntu/Debian
sudo apt update
sudo apt install libwebkit2gtk-4.0-dev \
    build-essential \
    curl \
    wget \
    libssl-dev \
    libgtk-3-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev

# Fedora
sudo dnf install webkit2gtk3-devel.x86_64 \
    openssl-devel \
    curl \
    wget \
    libappindicator-gtk3 \
    librsvg2-devel

# Arch
sudo pacman -S webkit2gtk \
    base-devel \
    curl \
    wget \
    openssl \
    appmenu-gtk-module \
    gtk3 \
    libappindicator-gtk3 \
    librsvg \
    libvips

3. 移动端开发环境 (可选)

Android 开发:

# 安装 Android Studio 和 SDK
# 设置 ANDROID_HOME 环境变量

# 初始化 Android 项目
pnpm run tauri:android:init

iOS 开发 (仅 macOS):

# 安装 Xcode 和 Xcode Command Line Tools
xcode-select --install

# 初始化 iOS 项目
pnpm run tauri:ios:init

🚀 项目启动

1. 克隆项目

# 从 GitHub 克隆
git clone https://github.com/HuLaSpark/HuLa.git

# 或从 Gitee 克隆（国内推荐）
git clone https://gitee.com/HuLaSpark/HuLa.git

# 进入项目目录
cd HuLa

2. 安装依赖

# 使用 pnpm 安装所有依赖
pnpm install

# 如果在国内网络环境下遇到问题，可以设置镜像
pnpm config set registry https://registry.npmmirror.com/

3. 启动开发环境

# 启动桌面应用开发环境（推荐）
pnpm run tauri:dev
# 简化命令
pnpm run td

# 启动 Android 开发环境
pnpm run tauri:android:dev
# 简化命令
pnpm run adev

# 启动 iOS 开发环境（仅 macOS）
pnpm run tauri:ios:dev
# 简化命令
pnpm run idev

4. 构建生产版本

# 构建桌面应用
pnpm run tauri:build
# 简化命令
pnpm run tb

5. 代码质量检查

# 检查代码格式和问题（不修复）
pnpm run check

# 修复代码格式和问题
pnpm run check:write

# 格式化所有文件（包括 Vue 组件）
pnpm run format:all

# Git 提交前的代码检查
pnpm run lint:staged

6. 测试

# 运行单元测试
pnpm run test:run

# 运行测试 UI 界面
pnpm run test:ui

# 生成测试覆盖率报告
pnpm run coverage

📁 项目目录结构

HuLa/
├── 📁 src/                      # Vue 3 前端源码
│   ├── 📁 agreement/            # 用户协议相关组件
│   ├── 📁 assets/               # 静态资源
│   │   ├── 📁 fonts/            # 字体文件
│   │   ├── 📁 img/              # 图片资源
│   │   ├── 📁 logo/             # Logo 资源
│   │   ├── 📁 mobile/           # 移动端专用资源
│   │   └── 📁 video/            # 视频资源
│   ├── 📁 components/           # Vue 组件
│   │   ├── 📁 common/           # 公共组件
│   │   ├── 📁 rightBox/         # 右侧功能组件
│   │   └── 📁 windows/          # 窗口组件
│   ├── 📁 directives/           # Vue 自定义指令
│   ├── 📁 enums/               # 枚举定义
│   ├── 📁 hooks/               # Vue 3 组合式 API Hooks
│   ├── 📁 layout/              # 布局组件
│   │   ├── 📁 center/          # 中央布局
│   │   └── 📁 left/            # 左侧布局
│   ├── 📁 mobile/              # 移动端专用代码
│   ├── 📁 plugins/             # 插件配置
│   ├── 📁 router/              # Vue Router 路由配置
│   ├── 📁 services/            # API 服务层
│   ├── 📁 stores/              # Pinia 状态管理
│   ├── 📁 styles/              # 全局样式
│   ├── 📁 typings/             # TypeScript 类型定义
│   ├── 📁 utils/               # 工具函数
│   ├── 📁 views/               # 页面组件
│   ├── 📁 workers/             # Web Workers
│   ├── 📄 App.vue              # 根组件
│   └── 📄 main.ts              # 应用入口文件
├── 📁 src-tauri/               # Tauri Rust 后端源码
│   ├── 📁 capabilities/         # Tauri 权限配置
│   ├── 📁 configuration/        # 应用配置
│   ├── 📁 entity/              # 数据库实体
│   ├── 📁 icons/               # 应用图标
│   ├── 📁 migration/           # 数据库迁移
│   ├── 📁 src/                 # Rust 源码
│   ├── 📁 tray/                # 系统托盘相关
│   ├── 📄 Cargo.toml           # Rust 项目配置
│   ├── 📄 tauri.conf.json      # Tauri 主配置
│   ├── 📄 tauri.*.conf.json    # 平台特定配置
│   └── 📄 db.sqlite            # SQLite 数据库
├── 📁 public/                  # 静态资源文件
│   ├── 📁 AI/                  # AI 相关资源
│   ├── 📁 avatar/              # 头像资源
│   ├── 📁 emoji/               # 表情包资源
│   ├── 📁 sound/               # 音频文件
│   └── 📄 logo.png             # 应用 Logo
├── 📁 scripts/                 # 构建和开发脚本
│   ├── 📄 check-all.js         # 环境检查脚本
│   ├── 📄 check-dependencies.js # 依赖检查脚本
│   └── 📄 interactive-build-inquirer.js # 交互式构建脚本
├── 📁 docs/                    # 项目文档
├── 📁 preview/                 # 项目预览图
├── 📁 build/                   # 构建输出目录
├── 📁 .husky/                  # Git hooks 配置
├── 📁 .vscode/                 # VS Code 配置
├── 📄 package.json             # 项目依赖和脚本配置
├── 📄 pnpm-lock.yaml           # 依赖版本锁定文件
├── 📄 tsconfig.json            # TypeScript 配置
├── 📄 vite.config.ts           # Vite 构建配置
├── 📄 uno.config.ts            # UnoCSS 配置
├── 📄 biome.json               # 代码格式化配置
├── 📄 vitest.config.ts         # 测试配置
└── 📄 README.md                # 项目说明文档

核心目录说明

目录	作用	技术栈
`src/`	Vue 3 前端应用源码	Vue 3 + TypeScript + Vite
`src-tauri/`	Tauri Rust 后端源码	Rust + Tauri + SQLite
`src/components/`	可复用 Vue 组件	Vue 3 Composition API
`src/stores/`	状态管理	Pinia + TypeScript
`src/services/`	API 接口服务	Axios + TypeScript
`src/hooks/`	自定义 Hooks	Vue 3 Composition API
`src/utils/`	工具函数库	TypeScript + Lodash
`src/styles/`	全局样式	Sass + UnoCSS
`public/`	静态资源文件	图片、音频、字体等

🐛 如何提交 Issues 和 PR

提交 Issue

🔍 搜索现有 Issues
- 在提交新 Issue 前，请先搜索是否已有类似问题
- 访问 GitHub Issues

📝 创建新 Issue

**问题描述**
清晰描述您遇到的问题

**复现步骤**
1. 进入...
2. 点击...
3. 出现错误...

**期望行为**
描述您期望发生的情况

**环境信息**
- 操作系统: [例如 Windows 11]
- Node.js 版本: [例如 v22.12.0]
- HuLa 版本: [例如 v2.6.13]

**截图或日志**
如有可能，请提供相关截图或错误日志

提交 Pull Request

🍴 Fork 项目

# 点击 GitHub 页面右上角的 "Fork" 按钮
# 然后克隆您的 Fork
git clone https://github.com/你的用户名/HuLa.git
cd HuLa

🌿 创建功能分支

# 创建并切换到新分支
git checkout -b feature/your-feature-name

# 或修复分支
git checkout -b fix/your-bug-fix

💻 开发和测试

# 安装依赖
pnpm i

# 启动开发环境
pnpm run td

# 运行代码检查
pnpm run lint:staged

# 运行测试
pnpm run test:run

📝 提交代码

# 使用项目提供的提交工具（推荐）
pnpm run commit

# 或传统方式提交
git add .
git commit -m "feat: 添加新功能描述"

🚀 推送和创建 PR

# 推送到您的 Fork
git push origin feature/your-feature-name

# 在 GitHub 上创建 Pull Request

代码提交规范

项目使用 Conventional Commits 规范：

类型	说明	示例
`feat`	新功能	`feat: 添加消息撤回功能`
`fix`	修复 Bug	`fix: 修复登录页面样式问题`
`docs`	文档更新	`docs: 更新 API 文档`
`style`	代码格式化	`style: 格式化组件代码`
`refactor`	重构代码	`refactor: 优化消息发送逻辑`
`perf`	性能优化	`perf: 优化图片加载性能`
`test`	添加测试	`test: 添加登录功能单元测试`
`chore`	构建过程或辅助工具变动	`chore: 更新依赖版本`

代码审查流程

自动检查: PR 提交后会自动运行 CI 检查
代码审查: 维护者会审查您的代码
修改完善: 根据反馈修改代码
合并入库: 审查通过后合并到主分支

🔧 服务地址配置

简化配置说明

HuLa 项目现在使用统一配置方案，您只需要修改一个文件即可完成服务地址配置：

配置文件： src-tauri/configuration/local.yaml

配置步骤

1. 创建本地配置文件

首次启动项目时，运行以下脚本自动创建 local.yaml 配置文件：

# 运行pnpm i 会自动创建 local.yaml 文件（使用 production.yaml 作为模板）
pnpm i

2. 修改服务地址

编辑 src-tauri/configuration/local.yaml 文件，修改以下配置：

# 数据库配置
database:
  sqlite_file: db.sqlite

# 后端服务配置
backend:
  base_url: http://localhost:8080/api      # 修改为您的后端 API 地址
  ws_url: ws://localhost:8080/api/ws/ws    # 修改为您的 WebSocket 地址

# 翻译服务配置（可选）
youdao:
  app_key: ''
  app_secret: ''
tencent:
  api_key: ''
  secret_id: ''

3. 配置示例

本地开发环境：

backend:
  base_url: http://localhost:8080/api
  ws_url: ws://localhost:8080/api/ws/ws

局域网环境：

backend:


### 注意事项

- ✅ **自动同步**：前后端会自动使用 `local.yaml` 中的配置，无需手动同步
- 🔄 **重启生效**：修改配置后需要重启开发服务器 (`pnpm run td`)
- 🌐 **协议选择**：
  - 本地/HTTP：使用 `http://` 和 `ws://`
  - 生产/HTTPS：使用 `https://` 和 `wss://`
- 📁 **文件管理**：`local.yaml` 文件不会提交到 Git，仅用于本地开发

### 验证配置

修改配置后，重启开发服务器验证：

```bash
# 重启开发服务器
pnpm run td


---

## 🎯 开发建议

### 编辑器配置

推荐使用 **Visual Studio Code** 并安装以下插件：

```json
{
  "recommendations": [
    "vue.volar",
    "bradlc.vscode-tailwindcss",
    "rust-lang.rust-analyzer",
    "tauri-apps.tauri-vscode",
    "ms-vscode.vscode-typescript-next",
    "biomejs.biome"
  ]
}

开发工作流

🔄 保持同步: 定期从上游仓库拉取最新代码
🧪 测试驱动: 为新功能编写测试用例
📚 文档更新: 及时更新相关文档
🎨 代码风格: 使用项目统一的代码风格
🐛 问题跟踪: 及时反馈和修复发现的问题

🤝 社区交流

💬 微信群: 扫描 README 中的二维码加入讨论群
🌟 GitHub: https://github.com/HuLaSpark/HuLa
🦄 Gitee: https://gitee.com/HulaSpark/HuLa
📧 邮箱: 2439646234@qq.com
🌐 官网: https://hulaspark.com

🎉 开始您的 HuLa 开发之旅

现在您已经掌握了 HuLa 项目的完整开发指南！快来加入我们，一起构建更好的即时通讯体验吧！

如果在开发过程中遇到任何问题，请不要犹豫地：

📖 查阅此文档
🔍 搜索现有 Issues
💬 在社区群中提问
🐛 创建新的 Issue

祝您开发愉快！ 🚀✨

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HuLa 项目入门手册 🚀

📋 目录

🔧 环境要求

必需环境

操作系统支持

⚙️ 环境配置与安装

1. 安装 Node.js 和 pnpm

2. 安装 Rust 和 Tauri 环境

3. 移动端开发环境 (可选)

🚀 项目启动

1. 克隆项目

2. 安装依赖

3. 启动开发环境

4. 构建生产版本

5. 代码质量检查

6. 测试

📁 项目目录结构

核心目录说明

🐛 如何提交 Issues 和 PR

提交 Issue

提交 Pull Request

代码提交规范

代码审查流程

🔧 服务地址配置

简化配置说明

配置步骤

1. 创建本地配置文件

2. 修改服务地址

3. 配置示例

开发工作流

🤝 社区交流

🎉 开始您的 HuLa 开发之旅

FilesExpand file tree

project_guide.md

Latest commit

History

project_guide.md

File metadata and controls

HuLa 项目入门手册 🚀

📋 目录

🔧 环境要求

必需环境

操作系统支持

⚙️ 环境配置与安装

1. 安装 Node.js 和 pnpm

2. 安装 Rust 和 Tauri 环境

3. 移动端开发环境 (可选)

🚀 项目启动

1. 克隆项目

2. 安装依赖

3. 启动开发环境

4. 构建生产版本

5. 代码质量检查

6. 测试

📁 项目目录结构

核心目录说明

🐛 如何提交 Issues 和 PR

提交 Issue

提交 Pull Request

代码提交规范

代码审查流程

🔧 服务地址配置

简化配置说明

配置步骤

1. 创建本地配置文件

2. 修改服务地址

3. 配置示例

开发工作流

🤝 社区交流

🎉 开始您的 HuLa 开发之旅