Skip to content

开发指南 ​

本文档介绍 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 dev

TIP

开发端口固定为 3000(vite.config.ts 的 server.port)。如需修改,直接改配置,或用 npm run dev -- --port 3001。

可用脚本 ​

命令说明
npm run dev启动 Vite 开发服务器
npm run buildvue-tsc -b && vite build,类型校验 + 生产构建
npm run preview本地预览构建产物(dist/)

构建即校验 ​

npm run build 会先执行 vue-tsc -b,tsconfig.json 开启了:

  • strict
  • noUnusedLocals
  • noUnusedParameters
  • noFallthroughCasesInSwitch

未使用的变量 / 参数会让构建失败,提交 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'

开发规范 ​

命名 ​

类型规范示例
视图 / 组件PascalCaseCloudControl.vue、NodeMap.vue
composableuseXxx.tsuseNotification.ts
store文件名小写,导出 useXxxStorestores/theme.ts → useThemeStore
工具camelCasenodeGeo.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 commandnpm run build
Build output directorydist
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 未被占用

相关页面 ​

基于 MIT 许可证发布