JiwuChat 快速入门知识库
项目概述
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 |
快速开始
环境要求
bash
# Node.js 22.20.0 (由 Volta 自动管理) # pnpm 10.13.1 (必须使用 pnpm) # Rust 工具链 (桌面端开发必需)
安装依赖
bash
pnpm install
开发命令
bash
# 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
构建命令
bash
# 完整生产构建 (Web + 桌面) pnpm run build # 仅 Web pnpm run build:nuxt # 仅桌面端 pnpm run build:tauri
代码质量
bash
# 代码检查和修复 (提交前运行) pnpm run lint:fix # Rust 类型检查 cd src-tauri && cargo check
项目目录结构
txt
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 # 项目说明
核心架构模式
1. Composables 优先架构
业务逻辑集中在 /app/composables/ 目录，通过 Nuxt 自动导入:
typescript
// 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);
2. 模块化 Store 设计
useChatStore 采用组合式模块拆分:
typescript
// 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 };
});
3. 平台适配层
桌面端和移动端通过 Rust 模块分离:
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;
4. WebSocket 架构
txt
useWsCore.ts # WebSocket 连接核心
↓
adapters/ # 协议适配器
├── browserAdapter # 浏览器原生 WebSocket
└── tauriAdapter # Tauri WebSocket 插件
↓
useWsNotification.ts # 消息通知处理
↓
useWsStore.ts # 连接状态管理
Commit 规范
项目使用 Conventional Commits + commitlint 校验:
text
<type>(<scope>): <subject> # 类型说明 feat # 新功能 fix # Bug 修复 docs # 文档变更 style # 代码格式 (不影响逻辑) refactor # 重构 perf # 性能优化 test # 测试 chore # 构建/工具变动 revert # 回退 build # 打包 ci # CI 配置
示例:
bash
feat(chat): 添加消息编辑功能 fix(router): 修复页面跳转状态丢失问题 refactor(drawer): 重构抽屉组件以提升可维护性 style(components): 更新对话框和滑动按钮样式 chore(deps): 升级依赖包版本
Vue 组件开发规范
Props 定义
使用解构默认值，类型分离:
vue
<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:
vue
<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/ |
常见问题排查
Tauri 构建失败
bash
# 更新 Rust 工具链 rustup update # 清理 Cargo 缓存 cd src-tauri && cargo clean
依赖问题
bash
# 清理并重装 rm -rf node_modules pnpm-lock.yaml && pnpm install
OAuth 深度链接测试
bash
# 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:nuxt - •修改代码: 热更新自动生效
- •代码检查:
pnpm run lint:fix - •提交代码: 遵循 Conventional Commits 规范
- •构建测试:
pnpm run build:nuxt
提示: 不要自动提交，用户偏好手动提交代码。