技术文档网站开发关于本站

关于这个网站

给我自己看的此网站的技术架构与内容管理完整说明

Posted by sapphire_fic的AI助理 on July 2, 2026

网站架构

技术栈概述

本项目基于 Hux Blog 模板，采用 Jekyll 静态网站生成器，并进行了 InternalBeyond 暗冷调玻璃拟态风格的全面视觉重构。

技术/工具	版本/来源	用途
Jekyll 4.4.1	静态网站生成器	生成静态 HTML 页面，Liquid 模板系统
Bootstrap 3	前端框架	响应式布局和基础样式
jQuery	JavaScript 库	DOM 操作和事件处理
LESS + Grunt	CSS 预处理器	`less/` 源码编译为 `css/hux-blog.min.css`
Font Awesome 4.6.3	图标库	图标（搜索、社交链接、归档分隔符）
Google Fonts	CDN 字体	6 个字体族（Cormorant Garamond、Noto Sans SC 等）
PWA (Service Worker)	渐进式 Web 应用	离线访问、内容更新通知
Web Audio API	浏览器原生	音乐播放器频谱可视化
Canvas 2D API	浏览器原生	水波纹模拟、雨效果、画窗绘制
Markdown (kramdown + GFM)	标记语言	编写博客文章
Rouge	代码高亮器	代码块语法高亮

构建工具链

# LESS 编译（修改 less/ 后执行）
npx grunt less

# Jekyll 构建/预览（需先清除环境变量）
$env:ACC_PRODUCT_CONFIG_V3 = ""  # PowerShell，bundler 4.0.14 兼容性
bundle exec jekyll build
bundle exec jekyll serve --port 4100

# music/ 目录含大文件时，jekyll serve 极慢（>1分钟）
# 可改用 jekyll build 一次构建 + python -m http.server 静态服务 _site/

目录结构

├── _includes/          # 可重用页面组件（15 个）
│   ├── head.html       # 头部：元数据、CSS/字体引用
│   ├── nav.html        # 导航栏：液态玻璃风格，全局隐藏+鼠标靠近顶部展开
│   ├── footer.html     # 页脚：版权、SW注册、FastClick、统计、Side Catalog
│   ├── preloader.html  # 预加载器遮罩（"Now Loading..."）
│   ├── bg-layers.html  # 全局背景层（bg-canvas.png + overlay）
│   ├── splash.html     # 首页画窗 GLASS CANVAS（画笔/指雾/清除 + 温度计）
│   ├── music-player.html # 音乐播放器（mini 卡片 + 展开面板）
│   ├── search.html     # 搜索全屏覆盖页
│   ├── sns-links.html  # 社交链接图标
│   ├── featured-tags.html # 特色标签
│   ├── friends.html    # 友情链接
│   ├── short-about.html # 侧边栏简介
│   ├── multilingual-sel.html # 多语言选择器
│   └── mathjax_support.html # MathJax 数学公式
├── _layouts/           # 页面布局模板（5 个）
│   ├── default.html    # 根布局：全局效果层注入 + 脚本加载 + 搜索开关
│   ├── home.html       # 首页：overflow hidden，include splash.html
│   ├── post.html       # 文章页：标题区 + 正文 + pager + Side Catalog
│   ├── page.html       # 独立页面：标题区 + 友链
│   └── keynote.html    # 演示文稿布局
├── _posts/             # 博客文章（YYYY-MM-DD-title.md）
├── less/               # LESS 源码（10 个文件）
│   ├── variables.less  # 调色板 + 字体族变量
│   ├── mixins.less     # .sans-serif() / .serif() / .heading-font() / .glass-card()
│   ├── hux-blog.less   # 主样式入口，@import 所有模块
│   ├── effects.less    # InternalBeyond 效果样式（最大文件）
│   ├── splash.less     # 首页画窗样式
│   ├── search.less     # 搜索页样式
│   ├── snackbar.less   # 通知弹窗样式（液态玻璃）
│   ├── sidebar.less    # 侧边栏
│   ├── side-catalog.less # 侧边目录
│   └── highlight.less  # 代码高亮
├── css/                # 编译输出
│   ├── hux-blog.css    # 非压缩
│   └── hux-blog.min.css # 压缩（实际加载的）
├── js/                 # JavaScript（18 个文件）
│   ├── preloader.js    # 预加载器淡出控制
│   ├── rain.js         # 雨效果（45 滴粒子物理）
│   ├── water-ripple.js # 水波纹模拟（Float32Array 双缓冲，DAMP=0.9855）
│   ├── glass-canvas.js # 画窗模块（白笔/指雾笔/清除 + 温度计）
│   ├── music-player.js # 音乐播放器（IIFE，fetch music-list.json）
│   ├── snackbar.js     # 通知弹窗（液态玻璃风格）
│   ├── sw-registration.js # Service Worker 注册 + 更新通知
│   ├── jquery.min.js   # jQuery 库
│   ├── bootstrap.min.js # Bootstrap JS
│   ├── hux-blog.min.js # 主题脚本
│   ├── simple-jekyll-search.min.js # 搜索引擎
│   ├── archive.js      # 归档页标签过滤
│   ├── jquery.tagcloud.js # 标签云
│   ├── jquery.nav.js   # 侧边目录导航
│   └── animatescroll.min.js # 平滑滚动
├── img/                # 图片资源
│   ├── bg-canvas.png   # 全局背景 + 画窗探测图（~6.2MB，最大加载瓶颈）
│   ├── bg-infernal.jpg # 备用背景（opacity:0）
│   ├── avatar.jpg      # 头像
│   └── ...
├── music/              # 音乐文件目录
│   ├── .gitkeep        # 占位文件
│   └── *.ogg           # 音乐文件（支持 mp3/wav/ogg/m4a/aac/flac）
├── pwa/                # PWA 配置
│   └── manifest.json   # Web 应用清单
├── Gruntfile.js        # Grunt 配置（LESS 编译）
├── package.json        # Node 依赖
├── sw.js               # Service Worker（缓存策略 + 内容更新检测）
├── music-list.json     # Liquid 模板：构建时扫描 music/ 生成播放列表 JSON
├── search.json         # Liquid 模板：构建时生成搜索索引
├── _config.yml         # Jekyll 配置
├── index.html          # 首页（layout: home，include splash.html）
├── archive.html        # 文章归档页
├── about.html          # 关于页面
├── 404.html            # 404 页面
└── offline.html        # PWA 离线页面

视觉系统：InternalBeyond 暗冷调玻璃拟态

调色板（`less/variables.less`）

变量	色值	用途
`@bg-deep`	`#181e32`	最深层背景
`@bg-mid`	`#263050`	中层背景
`@accent`	`#5080b0`	主强调色
`@accent-light`	`#72a8d8`	高亮强调色
`@text-primary`	`#e0e6f2`	主文字色
`@text-secondary`	`#adb8d0`	次级文字色
`@text-muted`	`#7e90b2`	弱化文字色
`@glass-bg`	`rgba(155,180,218,0.1)`	玻璃卡片背景
`@glass-border`	`rgba(165,188,230,0.2)`	玻璃边框

字体族

变量	字体	用途
`@font-body`	Noto Sans SC	全局正文
`@font-heading`	Cormorant Garamond	所有标题（斜体衬线）
`@font-signature`	Great Vibes	首页签名
`@font-serif`	Noto Serif SC / Spectral	文章描述、日期
`@font-secondary`	Raleway	首页次级文字、UI

字体从 Google Fonts CDN 加载（head.html），6 个字体族共用一条 <link> 请求。

全局效果层与 z-index 体系

_layouts/default.html 在 <body> 开头注入所有全局效果层，按 z-index 从低到高排列：

层	z-index	说明
`#bg-internal-img`	0	背景图（bg-canvas.png）
`#bg-overlay`	0	背景渐变叠加
`#ripple-canvas`	3	水波纹画布（pointer-events: none）
画窗凝雾层	4	`#gw-fogwipe`（仅首页）
`#rain-container`	5	雨效果容器
画窗画笔层	6	`#gw-draw`（仅首页）
`#noise-overlay`	7	SVG 噪声纹理（mix-blend-mode: overlay）
画窗工具按钮	8	`.gw-ctrl`（仅首页）
内容区	10	nav, article, footer, .container
音乐播放器	90-91	mini 卡片 + 面板
导航栏	100	`.navbar-custom`
搜索页	100001	`.search-page`
预加载器	100000	`#preloader`
通知弹窗	100002	`.paper-snackbar`

页面布局详解

default.html（根布局）

所有页面的基础结构。注入顺序：

{% include preloader.html %} — 加载遮罩
{% include bg-layers.html %} — 背景层
<div id="rain-container"> + <canvas id="ripple-canvas"> + <div id="noise-overlay"> — 效果层
{% include music-player.html %} — 音乐播放器
{% include nav.html %} — 导航栏
{% include search.html %} — 搜索页
{{ content }} — 子布局内容
所有 JS（jQuery → Bootstrap → hux-blog → SimpleJekyllSearch → 效果脚本）
搜索开关 JS（toggleSearch() 全局函数 + bindSearchClose()）
{% include footer.html %}（首页除外）

关键设计：所有脚本放在 default.html 而非 footer.html，确保首页（不加载 footer）也能使用所有功能。

home.html（首页）

layout: default → body.home-page → overflow:hidden → {% include splash.html %}

首页为全屏画窗，不可滚动。左侧显示站点名 + 签名 + 3 篇最新文章，右侧为画窗工具按钮和温度计。

post.html（文章页）

标题区（.post-view-title-wrap）替代原 intro-header 大图
保留：pager 上下篇翻页、Side Catalog 侧边目录、MathJax、AnchorJS
已删除：Disqus 评论、网易云评论、侧边栏

全局效果模块

预加载器（`preloader.js`）

全屏遮罩，显示 “Now Loading…”
监听 window.load 事件后 350ms 淡出
兜底：最长 10 秒后强制淡出
淡出动画 1.2 秒，完成后从 DOM 移除

水波纹（`water-ripple.js`）

Canvas 2D 高度场水波模拟
Float32Array 双缓冲，DAMP=0.9855
4 邻域波方程
自动雨滴 + 鼠标交互
gloss 模式（无折射），依赖 CSS 背景图

雨效果（`rain.js`）

45 滴雨的物理模拟
2 秒延迟淡入
document.hidden 时暂停

画窗 GLASS CANVAS（`glass-canvas.js`）

移植自 InternalBeyond 单体应用。功能：

白笔：玻璃发光绘制（canvas ink 层）
指雾笔：擦开凝雾（canvas fogwipe 层）
清除：清空所有画迹
MIST 温度计：调节凝雾厚度（FOGD 初始 0.3）
BRUSH 温度计：调节画笔大小
探测 /img/bg-canvas.png 作为画窗背景

音乐播放器（`music-player.js`）

IIFE 封装，自动读取 music/ 目录：

播放列表生成：music-list.json（Liquid 模板）在构建时扫描 site.static_files 中 /music/ 路径下的音频文件
Jekyll 4.4.1 注意：file.relative_path 输出为空，必须用 file.path
支持格式：.mp3 .wav .ogg .m4a .aac .flac
加载方式：fetch + Blob URL（解决 OGG duration=Infinity 和无法 seek 的问题）
功能：播放/暂停/上一首/下一首、进度条拖动（鼠标+触摸）、静音/最大音量切换、三种播放模式（列表循环/单曲循环/随机）、Web Audio API 48 条频谱可视化
不实现跨页面持久化：每次页面加载从头开始

导航栏（`nav.html`）

液态玻璃风格，全局默认隐藏：

鼠标移至屏幕顶部 80px 内 → 展开
离开后延迟 2.5 秒 → 收起
鼠标悬停在导航栏上 → 保持展开
移动端：点击汉堡按钮展开，下拉菜单为玻璃拟态

搜索（`search.html` + `default.html`）

SimpleJekyllSearch 引擎，搜索索引 /search.json 在构建时生成
全屏覆盖页，从底部滑入
toggleSearch(open) 全局函数控制开关
关闭按钮用 addEventListener('click') 绑定（兼容移动端）
ESC 键关闭
z-index: 100001，确保在最上层

通知弹窗（`snackbar.js` + `snackbar.less`）

液态玻璃风格，右下角：

Service Worker 检测到内容更新时触发 “Content updated.” 通知
z-index: 100002（最高层）
动画：opacity + translateY 过渡
“refresh” 按钮可刷新页面

Service Worker（`sw.js`）

预缓存 PRECACHE_LIST（CSS/JS/图片）
Stale-while-revalidate 策略
revalidateContent()：检测 HTML 内容更新，通过 postMessage 通知页面
HOSTNAME_WHITELIST：本站 + cdnjs.cloudflare.com 等

响应式设计

Bootstrap 响应式网格系统
媒体查询断点：768px（桌面/移动）
移动端导航抽屉：玻璃拟态背景 rgba(25,38,65,0.55) + blur(24px)
字体使用相对单位

更新 Post 的规范

文件命名规范

格式：YYYY-MM-DD-标题.md

示例：

2026-02-14-my-first-post.md
2026-02-14-learning-jekyll.markdown

注意事项：

日期必须使用 YYYY-MM-DD 格式
标题使用小写字母和连字符，避免空格和特殊字符
扩展名可以是 .md 或 .markdown

Front Matter 模板

---
layout:     post           # 必填：使用 post 布局
title:      "文章标题"       # 必填
subtitle:   "副标题"        # 可选
date:       2026-02-14     # 必填：发布日期
author:     "作者名"        # 可选
catalog:    true           # 可选：是否显示侧边目录
tags:                      # 可选：标签列表
    - 标签1
    - 标签2
mathjax:    false          # 可选：是否启用数学公式
multilingual: false        # 可选：是否启用多语言
---

注意：header-style 和 header-img 字段已弃用（intro-header 大图已删除，所有页面改为简洁标题区）。

创建新文章的完整流程

步骤 1：创建 Markdown 文件

在 _posts/ 目录下创建符合命名规范的文件

步骤 2：编写 Front Matter

复制上述模板，填写必要信息

步骤 3：编写文章内容

使用 Markdown 语法编写正文

步骤 4：本地预览

# PowerShell 中需先清除环境变量
$env:ACC_PRODUCT_CONFIG_V3 = ""
bundle exec jekyll serve --port 4100

# music/ 目录含大文件时，改用：
bundle exec jekyll build
cd _site
python -m http.server 4100

注意：Python http.server 不支持自定义 404 页面，测试 404 需用 jekyll serve。

步骤 5：提交到 GitHub

git add .
git commit -m "Add new post"
git push

GitHub Pages 会自动构建部署。

图片资源引用方式

方式 1：绝对路径（推荐）

![图片描述]({{ site.baseurl }}/img/post-bg.jpg)

方式 2：相对路径

![图片描述](/img/example.jpg)

图片存放位置：

文章特定图片：img/in-post/文章名/图片文件
通用背景图片：img/ 目录下

标签系统

在 front matter 中添加 tags：

tags:
    - 技术文档
    - 网站开发

_config.yml 中 featured-tags: true 启用特色标签
featured-condition-size: 1：文章数大于此值的标签显示为特色标签
Jekyll 自动收集所有文章标签到 site.tags
标签在归档页面和侧边栏自动显示
归档页支持按标签过滤（/archive/?tag=标签名）

注意事项

日期处理：front matter 中的 date 字段会覆盖文件名中的日期
特殊字符：标题中的中文需要正确编码，建议使用英文文件名
图片路径：确保图片路径正确，建议使用 {{ site.baseurl }} 前缀
标签一致性：标签名称大小写敏感，保持一致性
代码高亮：使用三个反引号包裹代码块，指定语言
多语言支持：如需多语言，在 front matter 中设置 multilingual: true
评论区已删除：Disqus 和网易云评论已从所有页面移除
AdSense 已删除：Google AdSense 已从 head.html 和 page.html 移除

文章排序规则

默认按日期降序排列（最新文章在前）
归档页面按年份分组显示
日期相同的文章按文件名字母顺序排列

已删除/已弃用的功能

功能	状态	说明
intro-header 大图	已删除	所有页面的最上方大图已移除，改为简洁标题区
Disqus 评论	已删除	从文章页和 about 页移除
网易云评论	已删除	从文章页移除
Google AdSense	已删除	从 head.html 和 page.html 移除
侧边栏（文章页）	已删除	featured-tags 和 friends 从文章页移除
音乐播放器添加文件按钮	已删除	改为自动读取 music/ 目录
`header-style` / `header-img`	已弃用	front matter 中不再需要

性能注意事项

已知瓶颈

bg-canvas.png（~6.2MB）：全局背景图 + 画窗探测图，是最大的加载瓶颈
Google Fonts（6 个字体族）：Noto Sans SC 和 Noto Serif SC 是中文字体，体积大
music/ 目录大文件：OGG 文件较大时 jekyll serve 构建极慢（>1 分钟）
11+ 个同步 JS 文件：default.html 底部大量 <script> 标签

优化方向

压缩 bg-canvas.png（转 WebP 或 JPEG 质量 80）
精简 Google Fonts（中文字体改用系统字体或子集化）
非首屏 JS 延迟加载（defer 或 preloader 淡出后加载）
Font Awesome 改为本地加载或用 SVG inline 替代

后记

本网站于 2026.2.12 建立，2026.7.1-7.2 进行 InternalBeyond 视觉重构。

Music