99 lines
4.7 KiB
Markdown
99 lines
4.7 KiB
Markdown
# 🍊 柚子博客 · 前端
|
||
|
||
暖色玻璃拟态风格的个人博客前端（Vue 3 + TypeScript + Vite 7），配套后端 API 为 `https://www.hxyouzi.com/api`。
|
||
|
||
> 项目标语：**重新起航**
|
||
|
||
## ✨ 功能特性
|
||
|
||
- 📰 **博客模块**：文章列表、分类筛选、文章详情阅读（`md-editor-v3` 渲染）
|
||
- 🧭 **导航主页**：搜索式导航首页，支持快捷搜索、站点导航增删改、右侧卡片/侧栏
|
||
- 🖼️ **画廊 / 图床**：文件资源浏览、搜索、分享（瀑布流 + 懒加载）
|
||
- 🔗 **友链**：友情链接展示与申请添加
|
||
- 🌤️ **天气 / 生活**：IP 定位、天气查询、每日一言、热榜、节假日（防御式处理）
|
||
- 🎵 **音乐播放**：基于 APlayer + Meting 的音乐播放器
|
||
- 👤 **用户体系**：登录 / 注册 / 自动登录（JWT，cookie 持久化）
|
||
- 🗂️ **其他页面**：小工具（Widget）、应用（Apps）等
|
||
|
||
## 🛠️ 技术栈
|
||
|
||
| 分类 | 技术 |
|
||
| --------- | ---------------------------------------------------------- |
|
||
| 核心框架 | Vue 3、TypeScript、Vite 7、Vue Router 5 |
|
||
| UI 组件库 | naive-ui（自动按需注册）、vue-devui（Tag） |
|
||
| 样式方案 | UnoCSS（重度 arbitrary values）、Less（全局注入主色变量） |
|
||
| 状态管理 | Pinia（`nav` / `log` stores） |
|
||
| 网络请求 | Axios（拦截器自动带 Bearer token） |
|
||
| Markdown | md-editor-v3 |
|
||
| 音频 | aplayer + @meting/core |
|
||
| 其他 | pinia、vue3-cookies、nprogress、es-toolkit、qweather-icons |
|
||
|
||
## 🚀 快速开始
|
||
|
||
环境要求：Node.js `^20.19.0 || >=22.12.0`
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器（端口 8989，路径 base /blog/，首页 /home）
|
||
npm run dev
|
||
|
||
# 类型检查（改完代码必跑）
|
||
npm run type-check
|
||
|
||
# 构建（type-check + build）
|
||
npm run b
|
||
|
||
# 仅构建
|
||
npm run build-only
|
||
```
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
src/
|
||
├── api/ # API 模块（自动挂载到 $http.<模块>.<函数>）
|
||
├── assets/ # 全局样式、字体、图片
|
||
├── components/ # 通用组件（自动注册，如 Gallery、Login、aplayer 等）
|
||
├── config/ # 全局配置（自动挂载 $http/$store/$cookies 等）
|
||
├── icon/ # SVG 图标（顶层自动注册为 <icon-<name> />）
|
||
├── lib/ # 内部组件库（Waterfall、LazyImg 及工具）
|
||
├── logo/ # 站点 logo 图
|
||
├── router/ # 路由（文件系统路由 + NProgress 守卫）
|
||
├── stores/ # Pinia stores（nav / log）
|
||
├── util/ # 请求封装、工具函数、主题配置
|
||
└── views/ # 页面（unplugin-vue-router 文件系统路由）
|
||
```
|
||
|
||
## 🔗 全局约定（使用前必读）
|
||
|
||
项目大量使用**全局变量与自动导入**，使用时**无需重复 import**（类型声明见 `env.d.ts`）：
|
||
|
||
| 全局变量 | 说明 |
|
||
| ---------- | ------------------------------------------------------------------------- |
|
||
| `$http` | API 聚合对象：`$http.<模块>.<函数>()`（如 `$http.blog.getBlogList`） |
|
||
| `$store` | Pinia store 聚合：`$store.nav.useNavStore()` / `$store.log.useLogStore()` |
|
||
| `$msg` | naive-ui message 实例：`$msg.success/warning/error/info` |
|
||
| `$cookies` | vue3-cookies 封装：`get/set/remove` |
|
||
| `$modal` | 全局弹窗：`$modal({ title, content, contType: 'text'\|'input', ... })` |
|
||
|
||
- **组合式 API** 已自动导入（`ref`/`computed`/`watch`/`useRoute`/`defineStore`/`useMessage` 等）。
|
||
- `src/components/` 组件与 naive-ui `<n-xxx>` 均自动注册，模板中直接使用。
|
||
- **新增 icon / api / store 文件后需重启 dev server**（`import.meta.glob` 构建时静态分析）。
|
||
- 登录态：cookie `userinfo` 存在即视为已登录。
|
||
|
||
## 🎨 设计规范
|
||
|
||
- **主色调**：暖色玻璃拟态，主色 `#ec66ab`（Less 变量 `@primary`）、主题按钮色 `#D71A44`
|
||
- **背景模板**：暖色径向渐变 + 两个 blur 圆 + 网格 overlay（参考 `src/views/index.vue` 顶部）
|
||
- **阴影规范**：三层体系（接触 + 主体 + 暖色高光 + inset 高光），避免纯冷灰阴影
|
||
- **字体**：霞鹜文楷（正文）+ Fira Code（代码）
|
||
- **页面布局**：统一减去导航栏高度（`$store.nav.useNavStore().navH`）
|
||
|
||
> 详细开发约定与常见陷阱见仓库根目录 `AGENTS.md`。
|
||
|
||
## 📄 License
|
||
|
||
本项目为个人项目，遵循 MIT License（以仓库实际声明为准）。
|