JiwuChat 项目快速入门知识库 - 基于 Tauri 2.9+ 和 Nuxt.js 4.0 的跨平台聊天应用
JiwuChat 是一款基于 Tauri 2.9+ 和 Nuxt.js 4.0 构建的跨平台聊天应用,支持桌面端、Web 端和移动端。应用体积轻量(约 10MB),集成 AI 对话、WebRTC 通话、多平台 OAuth 认证等功能。
| 层级 | 技术 | 版本 |
|---|---|---|
| 前端框架 | Nuxt.js + Vue 3 | 4.3.0 |
| 类型系统 | TypeScript | 5.9.3 |
| UI 组件库 | Element Plus | 2.13.2 |
| 原子化 CSS | UnoCSS | 66.5.3 |
| 状态管理 | Pinia | 3.0.4 |
| 桌面端 | Tauri (Rust) | 2.9+ |
| 富文本编辑器 | TipTap | - |
| Markdown 编辑器 | md-editor-v3 | 5.8.4 |
| 包管理器 | pnpm | 10.13.1 |
| Node.js | (Volta 管理) | 22.20.0 |
| 构建工具 | Vite + Rolldown | 7.2.11 |
# Node.js 22.20.0 (由 Volta 自动管理)
# pnpm 10.13.1 (必须使用 pnpm)
# Rust 工具链 (桌面端开发必需)
pnpm install
# Web 开发 (最常用)
pnpm run dev:nuxt
# 带 VS Code 调试器的 Web 开发
pnpm run dev:vscode:nuxt
# 桌面端开发
pnpm run dev:tauri
# 或
pnpm run dev:desktop
# 移动端开发
pnpm run dev:android
pnpm run dev:ios # 仅 macOS
# 生产环境测试
pnpm run prod:nuxt
pnpm run prod:nuxt:local
# 完整生产构建 (Web + 桌面)
pnpm run build
# 仅 Web
pnpm run build:nuxt
# 仅桌面端
pnpm run build:tauri
# 代码检查和修复 (提交前运行)
pnpm run lint:fix
# Rust 类型检查
cd src-tauri && cargo check
JiwuChat/
├── app/ # Nuxt.js 前端源码 (srcDir)
│ ├── assets/ # 静态资源 (styles, fonts, images)
│ │ └── styles/ # 全局样式文件
│ │ ├── base.scss # 基础样式
│ │ ├── animate/ # 动画样式
│ │ ├── element/ # Element Plus 主题覆盖
│ │ ├── overrides.scss # 组件样式覆盖
│ │ └── patterns/ # 背景图案样式
│ ├── components/ # Vue 组件 (按功能分组)
│ │ ├── auth/ # 认证相关组件
│ │ ├── btn/ # 按钮组件
│ │ ├── chat/ # 聊天核心组件
│ │ │ ├── AI/ # AI 对话组件
│ │ │ ├── ContactList/ # 联系人列表
│ │ │ ├── Dialog/ # 对话框
│ │ │ ├── Friend/ # 好友面板
│ │ │ ├── Message/ # 消息表单和列表
│ │ │ ├── Msg/ # 消息类型组件
│ │ │ ├── Preview/ # 预览组件
│ │ │ └── Room/ # 房间/群组组件
│ │ ├── common/ # 通用组件
│ │ │ ├── Drawer/ # 抽屉组件
│ │ │ ├── Emoji/ # 表情选择器
│ │ │ ├── List/ # 列表组件 (虚拟滚动等)
│ │ │ └── Popup/ # 弹窗组件
│ │ ├── menu/ # 菜单组件
│ │ ├── setting/ # 设置组件
│ │ └── user/ # 用户相关组件
│ ├── composables/ # 组合式函数 (核心业务逻辑)
│ │ ├── api/ # API 层
│ │ │ ├── chat/ # 聊天 API (friend, group, rtc, room, ai)
│ │ │ ├── community/ # 社区 API
│ │ │ ├── res/ # 资源/OSS API
│ │ │ ├── sys/ # 系统 API (api-key)
│ │ │ └── user/ # 用户 API (info, safe, wallet, address, bills)
│ │ ├── hooks/ # 可复用业务逻辑 Hooks
│ │ │ ├── msg/ # 消息处理 (队列, 文件上传, WebRTC, 弹窗)
│ │ │ ├── oauth/ # OAuth 认证
│ │ │ ├── oss/ # OSS 文件上传
│ │ │ └── ws/ # WebSocket 管理
│ │ │ ├── adapters/ # 协议适配器 (浏览器/Tauri)
│ │ │ ├── useWsCore.ts # WebSocket 核心连接
│ │ │ └── useWsNotification.ts # 实时通知
│ │ ├── store/ # Pinia 状态管理
│ │ │ ├── useChatStore/ # 聊天状态 (核心)
│ │ │ │ └── hooks/ # 模块化 hooks
│ │ │ ├── useUserStore.ts # 用户状态
│ │ │ ├── useSettingStore.ts# 设置状态
│ │ │ └── useWsStore.ts # WebSocket 状态
│ │ ├── tauri/ # Tauri 专用集成
│ │ │ ├── setting.ts # 桌面端设置
│ │ │ ├── extension.ts # 扩展功能
│ │ │ └── tray.ts # 系统托盘
│ │ └── utils/ # 工具函数
│ │ ├── useCheck.ts # 校验工具
│ │ ├── useCrypto.ts # 加密工具
│ │ ├── useDB.ts # IndexedDB 操作
│ │ ├── useDelay.ts # 延迟/防抖
│ │ ├── useSseRequest.ts # SSE 请求
│ │ ├── useUrl.ts # URL 处理
│ │ └── useWebToast.ts # Toast 提示
│ ├── constants/ # 常量定义
│ ├── directives/ # 自定义指令
│ ├── init/ # 应用初始化
│ │ ├── system.ts # 系统初始化
│ │ ├── macos.ts # macOS 专用
│ │ ├── iframe.ts # iframe 集成
│ │ ├── share.ts # 分享功能
│ │ └── setting/ # 设置初始化
│ │ ├── autostart.ts # 开机自启
│ │ ├── font.ts # 字体设置
│ │ ├── hotkey.ts # 快捷键
│ │ ├── theme.ts # 主题
│ │ ├── update.ts # 更新检测
│ │ ├── visibility.ts # 窗口可见性
│ │ └── window.ts # 窗口管理
│ ├── middleware/ # 路由中间件
│ ├── pages/ # 页面路由 (文件路由)
│ │ ├── index.vue # 首页 (聊天主界面)
│ │ ├── login.vue # 登录页
│ │ ├── extend.vue # 扩展页
│ │ ├── index/ # 聊天子页面
│ │ ├── desktop/ # 桌面端专属页面
│ │ ├── oauth/ # OAuth 回调页面
│ │ ├── user/ # 用户页面
│ │ └── msg/ # 消息页面
│ ├── plugins/ # Nuxt 插件
│ │ ├── error-handler.ts # 错误处理
│ │ ├── right-menu.ts # 右键菜单
│ │ └── markdown.ts # Markdown 渲染
│ ├── types/ # 类型定义
│ │ ├── chat/ # 聊天类型
│ │ │ └── WsType.ts # WebSocket 消息类型
│ │ ├── user/ # 用户类型
│ │ └── tauri.ts # Tauri 类型
│ ├── utils/ # 工具函数
│ └── windows/ # 窗口管理
│ ├── index.ts # 窗口定义
│ └── actions.ts # 窗口操作
├── src-tauri/ # Tauri Rust 后端
│ ├── src/
│ │ ├── main.rs # 入口文件
│ │ ├── lib.rs # 库文件
│ │ ├── desktops/ # 桌面端模块
│ │ │ ├── mod.rs # 模块导出
│ │ │ ├── setup.rs # 应用设置
│ │ │ ├── window.rs # 窗口管理和动画
│ │ │ ├── tray.rs # 系统托盘
│ │ │ ├── commands.rs # Tauri 命令
│ │ │ └── deeplink/ # OAuth 深度链接
│ │ │ ├── mod.rs # 模块导出
│ │ │ ├── handlers.rs # 链接处理器
│ │ │ ├── oauth.rs # OAuth 逻辑
│ │ │ └── types.rs # 类型定义
│ │ └── mobiles/ # 移动端模块
│ │ ├── mod.rs
│ │ ├── setup.rs
│ │ ├── window.rs
│ │ ├── commands.rs
│ │ └── deeplink/ # 移动端深度链接
│ ├── capabilities/ # 权限配置
│ ├── icons/ # 应用图标
│ ├── tauri.conf.json # Tauri 主配置
│ ├── tauri.*.conf.json # 平台特定配置
│ └── Cargo.toml # Rust 依赖
├── public/ # 静态资源
│ └── useWsWorker.js # WebSocket Worker
├── config/ # 配置文件
├── scripts/ # 构建脚本
├── nuxt.config.ts # Nuxt 配置
├── uno.config.ts # UnoCSS 配置
├── package.json # 项目依赖
├── CLAUDE.md # Claude Code 指南
└── README.md # 项目说明
业务逻辑集中在 /app/composables/ 目录,通过 Nuxt 自动导入:
// composables/api/chat/friend.ts - API 调用示例
export function getFriendList(token: string) {
return useHttp.get<Result<FriendVO[]>>(
"/chat/friend/list",
{},
{
headers: { Authorization: token }
}
);
}
// 页面/组件中直接使用 (自动导入)
const { data } = await getFriendList(userToken);
useChatStore 采用组合式模块拆分:
// composables/store/useChatStore/index.ts
export const useChatStore = defineStore("chat", () => {
const ui = createUIModule(); // UI 状态
const compose = createComposeInputModule(); // 输入框状态
const contacts = createContactsModule(); // 联系人管理
const messages = createMessagesModule(); // 消息管理
const members = createMembersModule(); // 群成员管理
const rtc = createRtcModule(); // WebRTC 通话
return { ...ui, ...compose, ...contacts, ...messages, ...members, ...rtc };
});
桌面端和移动端通过 Rust 模块分离:
// src-tauri/src/desktops/mod.rs
pub mod setup;
pub mod window;
pub mod tray;
pub mod commands;
pub mod deeplink;
// src-tauri/src/mobiles/mod.rs
pub mod setup;
pub mod window;
pub mod commands;
pub mod deeplink;
useWsCore.ts # WebSocket 连接核心
↓
adapters/ # 协议适配器
├── browserAdapter # 浏览器原生 WebSocket
└── tauriAdapter # Tauri WebSocket 插件
↓
useWsNotification.ts # 消息通知处理
↓
useWsStore.ts # 连接状态管理
项目使用 Conventional Commits + commitlint 校验:
<type>(<scope>): <subject>
# 类型说明
feat # 新功能
fix # Bug 修复
docs # 文档变更
style # 代码格式 (不影响逻辑)
refactor # 重构
perf # 性能优化
test # 测试
chore # 构建/工具变动
revert # 回退
build # 打包
ci # CI 配置
示例:
feat(chat): 添加消息编辑功能
fix(router): 修复页面跳转状态丢失问题
refactor(drawer): 重构抽屉组件以提升可维护性
style(components): 更新对话框和滑动按钮样式
chore(deps): 升级依赖包版本
使用解构默认值,类型分离:
<script lang="ts">
export interface MyComponentProps {
name?: string
count?: number
}
</script>
<script setup lang="ts">
const { name = "default", count = 0 } = defineProps<MyComponentProps>();
</script>
优先使用 UnoCSS 工具类,避免 BEM:
<template>
<!-- 推荐: 使用 UnoCSS shortcuts -->
<div class="card-bg-color p-4 rounded">
<span class="text-small text-color">内容</span>
</div>
</template>
常用 UnoCSS Shortcuts:
| 类名 | 作用 |
|---|---|
card-bg-color | 卡片背景 (适配暗色) |
bg-color / bg-color-2 / bg-color-3 | 背景色层级 |
text-color | 主文本颜色 |
text-small / text-mini | 次要文本 |
border-default | 默认边框 |
btn-primary / btn-danger | 按钮样式 |
flex-row-c-c | 居中 flex |
| 用途 | 路径 |
|---|---|
| 聊天状态管理 | app/composables/store/useChatStore/ |
| 用户状态 | app/composables/store/useUserStore.ts |
| WebSocket 管理 | app/composables/hooks/ws/ |
| API 调用 | app/composables/api/ |
| 消息组件 | app/components/chat/Msg/ |
| Element Plus 主题 | app/assets/styles/element/ |
| UnoCSS 配置 | uno.config.ts |
| Tauri 桌面端 | src-tauri/src/desktops/ |
| Tauri 移动端 | src-tauri/src/mobiles/ |
# 更新 Rust 工具链
rustup update
# 清理 Cargo 缓存
cd src-tauri && cargo clean
# 清理并重装
rm -rf node_modules pnpm-lock.yaml && pnpm install
# macOS 测试
open "jiwuchat://oauth/callback?platform=test"
| 包名 | 用途 |
|---|---|
@tauri-apps/api | Tauri 前端 API |
@tauri-apps/plugin-* | Tauri 插件 (autostart, dialog, fs, notification, updater 等) |
element-plus | UI 组件库 |
@vueuse/core | Vue 组合式工具集 |
pinia | 状态管理 |
qiniu-js | 七牛云 OSS 上传 |
md-editor-v3 | Markdown 编辑器 |
rolldown-vite | 构建工具 (pnpm overrides) |
pnpm run dev:nuxtpnpm run lint:fixpnpm run build:nuxt提示: 不要自动提交,用户偏好手动提交代码。