未命名文章

1. 概述

我的个人网站。

2. 技术栈

项目为前后端分离静态站点生成架构。

依赖版本详情

Python 依赖（requirements.txt）

markdown               # 核心 Markdown 解析
pyyaml                 # Frontmatter 解析
requests               # 友链头像下载
pillow                 # 图像主色提取
rcssmin                # CSS 压缩
python-dateutil        # 日期解析
packaging              # 版本号排序
pymdown-extensions     # 扩展 Markdown 语法

Node.js 依赖（package.json）

{
  "devDependencies": {
    "typescript": "^6.0.3",
    "vite": "^8.1.1",
    "rollup-plugin-copy": "^3.5.0"
  }
}

3. 目录结构

Website
├─ .github
│  └─ workflows
│     └─ static.yml
├─ builder
│  ├─ generators
│  │  ├─ aggregated.py
│  │  ├─ base.py
│  │  └─ friend_colors.py
│  ├─ build_context.py
│  ├─ common.py
│  ├─ engine.py
│  ├─ input_loader.py
│  └─ __init__.py
├─ dist
├─ node_modules
├─ src
│  ├─ assets
│  │  ├─ source
│  │  │  ├─ 分类一
│  │  │  │  └─ 马生复宋濂书.md
│  │  │  └─ 分类二
│  │  │     └─ 网站的起源.md
│  │  ├─ avatar.webp
│  │  ├─ friends.json
│  │  ├─ friend_colors.json
│  │  └─ 网站更新日志.md
│  ├─ copy
│  │  ├─ .well-known
│  │  │  └─ vercount-verify-pof0sq1cg39g4rpkl66s6rtf.txt
│  │  ├─ BingSiteAuth.xml
│  │  ├─ favicon.ico
│  │  └─ robots.txt
│  ├─ css
│  │  ├─ components
│  │  │  ├─ comments.css
│  │  │  ├─ footer.css
│  │  │  ├─ github-contrib-graph.css
│  │  │  ├─ image-viewer.css
│  │  │  └─ navbar.css
│  │  ├─ core
│  │  │  ├─ base.css
│  │  │  ├─ components.css
│  │  │  ├─ layout.css
│  │  │  └─ variables.css
│  │  ├─ pages
│  │  │  ├─ 404.css
│  │  │  ├─ about.css
│  │  │  ├─ article.css
│  │  │  ├─ friends.css
│  │  │  ├─ home.css
│  │  │  ├─ stats.css
│  │  │  └─ timeline.css
│  │  └─ main.css
│  ├─ js
│  │  ├─ core
│  │  │  ├─ app-initializer.ts
│  │  │  ├─ clarity.ts
│  │  │  ├─ core.ts
│  │  │  ├─ data-service.ts
│  │  │  ├─ disposable-stack.ts
│  │  │  ├─ modal-base.ts
│  │  │  ├─ page-manager.ts
│  │  │  ├─ page-utils.ts
│  │  │  ├─ scroll-dispatcher.ts
│  │  │  ├─ theme-controller.ts
│  │  │  └─ twikoo-manager.ts
│  │  ├─ data
│  │  │  ├─ settings.ts
│  │  │  ├─ site-state.ts
│  │  │  └─ sw.js
│  │  ├─ entry
│  │  │  └─ main.ts
│  │  ├─ pages
│  │  │  ├─ about.ts
│  │  │  ├─ article.ts
│  │  │  ├─ friends-manager.ts
│  │  │  ├─ home-manager.ts
│  │  │  ├─ search-render.ts
│  │  │  ├─ stats-manager.ts
│  │  │  ├─ timeline.ts
│  │  │  └─ stats
│  │  │     ├─ chart-registry.ts
│  │  │     └─ charts.ts
│  │  ├─ router
│  │  │  └─ router.ts
│  │  ├─ standalone
│  │  │  └─ 404.ts
│  │  ├─ ui
│  │  │  ├─ button-manager.ts
│  │  │  ├─ detail-dialog.ts
│  │  │  ├─ image-manager.ts
│  │  │  ├─ image-viewer.ts
│  │  │  ├─ jump-dialog.ts
│  │  │  ├─ list-events.ts
│  │  │  ├─ loading-overlay-manager.ts
│  │  │  ├─ mouse-effects.ts
│  │  │  ├─ navbar-manager.ts
│  │  │  ├─ personal-card.ts
│  │  │  ├─ theme.ts
│  │  │  ├─ tooltip.ts
│  │  │  └─ ui-effects.ts
│  │  └─ vendor
│  │     ├─ APlayer.min.js
│  │     ├─ browser.global.min.js
│  │     ├─ global-music-player.ts
│  │     └─ vercount.min.js
│  ├─ templates
│  │  ├─ 404.html
│  │  ├─ about.html
│  │  ├─ contact.html
│  │  ├─ footer.html
│  │  ├─ index.html
│  │  ├─ privacy.html
│  │  ├─ stats.html
│  │  └─ timeline.html
│  └─ works
│     ├─ 作品一
│     │  └─ metadata.json
│     └─ 作品二
│        ├─ index.html
│        └─ metadata.json
├─ .gitignore
├─ .gitmodules
├─ CNAME
├─ LICENSE
├─ package-lock.json
├─ package.json
├─ README.md
├─ requirements.txt
├─ run.py
└─ vite.config.ts

4. 构建系统详解

将源码（Markdown、元数据、前端资源）转换为可部署的静态网站。整个系统由 Python 编写，模块化设计，支持增量构建、并行执行和扩展。

4.1 核心组件

4.2 构建流程

1. 加载输入：InputLoader 读取所有源文件，生成 BuildContext 对象。
2. 生成器注册：在 run.py 中注册 FriendColorsGenerator 和 AggregatedGenerator。
3. 增量判断：引擎检查每个生成器的输出文件是否都存在，并比对输入数据的哈希值（以及前端资源的哈希），若未变化则跳过。
4. 执行生成：依次（或并行）调用各生成器的 generate() 方法，将结果写入 dist/ 目录。
5. 更新状态：成功生成后，将当前输入哈希及时间戳保存到 .build_state.json，供下次增量判断使用。

4.3 增量构建机制

• 状态文件：.build_state.json 存储每个生成器上次运行的“输入哈希”和“前端哈希”。
• 输入哈希：由生成器声明的依赖（如 articles、works）的序列化内容计算而得，任一源文件改动都会导致哈希变化。
• 前端哈希：AggregatedGenerator 额外监控 src/css/、src/js/、src/templates/、src/assets/（除 source/ 外）以及根目录下的 favicon.ico、robots.txt 等文件，确保前端资源变动时重新编译。
• 强制重建：通过 --force 参数可忽略所有增量判断，强制全量构建；--force-colors 可单独强制更新友链颜色。

4.4 生成器详解

AggregatedGenerator（聚合生成器）

这是最主要的生成器，其 generate() 方法依次执行以下任务：

• 统计生成：统计文章数、总字数、标签/分类频次、作者数、更新天数等，写入 dist/json/statistics.json。
• RSS 生成：从文章和作品中提取条目，按时间排序生成 dist/rss.xml。
• 站点地图：生成 dist/sitemap.xml，包含所有文章及固定页面。
• 文章列表页：渲染 dist/articles/index.html，包含标签筛选、搜索框、排序功能，数据通过 window.__STATIC_ARTICLES_DATA 注入。
• 作品列表页：渲染 dist/works/index.html，类似文章列表，数据通过 window.__STATIC_WORKS_DATA 注入。
• 友链页面：渲染 dist/friends/index.html，包含友链卡片（带主题色）和申请要求说明。
• 无 JS 回退页：生成 dist/nojs.html，提供完全静态的内容列表，方便搜索引擎或禁用 JavaScript 的用户访问。
• 子目录页面：将 src/templates/ 下的 about.html、timeline.html、stats.html、contact.html、privacy.html 复制到对应的 dist/about/、dist/timeline/ 等目录。
• 前端构建：调用 Vite 编译 TypeScript（npm run build），并将结果输出到 dist/js/。
• 静态资源复制：
  • 压缩 CSS（使用 rcssmin）并复制到 dist/css/。
  • 复制 src/assets/（排除 source/）到 dist/assets/。
  • 复制 src/copy/ 下的所有文件（如 favicon.ico、robots.txt、BingSiteAuth.xml 等）到 dist/ 根目录。
  • 复制 src/works/（排除 metadata.json）到 dist/works/，以便作品子页面资源可访问。
  • 复制 friends.json 和 friend_colors.json 到 dist/json/ 供前端使用。
• 代码分析：生成 dist/json/code_analysis.json，记录 dist/ 目录下各文件类型的数量、大小和行数统计，便于监控构建产物规模。

FriendColorsGenerator（友链颜色生成器）

• 功能：为每个友链的头像图片提取主色调，生成 src/assets/friend_colors.json（映射：网站链接 → [R, G, B]）。
• 缓存：头像图片会被缓存到临时目录，避免重复下载。
• 依赖：需 requests 和 Pillow 库，若未安装则生成器跳过（但构建不会失败，只会使用默认灰色）。
• 增量：默认只处理新增或缺失颜色的友链，使用 --force-colors 可强制刷新所有。

4.5 命令行用法

# 全量构建（忽略增量）
python run.py --force

# 仅强制更新友链颜色（其他生成器仍按增量判断）
python run.py --force-colors

# 只运行指定生成器（如只生成友链颜色）
python run.py --targets friend_colors

# 禁用并行执行（串行运行所有生成器）
python run.py --no-parallel

# 调整并行线程数（默认 4）
python run.py --workers 6

4.6 依赖与环境

• Python 依赖：见 requirements.txt，主要包括 markdown、pyyaml、requests、pillow、rcssmin、python-dateutil、packaging、pymdown-extensions。
• Node.js 依赖：用于前端 TypeScript 编译，见 package.json，使用 Vite 作为构建工具。
• 安装命令：

pip install -r requirements.txt
npm install

4.7 扩展新生成器

若需增加自定义输出（如生成 JSON 摘要、额外页面），可继承 OutputGenerator 基类并实现抽象方法，然后在 run.py 中注册。例如：

from builder.generators.base import OutputGenerator
from builder.build_context import BuildContext

class MyGenerator(OutputGenerator):
    name = "mygen"
    inputs = {"articles"}
    outputs = [Path("dist/my.json")]

    def generate(self, context: BuildContext, force: bool) -> bool:
        # 使用 context.articles 生成 my.json
        return True

注册：

engine.register(MyGenerator())

5. 前端架构

前端采用 单页应用 (SPA) 模式，基于原生 TypeScript 构建，无第三方框架依赖。核心设计遵循 模块化、可维护性 和 性能优先 原则，通过自定义路由、页面管理器、数据服务层和 UI 组件库，实现流畅的页面切换、高效的数据缓存和丰富的交互体验。

5.1 整体架构图

flowchart TB
    subgraph 入口与初始化
        A[main.ts] --> B[AppInitializer]
        B --> C[加载导航栏/页脚/主题/背景]
        B --> D[LoadingOverlayManager]
        D --> E[版本检测 & 数据预加载]
        E --> F[初始化完成]
    end

    subgraph 路由系统
        F --> G[enableAjaxNavigation]
        G --> H[router.ts]
        H --> I[拦截点击事件]
        I --> J[fetchAndReplaceContent]
        J --> K[提取页面内容 #router-view]
        K --> L[替换 DOM + 执行新页面脚本]
        L --> M[更新历史记录 & 滚动位置]
    end

    subgraph 页面管理
        M --> N[PageManagerRegistry.create]
        N --> O{页面类型}
        O -->|首页| P[HomePageManager]
        O -->|文章列表/作品列表| Q[SearchController]
        O -->|文章详情| R[ArticlePageManager]
        O -->|时间线| S[TimelineManager]
        O -->|统计| T[StatsManager]
        O -->|友链| U[FriendsPageManager]
        O -->|关于| V[AboutPageManager]
        O -->|其他| W[通用页面]
        P & Q & R & S & T & U & V & W --> X[执行 init / destroy]
    end

    subgraph 数据与缓存
        E --> Y[DataService]
        Y --> Z[内存缓存 60s + 并发去重]
        Z --> AA[Service Worker 持久化缓存]
        Y --> AB[API 请求 /json/*]
    end

    subgraph UI组件与交互
        C --> AC[主题切换 theme-controller]
        C --> AD[导航栏 navbar-manager]
        C --> AE[个人卡片 personal-card]
        C --> AF[浮动按钮 button-manager]
        C --> AG[鼠标特效 mouse-effects]
        C --> AH[图片查看器 image-viewer]
        C --> AI[跳转弹窗 jump-dialog]
        C --> AJ[滚动揭示 ui-effects]
        C --> AK[全局滚动分发 scroll-dispatcher]
    end

    subgraph 第三方集成
        K --> AL[Twikoo 评论]
        K --> AM[vercount 统计]
        K --> AN[Chart.js 图表]
        K --> AO[APlayer 音乐播放器]
        K --> AP[GitHub 贡献图]
        B --> AQ[Microsoft Clarity]
    end

    subgraph 性能与工具
        B --> AR[requestIdleCallback 调度]
        J --> AS[页面缓存 & 预加载]
        H --> AT[滚动位置恢复]
        AA --> AU[Service Worker 离线缓存]
        B --> AV[DisposableStack 资源清理]
    end

5.2 模块划分与职责

5.3 核心流程

5.3.1 应用启动流程

1. 入口：main.ts 监听 DOMContentLoaded，调用 AppInitializer.start()。
2. 编排器阶段：
   • 阶段 1：基础设施
     • 添加预连接、预加载标签。
     • 初始化滚动揭示。
     • 同步主题（themeController.init()）。
     • 空闲时加载背景图。
   • 阶段 2：页面骨架
     • 等待加载导航栏。
     • 异步加载页脚。
     • 渲染个人卡片。
     • 启动站点年龄更新器。
     • 初始化浮动按钮。
   • 阶段 3：空闲任务
     • 启用无刷新导航与列表点击。
     • 初始化当前页面特性（initPageFeatures）。
     • 初始化 UI 特效、预热 DataService、图片懒加载、全局图片查看器、页脚统计。
     • 加载音乐播放器。
   • 阶段 4：收尾
     • 初始化 Clarity，监听 ajax:navigation 更新页面。
     • 注册 popstate。
     • 显示加载覆盖层（LoadingOverlayManager）。
     • 播放导航栏入场动画。
     • 标记 data-loaded。
     • 注册 Service Worker（生产环境；开发环境注销）。

5.3.2 路由与页面切换

• 用户点击同源链接 → router.ts 拦截（enableAjaxNavigation）。
• 调用 fetchAndReplaceContent(url)：
  1. 检查内存页面缓存，若命中且未过期则直接使用。
  2. 否则发起 fetch 请求。
  3. 解析 HTML，提取 #router-view 内容、样式表、脚本。
  4. 执行 DOM 替换（带淡入淡出动画）。
  5. 卸载旧页面的资源（样式/脚本）。
  6. 加载新页面的资源，并通过 PageManagerRegistry 初始化对应 PageManager。
  7. 恢复滚动位置（从 history.state 或锚点）。
  8. 触发 ajax:navigation 事件，供其他模块监听。

5.3.3 数据流

• 所有 API 请求通过 DataService 单例发出。
• 策略：
  1. 内存缓存：TTL 60 秒。
  2. 并发去重：同一请求多个调用共享同一个 Promise。
  3. 持久化缓存：由 Service Worker 负责（/json/ 数据采用 Stale-While-Revalidate）。
  4. 强制刷新：通过 cache: 'reload' 通知 SW 绕过缓存。
  5. 网络失败降级：返回过期内存缓存。
• 页面管理器在 init 中调用 DataService 获取数据，并渲染 UI。

5.3.4 搜索与筛选（文章/作品列表）

• 使用 SearchController（位于 search-render.ts）管理列表页。
• 核心逻辑在当前主线程执行，使用 debounce 与 requestAnimationFrame 分批渲染（每批 20 项），避免一次性插入大量 DOM。
• 支持标签筛选、关键词搜索（标题/标签/日期）、多种排序（更新时间、字数、发布日期）。
• URL 参数与搜索状态双向同步（pushState 更新）。
• searchWorker.ts 为历史/预留模块，当前未接入。

5.3.5 页面管理器生命周期

• 每个页面管理器实现 init 和 destroy 方法。
• 推荐继承 PageBase，在 mount() 中注册资源到 this.stack，在 unmount() 中做额外收尾。
• init：绑定事件、加载数据、渲染 DOM、初始化第三方组件（如 Twikoo）。
• destroy：清理事件监听、定时器、观察者，重置 DOM（防止内存泄漏）。
• 路由切换时自动调用旧页面的 destroy 和新页面的 init。

5.4 性能优化策略

5.5 技术选型说明

5.6 扩展指南

添加新页面

1. 在 src/templates/ 创建 HTML 模板（含 #router-view 等占位）。
2. 在 builder/generators/aggregated.py 的 PAGE_TEMPLATES 中注册。
3. 在 src/js/pages/ 下创建对应的 XxxManager.ts，推荐继承 PageBase，实现 mount() / unmount()。
4. 在 src/js/router/router.ts 的 registerDefaultPages() 中使用 PageManagerRegistry.register(pattern, factory) 注册页面管理器。
5. 在导航栏（navbar-manager.ts 的 NAV_LINKS）添加链接项。
6. 重新运行构建。

自定义 UI 组件

• 新建文件于 src/js/ui/，导出核心函数。
• 遵循“事件绑定与销毁”模式，确保在页面切换时能清理资源。
• 若需全局弹窗，可使用 detail-dialog.ts 或 jump-dialog.ts 作为基础。
• 若需管理复杂资源，使用 DisposableStack。

修改主题或样式

• CSS 变量定义在 src/css/core/variables.css。
• 主题状态由 src/js/core/theme-controller.ts 统一管理。
• 导航栏开关绑定在 src/js/ui/theme.ts。
• 图表颜色随主题变化：stats-manager.ts 使用 themeController.onChange 监听并重建图表。

6. 关键数据流

6.1 文章发布流程

1. 作者在 src/assets/source/分类/ 下新建 .md 文件（含 frontmatter）
2. 运行 python run.py
3. input_loader 解析 MD，生成 HTML 到 dist/articles/
4. 更新 dist/json/articles.json
5. aggregated 生成统计、RSS、站点地图
6. 静态资源复制（Vite 构建 JS/CSS）
7. 部署 dist/ 到服务器

6.2 前端页面加载流程（以文章详情为例）

1. 用户点击文章链接（或直接输入 URL）
2. router 拦截，fetch 获取 /articles/xxx.html
3. 提取 #router-view 内容，替换
4. 初始化 ArticlePageManager
5. ArticlePageManager：
   - 初始化现有 TOC 结构与链接点击
   - 初始化阅读进度条
   - 启用图片懒加载（IntersectionObserver）
   - 初始化代码块复制
   - 初始化移动端侧边栏
   - 保存/恢复滚动位置
   - 初始化 Twikoo 评论（动态加载库）
   - 启动数学公式渲染（KaTeX）
   - 更新 vercount 统计
   - 监听主题变化刷新阅读进度
6. 记录滚动位置到 sessionStorage（返回时恢复）

6.3 搜索与筛选流程（文章/作品列表）

1. 页面加载时，DataManager 从缓存或网络获取数据。
2. SearchController 从 URL 解析查询参数（q, field, tags, sort）。
3. 在主线程过滤、排序数据。
4. UIRenderer 生成 HTML，使用 requestAnimationFrame 分批插入列表容器（每批 20 项）。
5. 滚动揭示效果重新触发（ScrollReveal）。
6. 用户修改搜索/标签/排序时，更新 URL 并重复上述过程。

7. 数据格式规范

7.1 文章 Frontmatter（YAML）

---
title: 文章标题
date: 2026-05-24
description: 简介
author: 高新炀
tag: [随笔, 生活]
category: 随笔   # 可选，默认使用所在子目录名
---

• date 支持 YYYY-MM-DD 或 YYYY年MM月DD日。
• tag 可为数组或逗号分隔字符串。
• 包含 隐藏 标签的文章将不出现在列表/RSS/统计中，但仍生成 HTML 到 .hidden/。

7.2 作品元数据（works/作品名/metadata.json）

{
  "title": "作品标题",
  "date": "2026-01-01",
  "description": "描述",
  "author": "高新炀",
  "tag": ["工具", "游戏"],
  "link": "https://example.com"   // 可留空，默认指向 /works/作品名/
}

7.3 友链（dist/json/friends.json）

[
  {
    "name": "站点名称",
    "link": "https://example.com",
    "desc": "描述",
    "avatar": "https://example.com/avatar.png"
  }
]

7.4 统计 JSON（statistics.json）字段

8. 开发与扩展指南

8.1 添加新页面

1. 在 src/templates/ 下创建新的 HTML 模板，包含 #navbar-placeholder、#personal-card-container、#footer-placeholder、#router-view 等占位。
2. 在 builder/generators/aggregated.py 的 PAGE_TEMPLATES 字典中添加映射（模板名 → 子目录），以在构建时复制到 dist/。
3. 若页面需要动态初始化，在 src/js/pages/ 下创建对应的页面管理器，推荐继承 PageBase。
4. 在 src/js/router/router.ts 的 registerDefaultPages() 中使用 PageManagerRegistry.register(pattern, factory) 注册该页面管理器。
5. 在导航栏（navbar-manager.ts 的 NAV_LINKS）中添加链接项。
6. 重新运行构建。

8.2 自定义生成器

若需扩展构建输出（如生成 JSON 摘要、额外页面等），可继承 OutputGenerator：

from builder.generators.base import OutputGenerator
from builder.build_context import BuildContext

class MyGenerator(OutputGenerator):
    name = "mygen"
    inputs = {"articles", "works"}   # 依赖的上下文属性
    outputs = [Path("dist/myfile.json")]

    def generate(self, context: BuildContext, force: bool) -> bool:
        # 使用 context.articles, context.works 等生成
        return True

然后在 run.py 中注册：

engine.register(MyGenerator())

8.3 修改前端构建（Vite）

• 入口文件：src/js/entry/main.ts。
• Vite 配置：vite.config.ts 将 src/js 映射为 /js，构建输出到 dist/（preserveModules 保持目录结构）。
• 生产构建通过 Python 构建系统调用 npm run build 触发 Vite。

8.4 调试技巧

• 构建日志：builder/common.py 提供 log_info/warning/error，彩色输出。
• 前端调试：Chrome DevTools。
• 数据缓存：DataService 使用内存缓存（60s），持久化数据在 Service Worker 的 Cache Storage 中；localStorage 主要保存设置、访客记录等。
• 性能分析：core/core.ts 中的 PerformanceMonitor 自动记录关键操作耗时，超过 100ms 会输出警告。
• Service Worker：可在 Chrome Application 面板中手动注销或更新。
• 主题调试：使用 themeController.getMode() / getTheme() 查看当前状态。

9. 部署说明

1. 安装 Python 依赖：

pip install -r requirements.txt

1. 安装 Node.js 依赖：

npm install

1. 运行构建：

python run.py

或：

python run.py

1. 构建产物位于 dist/ 目录。
2. 将 dist/ 内容上传到静态托管平台（如 GitHub Pages、Netlify、Vercel）。
3. 确保 CNAME 文件内容为自定义域名（如需）。
4. 若使用 Twikoo，需部署云函数并更新各页面中的 envId。

10. 许可证

• 代码：MIT License
• 文章内容：CC BY-NC-ND 4.0（除特别声明外）

本文档持续更新，以项目最新代码为准。
维护者：高新炀
最后更新：2026-09-12