技术栈
本文档列出 HayFrp Console 5.0 实际使用的框架、依赖与工程配置(以 package.json、vite.config.ts、tsconfig.json 为准)。
核心框架
| 依赖 | 版本 | 说明 |
|---|---|---|
vue | ^3.4.21 | Vue 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.8 | HTTP 客户端,services/api.ts 内封装故障转移与拦截器 |
dompurify | ^3.3.1 | 富文本消毒(系统公告、服务商公告渲染前清洗,防 XSS) |
@types/dompurify | ^3.2.0 | DOMPurify 类型定义 |
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.4 | Vue SFC 支持 |
vite-plugin-pwa | ^1.2.0 | PWA(autoUpdate、clientsClaim、skipWaiting、cleanupOutdatedCaches) |
terser | ^5.46.0 | 生产压缩,drop_console / drop_debugger |
@types/node | ^25.2.3 | Node 类型(vite 配置中使用 path) |
@types/qrcode | ^1.5.6 | qrcode 类型定义 |
构建分包
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) |
| XSS | Vue 默认转义;富文本公告统一 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 - Official | SFC 语法、类型提示 |
| Vue DevTools | 组件 / Pinia 状态调试 |
| ESLint / Prettier | 代码规范(当前仓库未内置配置,可按团队习惯引入) |
后续可优化方向
- 引入 ESLint + Prettier 配置并接入 CI
- 补充 Vitest 单元测试与 Playwright E2E(当前无测试框架)
services/api.ts体积较大(约 1000 行),可按模块拆分- 逐步替换
any与Record<string, unknown>,完善后端响应类型 - 把
customize_settings等纯前端偏好改为服务端同步(跨设备一致)