简介

文档维护人：降星驰（QQ：735845305，Email：735845305@qq.com）

这是团剧共创的前端项目。项目采用react作为框架，采用响应式界面设计。使用electron构建pc客户端，使用混合开发模式构建安卓客户端。基于webgal导出跑团replay。

在开始之前

node版本

请确保你的node版本在22及以上。

安装依赖

pnpm install

electron安装与配置

如果你的开发不涉及electron，可跳过此步。

在安装electron依赖的时候，如果遇到

Electron failed to install correctly,
 please delete node_modules/electron and try installing again

尝试

node node_modules/electron/install.js

如果要执行 electron 打包（electron-builder）：

• 安装包会携带 WebGAL_Terre 运行时。
• pnpm electron:prepare:resources 默认会从 D:\A_webgal\WebGAL_Terre\release 同步运行时到 extraResources/（按仓库相对路径等价于 ..\..\A_webgal\WebGAL_Terre\release）。
• 如果 WebGAL_Terre 不在默认位置，可设置环境变量 WEBGAL_TERRE_RELEASE_DIR 指向 release 目录。
• 也可以手动把 WebGAL_Terre release 内容放到 extraResources/，并确保 WebGAL_Terre.exe 位于该目录根层级。

electron-builder 工具下载不稳定（Windows）

Windows 下 nsis / winCodeSign 等工具会在首次构建时由 electron-builder 自动下载到本机缓存；如果网络波动导致下载失败，建议：

• 先只构建 zip：pnpm electron:build:win:zip
• 再单独构建 nsis：pnpm electron:build:win:nsis
• 固定缓存目录（可选）：设置环境变量 ELECTRON_BUILDER_CACHE 指向一个稳定路径（例如 D:\cache\electron-builder），避免系统盘空间/权限/清理工具影响
• 使用镜像（可选，网络环境需要时）：设置 ELECTRON_BUILDER_BINARIES_MIRROR 指向可用镜像源

这些设置只影响构建时下载工具，不影响应用运行。

一键自动化发布 Electron（本地 + 云端）

当客户端需要发新版本时，建议统一使用以下命令：

pnpm release:electron -- --bump patch

该命令会按顺序执行：

• 校验工作区干净且当前分支为 main
• git pull --rebase origin main
• 更新 package.json 版本号
• 本地打包 Windows 客户端（默认 zip + nsis）
• 自动提交版本号并 git push origin main
• 触发云端增量更新工作流（main 推送自动触发）

常用参数：

• --bump patch|minor|major：按语义版本递增
• --version x.y.z：直接指定版本号（与 --bump 二选一）
• --local-build all|zip|nsis|none：本地打包策略（默认 all）
• --no-push：只做本地提交，不推送
• --message "..."：自定义提交信息

配置环境

在项目根目录创建 .env （或 .env.development)文件，把下面的文字粘贴进去。

VITE_API_BASE_URL=https://tuan.chat/api
VITE_API_WS_URL=wss://tuan.chat/ws
VITE_TERRE_URL=http://localhost:3001
VITE_TERRE_WS=ws://localhost:3001/api/webgalsync

测试环境可使用 .env.test（已提供），默认域名为 https://test.tuan.chat，并且会开启 VITE_ENABLE_REACT_SCAN=true。

自动测试登录态

需要跑依赖登录态的浏览器/e2e 测试时，不要反复走登录页 UI。先在本机创建 .env.development.local（该文件已被 gitignore 忽略，不会提交）：

TC_E2E_USER_ID=10001
TC_E2E_PASSWORD=<本地测试账号密码>
TC_E2E_LOGIN_METHOD=userId
TC_E2E_API_BASE_URL=http://localhost:8081
TC_E2E_APP_ORIGIN=http://localhost:5177

后端可用后运行：

pnpm test:e2e:auth-state

脚本会调用 /user/login，并把 Playwright 可复用的登录态写到 .tmp/e2e-auth-state.json。测试里直接复用该文件：

const context = await browser.newContext({
  storageState: ".tmp/e2e-auth-state.json",
});

IDE设置

Vscode 设置

仓库包含一个 .vscode 文件夹，其中包含设置。该设置会阻止默认的 prettier 扩展，并使用 esLint 进行保存时的格式化。格式化程序已在 eslint.config.mjs 文件中预先配置。请确保你已在 Vscode 中安装了 eslint 扩展。

由于 Vscode 的限制，在你克隆仓库并安装依赖后，需要在终端中运行 pnpm lint以完成 eslint 的设置。

Webstorm 设置

注意将设置中开启 Run eslint --fix on save 就可以，无需装别的插件（万一tailwind没提示就装一个tailwind的插件）。

启动！！！

pnpm dev

项目已预先配置了 husky 和 lint-staged，以便在每次提交前运行 lint，并执行编码/乱码检测（node ./scripts/check-encoding.mjs）。

如果因为 lint 错误而提交失败，可以运行以下命令修复错误：

pnpm lint:fix

这将对整个仓库进行 lint，修复 eslint 可修复的错误，并显示其余的错误。

CI/CD 流程

自动化测试

自动部署：

• main 推送：生产部署到 https://tuan.chat/
• dev 推送：测试部署到 https://test.tuan.chat/（test 模式构建，开启 React Scan）

Electron 增量更新发布：

• main 推送会触发 .github/workflows/electron-update-publish.yml
• 工作流会构建 NSIS 包并发布以下文件：latest.yml、*Setup*.exe、*Setup*.exe.blockmap
• 客户端更新地址（electron-builder publish.url）：https://tuan.chat/updates/
• 默认发布目录：/www/wwwroot/tuan-chat-web/updates
• 工作流优先读取 UPDATE_*，未配置时会回退到 CD 使用的 SERVER_* / SSH_* 凭据。
• 若 UPDATE_SERVER_PATH 填的是站点根目录（如 /www/wwwroot/tuan-chat-web），工作流会自动追加 /updates。
• 可选 Secrets：
• UPDATE_SERVER_HOST：更新服务器 SSH 地址（默认 38.14.195.6）
• UPDATE_SERVER_PORT：更新服务器 SSH 端口（默认 22）
• UPDATE_SERVER_USERNAME：SSH 用户名（默认回退 SERVER_USERNAME / SSH_USERNAME）
• UPDATE_SERVER_PASSWORD：SSH 密码（默认回退 SERVER_PASSWORD / SSH_PASSWORD）
• UPDATE_SERVER_PATH：远端发布目录（默认 /www/wwwroot/tuan-chat-web/updates）

文件架构

core/** ， models/**，services/**，

这些由openApi自动生成。

useWebsocket.tsx

websocket的utils

• 已支持好友申请推送（WS type=21）的基础处理（缓存刷新钩子）。
• 为了方便排查“还有哪些 WS 类型没处理”，会把已实现/未处理类型与最近消息记录到 window.__TC_WS_DEBUG__，并在首次遇到未知 type ʱ console.warn。

hooks/** ，useQueryHooks.tsx

存放react-query相关的钩子函数。

如果要用react-query，请把新的钩子函数放在hooks文件夹下对应的文件内。

并且一定要注意有没有已经定义好了的钩子函数，不要重复定义！（ctrl+shift+f全局搜索一下）

并且mutation后记得invalidate对应的请求。

./app

components

页面组件都放这里，按照大模块分类。common文件夹内放公用的组件。

routes

对应路由的最终页面。

updateLogs

存放更新日志（会以弹窗形式给用户看）

webgal

webgal相关

utils

存放各种工具类

./android

安卓客户端的工程文件夹，用android studio打开。使用混合开发模式。

依赖

Blocksuite 参考仓库

自 2026-04-18 起，团剧共创使用的 Blocksuite 参考仓库统一迁移到：

• D:\A_blocksuite\AFFiNE
• D:\A_blocksuite\OctoBase

详细说明见 docs/integrations/blocksuite.md 和 docs/vendors/blocksuite/index.md。

UI库

https://daisyui.com/

https://tailwindcss.com/

Ahooks

阿里的钩子函数库，很实用。

https://ahooks.js.org/zh-CN/

useHooks

同样是一个实用的钩子函数库。

https://usehooks.com/

React-taost

用于发送通知

https://react-hot-toast.com/docs

eslint

修正格式。在每次commit的时候都会进行eslint的检查。如果检查不通过commit会失败。

如果你用的ide是webstorm，可以在这里打开eslint错误的自动修复：

icon库

到这个网站上搜索后直接复制粘贴就行。

https://reactsvgicons.com/

react-virtuoso

https://virtuoso.dev/

虚拟列表的轮子，但ahook中也提供了虚拟列表，可按情况选择