treg前端架构解析：Vue 3 Dashboard 与 Vite 构建完全指南
【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg
🎯 treg 是一个"Agent 工具的 OpenRouter"——用一个统一密钥调用 2000+ 种工具（Semrush、Moz、Google Ads、Instagram 等）。它的前端 Dashboard采用Vue 3 + Vite技术栈构建：没有独立的前端服务器，整个编译后的应用直接由 Python Web 服务同源托管。这篇文章带你快速看懂 treg 的前端架构、Vite 双构建流水线、懒加载策略与本地开发配置，帮助你以最低成本跑起并改造这个 Dashboard。
一、前端定位：只有一个 Dashboard
treg 的前端遵循"单一事实来源"原则：
- 所有入口（登录前后、目录页、分享链接）都提供同一套编译产物，源码全部位于 frontend/ 目录
- 没有第二套生产前端，Python 后端（端口 18790）直接吐出编译好的
index.html与静态资源 - 构建产物写入
src/treg/web/dashboard/，被 Git 忽略、随 Python 安装包分发
这意味着：改前端 → 重新构建 → Python 服务即刻生效，回滚只需部署上一个构建版本。
二、技术栈速览
来自 frontend/package.json：
| 组件 | 版本 | 角色 |
|---|---|---|
| Vue | 3.5.41 | 核心框架（仅打包 runtime，不含模板编译器） |
| Vite | 8.3.0 | 开发服务器 + 构建 |
| TypeScript | 5.9.3 | 类型系统（vue-tsc检查） |
| Vitest | 5.0.1 | 单元测试 |
| Playwright | 1.63.0 | 浏览器端到端测试 |
| @fontsource/* | 5.3.0 | 同源自托管字体（Geist Pixel / DM Mono） |
注意engines要求Node ≥ 22.12，升级 Node 前请先确认本地版本。
三、目录结构与模块划分
Dashboard 源码组织在 frontend/src/，各目录职责清晰：
frontend/src/ ├── App.vue # 应用外壳：按视图条件挂载页面与对话框 ├── views.ts # 页面/对话框的按需加载注册表 ├── main.ts # 入口：挂载 App、注册 v-dialog 指令、字体 ├── api.ts # 同源 JSON 传输层（会话过期、边缘编码） ├── pages/ # 15 个页面：目录、活动、工具、团队、Hub 等 ├── components/ # 共享导航与 UI 组件 ├── dialogs/ # 17 个对话框（连接 Token、充值、分享…） ├── agent-setup/ # 与独立 Enrich Arena 页共享的 onboarding 组件 └── state/ # 按功能拆分的状态模块（Options API）状态层是这套架构的特色：state/controller.js 把session、team、billing、catalog、hub等 30+ 个按功能分组的状态模块拼装成一个巨型控制器，再通过 state/context.ts 的provide/inject暴露给组件。这是"增量抽取"设计——旧模块共享应用级状态，新组件则被要求使用类型化的 props/events。
四、Vite 构建流水线：一次构建，两个产物
1. 主构建：Dashboard SPA
核心配置在 frontend/vite.config.ts：
base: '/app/ui/'：所有资源挂在/app/ui/前缀下，由 Python 服务同源提供outDir指向src/treg/web/dashboard：前端构建直接落进 Python 包目录，wheel/sdist 打包时自动带上- 代码分割：
vue与@vue/*被单独拆成一个 chunk，利于跨页面缓存 - 开发代理：Vite（5173 端口）把非
/app/ui/的请求代理到本地 Python 服务（18790 端口），保证同源 Cookie 生效
2. 副构建：Enrich Arena 独立脚本
vite.agent-setup.config.ts 把 agent-setup/ 的同一批组件再编译一次，产出agent-setup.js——一个 IIFE 经典脚本（暴露为window.TregAgentSetup），供不使用 Vue 构建管线的独立 Arena 页运行，vue作为全局变量外挂。
两个构建串接在 package.json 的build脚本里：
bash scripts/build-dashboard.sh完整流程 =vue-tsc类型检查 → Vite 主构建 → agent-setup 构建 → 拷贝 Vue 全局 runtime 与许可（copy-runtime.mjs）。
五、本地开发：Vite 热更新最快配置
三步跑起开发环境（详见 frontend/README.md）：
- 安装 Node 22.12+ 与 npm
- 仓库根目录执行
scripts/dev-local.sh up - 打开
http://localhost:18790/app——Python 响应里会动态加载 5173 端口的 Vite 模块，实现热更新
⚠️ 本地热更新依赖TREG_FRONTEND_DEV开关，不能与 PostgreSQL 或公网域名同时使用；要在局域网其他设备预览，先build再用TREG_FRONTEND_DEV=false重启。
六、加载策略：首屏快、后续不卡
views.ts 是全站的"按需加载中枢"，两层机制让懒加载对用户完全无感：
preloadInitialView：入口执行时就根据 URL 解析目标页面，与/meta、/auth/me网络请求并行下载首个视图的 chunkprefetchAfterBoot：启动完成后在浏览器空闲期（requestIdleCallback）逐个预取用户可达的页面与对话框 chunk，之后切换视图同步渲染、零白屏
传输层 api.ts 同样讲究：401 时自动触发会话过期跳转；大体积请求体（如导入 Skill 文件夹）在遇到边缘 403 时自动以 base64 编码重试，绕开 WAF 拦截。
七、质量保障：三层测试门禁
| 层级 | 工具 | 命令 | 说明 |
|---|---|---|---|
| 类型 | vue-tsc | npm --prefix frontend run check | 构建前强制通过 |
| 单元 | Vitest | npm --prefix frontend test | tests/ 覆盖传输、存储等 |
| E2E | Playwright | npm --prefix frontend run test:e2e | 对构建产物跑 Chromium |
E2E 有两点值得借鉴（playwright.config.ts）：
- 测试服务器使用OS 分配的随机空闲端口，多个 worktree 并行跑测试互不冲突
- e2e/layout.spec.ts 在桌面与手机宽度下渲染主页面，自动检测文字互相覆盖、内容溢出、横向滚动等布局事故
八、上手清单 ✅
- 克隆仓库后先
node -v确认 ≥ 22.12 bash scripts/dev-local.sh up启动全栈，浏览器打开/app看热更新- 改完前端务必
bash scripts/build-dashboard.sh再跑 Playwright——浏览器测试只认构建产物 - 新增页面/对话框：在 views.ts 注册
lazy()即可，切勿在 App.vue 里静态 import，否则它会被塞进每个访客都下载的首屏 chunk
总结：treg 的前端是一个"Python 同源托管的 Vue 3 单页应用"——Vite 双构建同时服务 Dashboard 与独立 Arena 页，views.ts的预加载/空闲预取让首屏与切换都很快，状态层则用 provide/inject 平滑兼容了旧的 Options API 模块。理解这套架构后，无论是加页面、调样式还是跑 E2E，你都已具备完整地图。🚀
【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
