全栈开发者 / 技术博主的个人博客前端。基于 Vue 3 + TypeScript + Vite + Pinia 构建,配套后端 API 服务
api.mayekun.com。
🌐 在线地址:https://mayekun.com
💻 代码仓库:https://github.com/eonsee/k-ui
🛠 技术栈:Vue 3 · TypeScript · Vite 5 · Pinia · Vue Router 4 · Axios · TailwindCSS
- 项目简介
- 核心功能
- 技术栈
- 项目结构
- 环境配置
- 快速开始
- 路由与页面
- 状态管理 (Pinia)
- 核心组件
- API 请求封装
- 特色功能详解
- SEO 与部署
- 开发约定
- 待优化项 / Known Issues
- License
k-ui 是博客 mayekun.com 的前端工程,承载个人主页、文章系统、作品集、关于页等功能。
- 🎨 设计风格:现代简约、毛玻璃质感、响应式布局(桌面 / 平板 / 手机)
- 🌗 暗色模式:跟随系统 / 手动切换
- 🇨🇳 中文界面:本土化文案与设计
- ⚡ 性能优先:路由懒加载、Vite 构建、相对路径代理避免 CORS
| 模块 | 功能点 |
|---|---|
| 首页 | 个人简介、真实数据统计、作品封面轮播、文章列表(最新 6 篇) |
| 文章列表 | 分类筛选、关键词搜索、分页、活跃度热力图、敲木鱼功德互动 |
| 文章详情 | Markdown 渲染、代码高亮、文章目录 (TOC)、自动滚动阅读、悬浮音乐播放器 |
| 作品集 | 分类筛选、脑力点位图(左侧点位网络 + 右侧详情卡片)、成长轨迹时间轴 |
| 关于页 | 个人介绍、技能图谱、二维码、成长故事 |
| 通用 | 顶部导航(主题切换、GitHub / Gitee)、底部社交信息、QQ 二维码、备案号、运行天数实时统计 |
- Vue 3.4 —— Composition API +
<script setup> - TypeScript 5.3 —— 全量类型约束
- Vite 5 —— 构建工具 + Dev Server
- Pinia 2 —— 状态管理
- Vue Router 4 —— SPA 路由
- TailwindCSS 3 + less —— 样式
- lucide-vue-next —— 图标库
- markdown-it + highlight.js —— Markdown 渲染与代码高亮
- ant-design-vue —— 部分交互组件(如有)
- clsx + tailwind-merge —— class 合并工具
- axios —— 请求库,统一封装在
src/api/request.ts
k-ui/
├── public/ # 静态资源(直接拷贝到 dist 根目录)
│ ├── favicon.png / favicon.svg # 网站图标
│ ├── my.jpg # og:image 社交分享图
│ ├── qr-qq.png / qr-wechat.png # 联系方式二维码
│ └── ...
├── src/
│ ├── api/ # 接口请求层
│ │ ├── request.ts # axios 实例与拦截器
│ │ ├── article.ts # 文章相关 API
│ │ ├── category.ts # 分类 API
│ │ ├── work.ts # 作品 API
│ │ ├── profile.ts # 个人简介 API
│ │ ├── growth.ts # 成长时间轴 API
│ │ └── skill.ts # 技能 API
│ ├── assets/ # 业务图片资源
│ ├── components/
│ │ ├── article/ # 文章相关组件
│ │ │ ├── ArticleCard.vue # 文章卡片
│ │ │ ├── ActivityHeatmap.vue # 文章活跃度热力图(固定夏季配色)
│ │ │ ├── IPCard.vue # 访客 IP 卡片(已停用)
│ │ │ ├── IPDetailCard.vue # 访客 IP 详情卡片(已停用)
│ │ │ ├── WoodenFish.vue # 敲木鱼互动(功德计数)
│ │ │ ├── ArticleToc.vue # 文章目录
│ │ │ ├── AutoReader.vue # 自动滚动阅读
│ │ │ ├── FloatingMusicPlayer.vue / MusicPlayer.vue
│ │ │ └── SeasonTree.vue # 四季树(历史遗留)
│ │ ├── layout/ # 布局组件
│ │ │ ├── AppHeader.vue # 顶部导航(主题、GitHub / Gitee)
│ │ │ └── AppFooter.vue # 底部信息(社交、QQ 二维码、备案)
│ │ ├── work/WorkCard.vue # 作品卡片(备用,未启用)
│ │ ├── home/StatsChart.vue # 首页统计图表(已停用)
│ │ └── common/Couplet.vue # 春联动画(已停用)
│ ├── composables/
│ │ └── useTheme.ts # 主题切换逻辑
│ ├── lib/utils.ts # 通用工具函数
│ ├── mock/data.ts # 本地 mock 数据(接口异常时降级)
│ ├── router/index.ts # 路由配置
│ ├── store/index.ts # Pinia 主仓库(含二十四节气配置)
│ ├── types/index.ts # 全局类型定义
│ ├── views/ # 页面
│ │ ├── Home.vue # 首页
│ │ ├── Articles.vue # 文章列表
│ │ ├── ArticleDetail.vue # 文章详情
│ │ ├── Works.vue # 作品集
│ │ └── About.vue # 关于
│ ├── App.vue / main.ts
│ └── style.css # 全局样式 + Tailwind 入口
├── database/ # 后端相关(参考用)
│ ├── mayekun_blog.sql # 数据库初始化脚本
│ └── deploy-guide.md # 后端部署文档
├── .trae/documents/ # 项目 PRD 与技术架构文档
│ ├── prd.md
│ └── tech-architecture.md
├── docs/images/home.png # README 预览图
├── .env / .env.development / .env.production
├── index.html # HTML 模板(含 SEO meta)
├── tailwind.config.js / postcss.config.js
├── tsconfig.json
├── vite.config.ts # Vite 配置(含 /admin, /upload 代理)
└── package.json
通过 .env.* 文件管理环境变量,必须使用相对路径,避免 CORS:
VITE_API_BASE_URL=/admin # 通过 Vite proxy 转发
VITE_UPLOAD_URL=
VITE_PROXY_TARGET=http://api.mayekun.comVITE_API_BASE_URL=/admin # 走 Nginx 同域代理
VITE_UPLOAD_URL=开发环境启动 npm run dev 时,Vite 会代理:
/admin/*→http://api.mayekun.com(业务接口)/upload/*→http://api.mayekun.com(静态资源)
⚠️ 不要直接写绝对地址(如http://api.mayekun.com),会触发 CORS 跨域错误。
# 1. 安装依赖
npm install
# 2. 启动开发服务
npm run dev # 默认 http://localhost:5173
# 3. 类型检查
npm run check
# 4. 生产构建
npm run build # 输出到 dist/
# 5. 本地预览构建产物
npm run preview
# 6. 代码风格
npm run lint
npm run lint:fix| 路径 | 名称 | 页面 | 说明 |
|---|---|---|---|
/ |
home | Home.vue |
首页 |
/articles |
articles | Articles.vue |
文章列表(含热力图 + 敲木鱼) |
/article/:id |
article-detail | ArticleDetail.vue |
文章详情(Markdown) |
/works |
works | Works.vue |
作品集(脑力点位图) |
/about |
about | About.vue |
关于我 |
路由守卫会自动设置 document.title。
主仓库 src/store/index.ts 集中管理所有业务数据:
- 文章:
articles、articleCategories、heatMapData、fetchArticles()、fetchCategories()、fetchHeatMapData() - 作品:
works、workCategories、filteredWorks、fetchWorks() - 个人信息:
profile、fetchProfile() - 技能:
skills、fetchSkills() - 成长时间轴:
growthTimeline、fetchGrowthTimeline() - 热力图模式:
heatmapMode(season/solar)、currentSeason(固定summer)、currentSolarTerm - 筛选状态:
searchQuery、currentArticleCategory、currentWorkCategory
SOLAR_TERMS—— 24 节气配置(含名称、月份、日期、主题色、物候描述)HeatmapMode/SolarTermKey—— 类型导出
- 365 天网格热力图,按文章发布数量上色
- 固定使用夏季青蓝色阶,已关闭四季切换与按月份自动推断季节
- 顶部的四季切换按钮已移除
- 位置:文章列表页右侧(与热力图并排)
- 点击木鱼累计「功德」,带音效与敲击动效
- 原
IPCard.vue/IPDetailCard.vue访客 IP 卡片已停用
- 左侧散布的彩色点位代表作品(按索引分配 18 色调色板)
- 不足 10 个作品时用模拟点补足(视觉上"待解锁")
- 同分类点位用虚线连接,形成"脑力网络"
- 点击点位 → 右侧详情卡片显示封面、描述、标签、链接
- 顶部 SVG 曲线成长时间轴,含"成长轨迹 / 每一步都算数"端点文字
- 站点标语与社交入口(GitHub / Twitter / Email)
- QQ 二维码
- 工信部备案号(带 logo)
- 网站运行天数与访问量(每分钟实时更新,跨午夜自动 +1)
- 版权信息 + ICP 备案
- Markdown 渲染(markdown-it)+ 代码高亮(highlight.js)
- 右侧悬浮目录 (TOC) + 自动滚动阅读
- 悬浮音乐播放器
所有请求统一通过 src/api/request.ts:
// 基础实例
const service = axios.create({
baseURL: import.meta.env.VITE_API_BASE_URL, // /admin
timeout: 15000
})
// 请求拦截器:附加 token
// 响应拦截器:统一错误处理、业务码校验| 文件 | 说明 |
|---|---|
article.ts |
文章分页查询、热力图、详情 |
category.ts |
分类列表(type=1 文章 / 2 作品) |
work.ts |
作品列表、详情 |
profile.ts |
个人简介 |
skill.ts |
技能图谱 |
growth.ts |
成长时间轴 |
- 全站主色固定为夏季青蓝
#06b6d4,通过html[data-season='summer']的 CSS 变量生效 index.html初始即标记data-season="summer",避免首屏闪出其他季节的颜色- 已关闭随四季自动切换,热力图也不再提供季节切换按钮
store/index.ts中的SOLAR_TERMS二十四节气配置保留备用
- 位置算法:黄金角分布(
Math.PI * (3 - Math.sqrt(5))),点位均匀散布在圆形区域 - 连线:同分类点位之间画虚线,hover/active 时变实线
- 模拟点:真实作品不足 10 个时用淡色"待解锁"占位(不可点击)
- 误触防护:点位 button 尺寸固定为圆点大小(12px),标签用绝对定位避免扩大可点击区域
- viewBox
0 0 1200 120,沿水平方向 4 段贝塞尔曲线 - 渐变描边(蓝 → 紫 → 青),含模糊滤镜发光效果
- 端点文字"成长轨迹 / 每一步都算数"固定在画布左右两端
index.html配置 og:image / og:title / og:description- 建议 og:image 至少 200×200(实际使用
my.jpg1200×630) - 百度搜索资源平台验证站点可显示中文站名
用户 → mayekun.com (Nginx)
├── 静态资源 → /usr/share/nginx/html
├── /admin/* → proxy_pass http://api.mayekun.com
└── /upload/* → proxy_pass http://api.mayekun.com
Nginx 关键配置(mayekun.com):
location /admin/ {
proxy_pass http://api.mayekun.com;
proxy_set_header Host api.mayekun.com;
proxy_connect_timeout 60s;
proxy_read_timeout 120s;
}
location /upload/ {
proxy_pass http://api.mayekun.com;
}Nginx 关键配置(api.mayekun.com):
location / {
add_header 'Access-Control-Allow-Origin' '*' always;
# ... 业务转发
}npm run build # 生成 dist/
# 上传 dist 全部内容到 mayekun.com 服务器的 /usr/share/nginx/html/
# 确保 Nginx 配置正确- Vue 3 Composition API:所有组件使用
<script setup lang="ts"> - TypeScript 严格模式:避免
any,所有数据结构在types/index.ts定义 - CSS 变量主题:通过
var(--xxx)引用,支持暗色模式自动切换 - 路径别名:
@/→src/ - 样式作用域:组件样式使用
<style scoped> - 响应式单位:rem / em / vw,固定值用 px
@media (max-width: 1024px) { /* 平板 */ }
@media (max-width: 768px) { /* 手机 */ }
@media (max-width: 480px) { /* 小屏手机 */ }- 访客 IP 卡片(
IPCard.vue/IPDetailCard.vue)因外部接口 CORS 限制已停用,文章页改用敲木鱼互动 - 移动端脑力点位图点位标签已隐藏(
@media max-width: 768px),但仍可点击 - 文章热力图 365 天格子在超窄屏(< 360px)下可能略拥挤
-
WorkCard.vue已被新脑力点位图替代但文件保留,可清理
MIT © 马业坤
🌟 如果觉得项目对你有帮助,欢迎 Star 一下!
