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 |
快速开始
环境要求
# 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 # 项目说明核心架构模式
1. Composables 优先架构
业务逻辑集中在 /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);2. 模块化 Store 设计
useChatStore 采用组合式模块拆分:
// composables/store/useChatStore/index.ts
export const useChatStore = defineStore("chat", () => {
const ui = createUIModule(); // UI 状态
const compose = createComposeInputModule(); // 输入框状态
const contacts = createContactsModule(); // 联系人管理
const