15 KiB
15 KiB
技术选型与架构方案
1. 决策概览
1.1 技术栈选型
| 层级 | 技术选择 | 备选方案 | 决策理由 |
|---|---|---|---|
| 静态生成器 | Hugo | Zola, Astro | 极速构建、成熟生态、Go模板 |
| 主题框架 | 自定义 | PaperMod, Stack | 完全可控、符合品牌调性 |
| 样式方案 | Tailwind CSS + 自定义CSS | SCSS/BEM | 原子化优先、暗色模式友好 |
| 搜索 | Fuse.js (客户端) | Pagefind, Algolia | 零后端、轻量、隐私优先 |
| 部署 | GitHub Pages + GitHub Actions | Vercel, Netlify | 简单免费、版本联动 |
| CMS(可选) | 本地Markdown | Decap CMS | 纯文本优先、Git版本控制 |
1.2 架构原则
┌─────────────────────────────────────────────────────────────┐
│ 架构决策原则 │
├─────────────────────────────────────────────────────────────┤
│ 1. 静态优先 → 零运行时依赖，最大可靠性 │
│ 2. 渐进增强 → 核心内容无JS亦可访问 │
│ 3. 内容即数据 → Frontmatter驱动，结构化优先 │
│ 4. 工具链极简 → 单一二进制(Hugo)，减少依赖 │
│ 5. 版本控制 → Git为中心，内容+代码统一 │
└─────────────────────────────────────────────────────────────┘
2. 系统架构
2.1 整体架构图
┌─────────────────────────────────────────────────────────────────────┐
│ 内容生产层 (Content Layer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Markdown │ │ Frontmatter │ │ Assets │ │
│ │ 正文 │ │ 元数据 │ │ 图片/附件 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼─────────────────┼─────────────────┼──────────────────────┘
│ │ │
└─────────────────┼─────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 构建层 (Build Layer) │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ Hugo Static Generator │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ 内容解析 │→ │ 模板渲染 │→ │ 搜索索引 │→ │ 资源优化 │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 输出层 (Output Layer) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ HTML │ │ CSS/JS │ │ Images │ │ RSS/JSON│ │
│ │ 页面 │ │ 样式 │ │ 资源 │ │ Feed │ │
│ └────┬─────┘ └──────────┘ └──────────┘ └──────────┘ │
└───────┼─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 部署层 (Deploy Layer) │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ GitHub Pages (CDN + HTTPS) │ │
│ └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
2.2 项目目录结构
val-blog/
├── archetypes/ # 内容模板
│ ├── journey.md # 旅程记录模板
│ ├── sketch.md # 速记模板
│ ├── gallery.md # 图志模板
│ └── essay.md # 深度文模板
├── assets/ # 需处理的资源
│ ├── css/
│ │ ├── main.css # 主样式
│ │ ├── dark.css # 暗色模式
│ │ └── components/ # 组件样式
│ ├── js/
│ │ ├── search.js # 搜索功能
│ │ ├── theme.js # 主题切换
│ │ └── gallery.js # 图片画廊
│ └── images/
│ └── logo.svg
├── config.toml # 站点配置
├── content/ # 内容目录
│ ├── _index.md # 首页
│ ├── about.md # 关于页面
│ ├── journey/ # 旅程记录
│ ├── sketch/ # 速记
│ ├── gallery/ # 图志
│ ├── essay/ # 深度文
│ └── series/ # 系列文章
├── data/ # 数据文件
│ └── navigation.yaml
├── layouts/ # 模板
│ ├── _default/
│ │ ├── baseof.html # 基础模板
│ │ ├── list.html # 列表页
│ │ └── single.html # 单页
│ ├── index.html # 首页模板
│ ├── partials/ # 模板片段
│ │ ├── head.html
│ │ ├── header.html
│ │ ├── footer.html
│ │ ├── navigation.html
│ │ ├── search.html
│ │ ├── theme-toggle.html
│ │ └── pagination.html
│ └── shortcodes/ # 短代码
│ ├── gallery.html
│ ├── timeline.html
│ └── map.html
├── static/ # 静态文件
│ ├── fonts/
│ ├── images/
│ ├── favicon.ico
│ └── robots.txt
└── themes/ # 主题目录（如使用子主题）
3. 功能模块设计
3.1 功能矩阵
| 功能 | 优先级 | 技术方案 | 状态 |
|---|---|---|---|
| 响应式布局 | P0 | Tailwind CSS | 待实现 |
| 暗色模式 | P0 | CSS变量 + localStorage | 待实现 |
| 中文排版优化 | P0 | typo.css + 自定义 | 待实现 |
| 全文搜索 | P0 | Fuse.js + 索引构建 | 待实现 |
| 标签系统 | P0 | Hugo Taxonomies | 待实现 |
| 时间线视图 | P0 | 自定义模板 | 待实现 |
| RSS/Atom | P0 | Hugo内置 | 待实现 |
| JSON Feed | P1 | 自定义模板 | 待实现 |
| 图片画廊 | P1 | 轻量JS + CSS Grid | 待实现 |
| 文章系列 | P1 | Hugo Sections | 待实现 |
| 阅读时间 | P1 | Hugo内置/自定义 | 待实现 |
| 目录导航 | P1 | 自动生成TOC | 待实现 |
| 相关文章 | P2 | 标签匹配 | 待实现 |
| 阅读进度 | P2 | CSS/JS | 待实现 |
| 代码高亮 | P2 | Prism.js/Chroma | 待实现 |
| PWA支持 | P2 | Service Worker | 待实现 |
| 评论系统 | P3 | Giscus(Utterances) | 待实现 |
| Newsletter | P3 | 第三方服务 | 待实现 |
3.2 暗色模式实现
/* CSS变量定义 */
:root {
/* 浅色模式 */
--bg-primary: #F7F5F0;
--bg-secondary: #FFFFFF;
--text-primary: #2D3E50;
--text-secondary: #5A6A7A;
--accent: #C9A961;
--border: #E5E1D8;
}
[data-theme="dark"] {
/* 暗色模式 */
--bg-primary: #1A1F2B;
--bg-secondary: #232936;
--text-primary: #D4D4D4;
--text-secondary: #8A94A6;
--accent: #D4B86A;
--border: #3A4150;
}
/* 系统偏好检测 */
@media (prefers-color-scheme: dark) {
:root:not([data-theme]) {
/* 暗色变量 */
}
}
3.3 搜索架构
┌──────────────────────────────────────────────────────┐
│ 搜索实现方案 │
├──────────────────────────────────────────────────────┤
│ 构建时: │
│ └── Hugo模板生成 search-index.json │
│ ├── title │
│ ├── content (摘要) │
│ ├── tags │
│ ├── date │
│ └── permalink │
│ │
│ 运行时: │
│ ├── 页面加载时异步获取 search-index.json │
│ ├── Fuse.js 初始化索引 │
│ ├── 输入时实时搜索 │
│ └── 结果渲染 (标题+摘要+高亮) │
│ │
│ 优化: │
│ ├── 索引分片 (按年份/类型) │
│ ├── 防抖 (300ms) │
│ └── 缓存至 sessionStorage │
└──────────────────────────────────────────────────────┘
4. 内容模型
4.1 Frontmatter规范
---
# 基础信息
标题相关
title: "文章标题"
subtitle: "副标题（可选）"
# 分类与标签
categories: ["journey"] # journey/sketch/gallery/essay
tags: ["异世界", "魔法森林", "水晶洞穴"]
series: "魔法大陆纪行" # 系列名称（可选）
series_order: 1 # 系列中的顺序
# 时间与状态
date: 2026-03-09T21:00:00+08:00
lastmod: 2026-03-09T22:30:00+08:00
draft: false
featured: false # 是否精选
# 元数据
author: "Val"
location: "翡翠森林·北境" # 故事发生地
world: "Aethoria" # 世界观/宇宙名称
# 媒体
cover:
image: "/images/covers/forest-crystal.jpg"
alt: "水晶洞穴内部"
caption: "微弱的蓝光来自洞顶的水晶"
gallery: # 图志专用
- src: "/images/gallery/forest-01.jpg"
alt: "森林入口"
- src: "/images/gallery/forest-02.jpg"
alt: "水晶洞穴"
# SEO
description: "在翡翠森林深处发现的水晶洞穴"
keywords: ["奇幻", "探险", "水晶洞穴"]
# 交互
comments: true
toc: true # 是否显示目录
reading_time: true # 是否显示阅读时间
---
4.2 内容类型定义
| 类型 | 目录 | 模板 | 特殊字段 |
|---|---|---|---|
| 旅程记录 | /journey/ |
journey/single.html |
location, route, timeline |
| 速记 | /sketch/ |
sketch/single.html |
mood, weather, time_of_day |
| 图志 | /gallery/ |
gallery/single.html |
gallery[], location |
| 深度文 | /essay/ |
essay/single.html |
abstract, references |
5. 部署方案
5.1 GitHub Actions工作流
# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
submodules: true
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: '0.123.0'
extended: true
- name: Build
run: hugo --minify
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./public
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy
id: deployment
uses: actions/deploy-pages@v4
5.2 本地开发流程
# 1. 安装Hugo (macOS)
brew install hugo
# 2. 克隆项目
git clone <repo> val-blog
cd val-blog
# 3. 启动开发服务器
hugo server -D --bind 0.0.0.0
# 4. 创建新内容
hugo new content journey/2026/crystal-cave.md
# 5. 构建 (生产)
hugo --minify
6. 性能预算
| 指标 | 目标 | 最大允许 |
|---|---|---|
| 首屏加载时间 | < 1.0s | 1.5s |
| 可交互时间 | < 1.5s | 2.0s |
| 首页总大小 | < 200KB | 300KB |
| 单页总大小 | < 150KB | 250KB |
| 搜索索引 | < 500KB | 1MB |
| Lighthouse分数 | > 90 | 80 |
7. 变更记录
| 版本 | 日期 | 变更内容 | 作者 |
|---|---|---|---|
| v0.1.0 | 2026-03-09 | 初稿创建 | Val |