Skip to content

技术栈 ​

本文档列出 HayFrp Console 5.0 实际使用的框架、依赖与工程配置(以 package.json、vite.config.ts、tsconfig.json 为准)。

核心框架 ​

依赖版本说明
vue^3.4.21Vue 3,全部使用 Composition API + <script setup>
vue-router^4.3.0路由管理,HTML5 History 模式,全部懒加载
pinia^2.1.7状态管理(user、theme 两个 store)
vue-i18n^10.0.8国际化,legacy: false,5 种语言
vite^5.2.0构建工具与开发服务器(端口 3000)
typescript^5.4.2类型系统,strict 全开
vue-tsc^2.0.6构建时类型校验(vue-tsc -b)

UI 与交互 ​

依赖版本说明
naive-ui^2.38.1主 UI 组件库,深色 / 浅色主题、i18n 与日期 locale 联动
@lucide/vue^1.40.0图标库(Settings、Server、Rocket、Terminal、Users 等,按需导入)
vue3-slide-verify^1.1.8滑块验证码组件(已安装,当前页面未使用,预留给注册 / 登录风控)

常用 Naive UI 组件:NCard、NButton、NInput、NDataTable、NModal、NDrawer、NForm、NTag、NProgress、NStatistic、NResult、NSkeleton、NColorPicker、NCollapse、NCode、NConfigProvider。

网络与安全 ​

依赖版本说明
axios^1.6.8HTTP 客户端,services/api.ts 内封装故障转移与拦截器
dompurify^3.3.1富文本消毒(系统公告、服务商公告渲染前清洗,防 XSS)
@types/dompurify^3.2.0DOMPurify 类型定义
qrcode^1.5.4登录页二维码生成(QRCode.toDataURL)

axios 实例配置 ​

typescript
const API_ENDPOINTS = [
  'https://api.hayfrp.1zyq1.com',     // 主节点
  'https://v2.api.hayfrp.1zyq1.com',  // 备用 1
  'https://api.hayfrp.com'            // 备用 2
]

const instance = axios.create({
  baseURL: API_ENDPOINTS[0],
  headers: {
    'Content-Type': 'application/json',
    'waf': 'off'            // 绕过雷池(SafeLine)防火墙,后端要求
  },
  timeout: 15000
})
  • 故障转移:requestWithFallback() 在 ERR_NETWORK 或 HTTP >= 500 时切换到下一个端点,最多 3 次
  • 并发安全:每次请求创建独立 axios 实例(createRequestInstance()),避免共享 baseURL 产生竞态
  • 响应清洗:后端部分接口在 JSON 前输出 PHP Warning / Notice,拦截器会定位首个 { / [ 后重新解析
  • 401 处理:清除 Token、userStore.logout() 并跳转 /login

构建与部署 ​

依赖版本说明
@vitejs/plugin-vue^5.0.4Vue SFC 支持
vite-plugin-pwa^1.2.0PWA(autoUpdate、clientsClaim、skipWaiting、cleanupOutdatedCaches)
terser^5.46.0生产压缩,drop_console / drop_debugger
@types/node^25.2.3Node 类型(vite 配置中使用 path)
@types/qrcode^1.5.6qrcode 类型定义

构建分包 ​

typescript
manualChunks: {
  'vue-vendor': ['vue', 'vue-router', 'pinia'],
  'naive-ui': ['naive-ui'],
  'utils': ['axios', 'dompurify', 'qrcode']
}

TypeScript 严格项 ​

tsconfig.json 开启:strict、noUnusedLocals、noUnusedParameters、noFallthroughCasesInSwitch。

WARNING

由于 noUnusedLocals / noUnusedParameters 生效,任何未使用的变量或参数都会让 npm run build(vue-tsc -b)失败。

样式方案 ​

  • 组件内 <style scoped> 隔离样式,全局样式集中在 src/styles/main.css
  • CSS 变量驱动主题:
css
:root {
  --primary-color: #667eea;   /* 可由「面板个性化」覆盖 */
  --header-bg: #ffffff;
  --card-bg: #ffffff;
}
  • 全局 class 钩子:html.dark(暗色)、html.anime-style(二次元壁纸)、body.compact-mode(紧凑模式)
  • 移动端断点 768px,与 useThemeStore 的 MOBILE_BREAKPOINT 保持一致
  • 亮色模式下 App.vue 通过 themeOverrides.common.dividerColor 提高分割线对比度

本地存储与安全策略 ​

项方案
登录态localStorage csrf,JSON {token, expiry},7 天有效,启动时校验 + 定时自动登出
开放重定向utils/redirect.ts 白名单(同源 / 3 个 verify 域名的 HTTPS 443)
XSSVue 默认转义;富文本公告统一 DOMPurify.sanitize()
WAF请求头 waf: off 绕过雷池
云控命令前端对危险命令做拦截提示
启动器授权仅通过 http://localhost:21100 回环通信,Token 不出本机

浏览器支持 ​

  • Chrome / Edge 87+
  • Firefox 78+
  • Safari 14+
  • 移动端:iOS Safari 14+、Android Chrome 87+

使用了 AbortSignal.timeout()、structuredClone 等较新 API 的地方,建议按上述基线评估。

开发工具建议 ​

工具用途
VS Code + Vue - OfficialSFC 语法、类型提示
Vue DevTools组件 / Pinia 状态调试
ESLint / Prettier代码规范(当前仓库未内置配置,可按团队习惯引入)

后续可优化方向 ​

  1. 引入 ESLint + Prettier 配置并接入 CI
  2. 补充 Vitest 单元测试与 Playwright E2E(当前无测试框架)
  3. services/api.ts 体积较大(约 1000 行),可按模块拆分
  4. 逐步替换 any 与 Record<string, unknown>,完善后端响应类型
  5. 把 customize_settings 等纯前端偏好改为服务端同步(跨设备一致)

相关页面 ​

基于 MIT 许可证发布