开发指南
本文档介绍 HayFrp Console 5.0 的本地开发、构建校验与部署方式。
环境要求
| 工具 | 版本要求 |
|---|---|
| Node.js | >= 18(推荐 20+;本项目脚本在 Node 24 下验证过) |
| 包管理器 | npm(仓库同时存在 package-lock.json 与 pnpm-lock.yaml,不要切换包管理器) |
| Git | 任意较新版本 |
安装与启动
bash
# 1. 安装依赖
npm install
# 2. 启动开发服务器(端口 3000)
npm run devTIP
开发端口固定为 3000(vite.config.ts 的 server.port)。如需修改,直接改配置,或用 npm run dev -- --port 3001。
可用脚本
| 命令 | 说明 |
|---|---|
npm run dev | 启动 Vite 开发服务器 |
npm run build | vue-tsc -b && vite build,类型校验 + 生产构建 |
npm run preview | 本地预览构建产物(dist/) |
构建即校验
npm run build 会先执行 vue-tsc -b,tsconfig.json 开启了:
strictnoUnusedLocalsnoUnusedParametersnoFallthroughCasesInSwitch
未使用的变量 / 参数会让构建失败,提交 PR 前必须跑通 npm run build。仓库当前没有单元测试 / E2E 框架,npm run build 就是唯一的强校验门。
目录与别名
@/ 指向 src/:
typescript
import { api } from '@/services/api'
import { useUserStore } from '@/stores/user'
import AppSkeleton from '@/components/AppSkeleton.vue'开发规范
命名
| 类型 | 规范 | 示例 |
|---|---|---|
| 视图 / 组件 | PascalCase | CloudControl.vue、NodeMap.vue |
| composable | useXxx.ts | useNotification.ts |
| store | 文件名小写,导出 useXxxStore | stores/theme.ts → useThemeStore |
| 工具 | camelCase | nodeGeo.ts、redirect.ts |
组件结构
vue
<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'
import { useMessage } from 'naive-ui'
import { useI18n } from 'vue-i18n'
import { api } from '@/services/api'
import { useUserStore } from '@/stores/user'
const message = useMessage()
const { t } = useI18n()
const userStore = useUserStore()
const loading = ref(false)
const list = ref<Proxy[]>([])
async function fetchList() {
loading.value = true
try {
const res = await api.listProxies(userStore.csrf!)
list.value = res.proxies || []
} catch (e) {
message.error(t('proxies.getDataFailed'))
} finally {
loading.value = false
}
}
onMounted(fetchList)
</script>
<template>
<AppSkeleton v-if="loading" variant="list" />
<NDataTable v-else :data="list" />
</template>
<style scoped>
/* 2 空格缩进 */
</style>约定清单
- 缩进统一 2 空格(Vue / TS / CSS)
- 一律
<script setup lang="ts">+ Composition API - API 调用只走
@/services/api,不要在组件里直接axios - 文案一律走 i18n(
t()/$t()),5 个语言文件同步补齐 - 判断成功状态同时接受
status === 200与status === true - 富文本渲染(公告)必须
DOMPurify.sanitize() - 状态优先放 Pinia;页面局部状态用
ref/reactive - 注释用中文,说明「为什么」而不是「做了什么」
Git 提交规范
bash
git commit -m "feat: 联机大厅支持房间密码"
git commit -m "fix: 修复扫码登录成功后被立即登出"
git commit -m "docs: 补全 API 文档"
git commit -m "style: 优化移动端菜单布局"
git commit -m "refactor: 拆分 api.ts 的用户模块"一次提交只做一件逻辑上的事;提交前跑 npm run build。
调试技巧
| 手段 | 用途 |
|---|---|
| 浏览器 Network | 观察 API 请求 / 响应;注意接口会按 15 秒超时、失败后自动切端点 |
| Vue DevTools | 查看组件树与 Pinia(user、theme)状态 |
localStorage 面板 | 检查 csrf(含 expiry)、theme、customize_settings、hayfrp-locale 等 |
控制台 HayFrp() | 彩蛋:全屏 HayFrp 文字 + 每 500ms 切换明暗 |
控制台 testOffline() | 手动触发 PWA 离线弹窗 |
控制台 HayFrpCnRedirect({ resetRemembered: true }) | 清除「国内域名提示」的「不再显示」记忆 |
本地调试 API
接口默认直连 https://api.hayfrp.1zyq1.com(不是本地代理),因此本地开发时请求会真实打到线上。若需联调后端,可临时修改 src/services/api.ts 的 API_ENDPOINTS,或自行在 vite.config.ts 增加 server.proxy。
构建产物
dist/
├── index.html
├── assets/
│ ├── css/… # cssCodeSplit 后的样式
│ ├── js/…
│ └── … # assets/[ext]/[name]-[hash][extname]
├── sw.js # PWA Service Worker(vite-plugin-pwa)
├── workbox-*.js
└── favicon.ico / logo.png / robots.txt / sitemap.xml- 生产构建使用
terser,drop_console: true、drop_debugger: true→ 线上无console输出 - 手动分包:
vue-vendor、naive-ui、utils - PWA 使用
autoUpdate(skipWaiting+clientsClaim+cleanupOutdatedCaches)
部署
Nginx
nginx
server {
listen 443 ssl http2;
server_name console.example.com;
root /var/www/hayfrp-console/dist;
index index.html;
# SPA history 路由回退
location / {
try_files $uri $uri/ /index.html;
}
# Service Worker 不缓存
location = /sw.js {
add_header Cache-Control "no-cache";
}
location /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}Cloudflare Pages
| 配置项 | 值 |
|---|---|
| Build command | npm run build |
| Build output directory | dist |
| Node 版本 | 18+ |
仓库根目录的
_routes.json已为 Cloudflare 的 SPA 路由准备。
常见问题
| 问题 | 排查方向 |
|---|---|
| 端口 3000 被占用 | 换端口启动,或结束占用进程 |
| 依赖安装失败 | 删除 node_modules 后重新 npm install,不要混用 npm / pnpm |
构建报 TS6133(声明未使用) | noUnusedLocals 生效,删除或使用该变量 / 参数 |
| 接口 403 / Token 无效 | Token 7 天过期,重新登录;或 keepcsrf=false 导致旧 Token 失效 |
| 样式不生效 | 检查 <style scoped> 与全局 main.css 的 class 钩子(html.dark、body.compact-mode) |
| 页面白屏 | 查看控制台是否有 401 跳转、PWA 旧缓存(尝试硬刷新 / 清理 Service Worker) |
| 启动器授权失败 | 确认启动器在运行、本地端口 21100 未被占用 |