# VoiceLink

**Repository Path**: yimu321/voice-link

## Basic Information

- **Project Name**: VoiceLink
- **Description**: 一个基于 Electron + TypeScript + React 开发的 Windows 桌面语音连麦应用，支持用户注册登录、创建/加入语音房间、低延迟语音通信和两种说话模式。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: JavaScript, React, TypeScript, HTML, Electron

## README

# 语音连麦 - Windows 桌面应用

一个基于 Electron + TypeScript + React 开发的 Windows 桌面语音连麦应用，支持用户注册登录、创建/加入语音房间、低延迟语音通信和两种说话模式。

## 核心功能

### 🎯 主要功能
- **用户认证**：邮箱+密码注册登录，JWT 认证
- **语音房间**：创建/加入语音房间，每个房间有唯一 ID
- **低延迟语音**：基于 WebRTC 的点对点语音通信，目标延迟 <500ms
- **两种说话模式**：
  - 自由说话（麦克风持续采集）
  - 按键说话（PTT）：按下全局快捷键 Ctrl+T 开启麦克风
- **实时用户列表**：房间内实时显示在线用户和连接状态

### 🎨 界面特点
- **中文界面**：完全本地化的中文用户界面
- **Windows 风格**：符合 Windows 桌面应用的设计风格
- **响应式布局**：适配不同屏幕尺寸

## 技术栈

### 前端
- **框架**：Electron 40.6.0 + TypeScript 5.9.3 + React 19.2.0
- **构建工具**：Vite 7.3.1
- **样式**：CSS3
- **实时通信**：WebRTC + WebSocket

### 后端
- **服务器**：Node.js + Express
- **数据库**：PostgreSQL + Prisma ORM
- **认证**：JWT + bcrypt
- **实时通信**：WebSocket

## 系统要求

- **操作系统**：Windows 10/11
- **内存**：至少 4GB RAM
- **处理器**：Intel i3 或同等性能处理器
- **网络**：稳定的网络连接
- **麦克风**：内置或外置麦克风

## 安装和运行

### 方法一：使用便携版（推荐）
1. 下载 `build_dist/语音连麦 0.0.0.exe` 文件
2. 直接双击运行，无需安装

### 方法二：使用安装版
1. 下载 `build_dist/语音连麦 Setup 0.0.0.exe` 文件
2. 双击运行安装向导
3. 按照提示完成安装
4. 从开始菜单或桌面快捷方式启动应用

### 方法三：从源码运行

#### 1. 克隆项目
```bash
git clone <repository-url>
cd nihaoshijie
```

#### 2. 安装依赖
```bash
# 安装前端依赖
npm install

# 安装后端依赖
cd server
npm install
cd ..
```

#### 3. 配置环境变量
创建 `.env` 文件（前端）和 `server/.env` 文件（后端），配置数据库连接和其他参数。

#### 4. 启动开发服务器
```bash
# 启动后端服务器
cd server
npm run dev:js
cd ..

# 启动前端开发服务器
npm run dev

# 或启动 Electron 开发模式
npm run electron:dev
```

## 构建步骤

### 1. 安装构建依赖
```bash
# 使用国内镜像安装 electron
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

# 安装依赖
npm install --save-dev electron electron-builder
```

### 2. 构建应用
```bash
# 构建应用
npm run electron:build
```

构建完成后，可执行文件会生成在 `build_dist` 目录中：
- `语音连麦 0.0.0.exe`：便携版
- `语音连麦 Setup 0.0.0.exe`：安装版

## 项目结构

```
ihaoshijie/
├── build/              # 构建资源（图标等）
├── build_dist/         # 构建输出目录
├── dist/               # Vite 构建输出
├── electron/           # Electron 主进程和预加载脚本
│   ├── dist/           # 编译后的 Electron 文件
│   ├── main.ts         # Electron 主进程
│   └── preload.ts      # 预加载脚本
├── public/             # 静态资源
├── server/             # 后端代码
│   ├── app.js          # 后端服务器
│   ├── routes/         # API 路由
│   └── models/         # 数据模型
├── src/                # 前端源码
│   ├── components/     # React 组件
│   ├── services/       # 服务层
│   ├── types/          # TypeScript 类型定义
│   ├── App.tsx         # 主应用组件
│   └── main.tsx        # 应用入口
├── tsconfig.*.json     # TypeScript 配置文件
├── vite.config.ts      # Vite 配置
└── package.json        # 项目配置和依赖
```

## 环境变量配置

### 前端环境变量（.env）
```env
VITE_API_BASE_URL=http://localhost:3000/api
VITE_WS_URL=ws://localhost:3000
```

### 后端环境变量（server/.env）
```env
# 数据库连接字符串
DATABASE_URL="postgresql://username:password@localhost:5432/nihaoshijie"

# JWT 密钥
JWT_SECRET="your-secret-key"

# 服务器配置
PORT=3000
NODE_ENV=development
```

## 常见问题和解决方案

### 1. 麦克风权限问题
- **症状**：无法初始化音频，提示 "Failed to initialize audio"
- **解决方案**：
  1. 检查系统麦克风权限是否已授予
  2. 检查麦克风是否被其他应用占用
  3. 重新启动应用

### 2. 网络连接问题
- **症状**：无法连接到服务器，或房间内用户无法听到声音
- **解决方案**：
  1. 检查网络连接是否正常
  2. 确保防火墙未阻止应用访问网络
  3. 检查服务器是否正在运行

### 3. PTT 快捷键不工作
- **症状**：按下 Ctrl+T 没有反应
- **解决方案**：
  1. 确保应用已在前台运行
  2. 检查是否有其他应用占用了 Ctrl+T 快捷键
  3. 重新启动应用

### 4. 构建失败
- **症状**：运行 `npm run electron:build` 时失败
- **解决方案**：
  1. 确保已安装所有依赖
  2. 检查网络连接是否正常（electron 下载需要网络）
  3. 使用国内镜像：`set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/`

## 开发指南

### 添加新功能
1. 在 `src/components` 中创建新组件
2. 在 `src/services` 中添加相应的服务
3. 在 `src/types` 中添加类型定义
4. 在 `server/routes` 中添加 API 端点（如果需要）

### 调试技巧
- **前端调试**：在开发模式下，按 F12 打开开发者工具
- **后端调试**：使用 `console.log()` 或设置断点
- **WebRTC 调试**：在 Chrome 开发者工具的 "WebRTC" 标签页查看连接状态

## 许可证

本项目采用 MIT 开源许可证。

### MIT License

Copyright (c) 2026 依木

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

如果您有任何问题或建议，请联系：
- 开发者：依木
- Gitee：https://gitee.com/yimu321/voice-link

---

**最后更新**：2026-02-24