发布于 2026-06-01 22:55:21
0 comments

firekylin博客系统升级优化记录

之前有了想要把博客彻底统一的想法，考虑到后续使用的方便，决定对firekylin博客系统（包括主题）进行一轮优化，把发现的Bug也都修掉。没想到这一晃就搞了好久，不过好在把想改的地方都改完了。

下面的内容是我用AI综合我的改动提纲+commit信息整理汇总生成，然后手动修改校对，可以认为覆盖比较全面、准确。

本文记录了对 Firekylin 博客系统进行的一系列升级优化工作，涵盖系统核心、编辑器、Markdown 渲染、后台管理以及自定义主题等多个方面。改动主要集中在 master 分支（系统核心）和 fanzheng.org 分支（自定义主题）上。

新功能

Markdown 编辑器大幅增强

这是本次升级中改动最大的部分，对后台 Markdown 编辑器进行了全面的功能增强，使其编辑体验向 GitHub Markdown 编辑器看齐。

图标全部升级为 SVG：替换原有图标方案，统一使用 SVG 格式（ce4edda）。

新增富文本快捷键：快捷键对齐 GitHub Markdown Editor 的行为（ff41157）

快捷键 功能
Ctrl+B 加粗
Ctrl+I 斜体
Ctrl+K 快速链接
Ctrl+L 链接
Ctrl+Q 引用
Ctrl+E 行内代码
Ctrl+Shift+E 代码段
Ctrl+G 图片
Ctrl+Shift+7 有序列表
Ctrl+Shift+8 无序列表
Ctrl+H 标题
Ctrl+R 分割线
Ctrl+M 插入more标签

列表操作增强：

  • 有序列表和无序列表支持智能识别：当选中行不全是列表时全部添加列表标记，全是列表时全部去掉（ffdb26a）
  • 点按回车时智能插入新的列表行，空列表行自动删除（c6950a8）

链接插入优化：

  • 链接和快速链接插入后，编辑器会根据上下文智能决定选中 text 还是 url 部分（e6b99e5）

其他编辑器功能：

  • 支持 Tab / Shift+Tab 缩进操作（ee11695）
  • 增加删除线、下划线、行内代码、快速链接、键盘按键（<kbd>）等富文本功能（5583abe）
  • 编辑器支持等宽字符模式（monospace），方便编写代码（b71cc94）

Markdown 渲染能力升级

  • Footnotes 支持：新增脚注语法（cbae59d）
  • Alert 支持：支持 GitHub 风格的 Alert 语法（33aba9d），增加 Alert 富文本插入功能（65ede6f）
  • LaTeX 公式添加 className：方便通过 CSS 自定义公式样式（20d5550）
  • 纯图片段落加 className：纯图片段落增加 class 以支持自定义样式（c485960）

分类（Categories）功能

新增分类功能支持，包括后台分类管理页面和前台分类页面，同时添加了相关图标并切换为 SVG 格式（0a02e95）。

文章草稿选项卡

文章管理的文章列表页增加了草稿选项卡，方便快速查看和管理草稿状态的文章（b8edcca）。

Bug 修复

链接 URL 编码问题

文章链接存在多处 URL 未正确 encode 的问题，涉及多个页面：

  • post 页的上一篇/下一篇链接、文章编辑页中的文章链接未 encode，导致含中文或特殊字符的路径无法跳转
  • 搜索结果页的文章链接未 encode
  • 标签和分类在 tags 页、categories 页、post 页的链接 encode 遗漏
  • 手动添加分类和标签时的 encode 行为与编辑器自动添加的行为不一致，统一去除手动 encode

相关提交：8502120、49057ab、5eb263b、e9ec988

Markdown 编辑器修复

  • 撤销/重做失效：编辑器通过工具栏插入文本后无法撤销/重做，同时 _preInputText 未正常更新 localStorage，以及点击富文本按钮后没有激活 textarea（e8fc126）

后台管理页面修复

  • 阅读设置页面：二次进入时首页选项显示异常，原因是旧的不规范写法导致数据未正确回填（410fffa）
  • 标签编辑页：进入添加标签页时表单没有清空，残留上次数据（a3712f8）
  • 分类和标签：文章关联的分类和标签添加后无法彻底删除（87b53d1）
  • 分类编辑页：MobX 升级后 categoryInfo 没有初始化，由于 tsconfig 的设置导致 MobX 忽略（1966438）

渲染相关修复

  • LaTeX 公式失效：marked 升级后 LaTeX 公式渲染失效（d499288）
  • 标题含公式时 TOC 不一致：标题中含有数学公式时，正文渲染和 TOC 目录的锚点不一致、TOC 标题渲染异常。通过将 MathJax 和 TOC 改写为 Marked Extension 形式彻底解决（82da60a）
  • page 手动指定 toc 不生效：page 类型文章即使手动指定 toc 也不生成目录（8a26235）
  • page 与 post 的 DOM 结构不一致：导致主题脚本在 page 页不执行（ef0b669）

Ant Design v4 升级回归修复

Ant Design v3 → v4 升级后暴露出大量历史不规范写法导致的回归问题，逐一修复：

  • category/upload/tag/push/user 页表单不规范写法失效 & 已废弃 React 接口重写（475af7f）
  • user 页 submitting 和 hasEmail 初始化状态不正确导致页面状态异常（d9b6042）
  • 文章编辑页标题不更新（144b321）
  • post 页对 antd 类名的硬依赖导致升级后样式失效（26f4266）
  • 外观设置-菜单管理 button 样式恢复（a7c382d）
  • 几个默认行为变更导致的样式问题（585094a）
  • 系统设置-阅读设置无法显示默认数据（96775f6）
  • form 默认样式变更导致的样式变化（001b090）
  • LDAP 设置页无法显示默认数据（16d74af）
  • 登录页"自动登录"与"找回密码"不在同一行（50882a7）

迁移与构建修复

  • axios 拦截器失效：迁移到 Vite 后，CJS → ESM 转换导致 axios 拦截器不工作（9121a8a）
  • MobX v5 不兼容：迁移到 Vite 后与 MobX v5 不兼容导致后台打不开，升级 MobX v6 解决（fa7e11e）
  • Vite 产物缓存：Vite 产物未添加 hash，导致管理页更新后被浏览器缓存（7e464c7）
  • Dockerfile 资源文件不全：release 版本没正确执行 sqlite3 的 postinstall，Dockerfile 资源文件复制不全导致无法启动（67dea83）
  • release.yml 版本过滤逻辑：版本过滤逻辑问题导致无法正常自动 release（9650c7d）
  • pnpm-workspace.yaml：加回 pnpm-workspace.yaml，修复 pnpm v9 兼容问题（233fe88、ab78347）
  • 直接依赖未显式声明：部分直接依赖没有显式写在 package.json 中（44da6ef）

其他改动

Ant Design v3 → v4 迁移

Ant Design v4 的初始迁移由迁移工具完成（生成第一个可编译版本），在此基础上进行了大量后续工作：

  • 去除兼容性处理，清理废弃 API（6d59c45）
  • Button 组件规范化改造（12ef079）
  • 后端依赖的 moment.js 迁移到 dayjs（1484db1）
  • 逐一修复升级后的回归问题（详见「Ant Design v4 升级回归修复」一节）

Markdown 渲染引擎升级

  • marked 升级：从 v4 升级到 v18（773c580）
  • MathJax 升级：从 v2 升级到 v4，去除 mathjax-node 依赖（f24061a），公式渲染改为使用 MathJax 4 直接渲染为 SVG
  • 代码高亮重构：将代码高亮重构为插件实现，并升级 highlight.js 版本（158a0e9）
  • MathJax 和 TOC 改写为 Marked Extension：解决标题含公式时的 TOC 锚点不一致问题（82da60a）

编辑器代码优化与清理

  • 清理编辑器无用代码，marked 升级后默认不支持 HTML 过滤（95a542b）
  • 优化富文本标签插入的文本（956014a）
  • 编辑器快捷键函数结构重构（15964fb）

依赖与构建维护

  • 清理不必要的依赖 & 升级部分依赖（4ba1847）
  • 多次 Dockerfile 修复与调整（c50d7b0、5ceefd0、75f1ed0、2a4959b）

主题改动

主题的改动在 fanzheng.org 分支上，基于默认主题进行优化。

代码块样式优化

  • 代码行号 CSS 样式规范化（38fb127、e1aafbd）
  • 不超过 5 行的代码块不显示行号，避免短代码段的视觉干扰（cf72e0e）
  • 修改代码块字体，合并冗余样式（39f3ca5）
  • 行间代码样式调整，代码显示更扁平，行号标记做了相应调整
  • 基于 highlight.js 的 CSS 优化代码高亮显示效果

目录（TOC）优化

  • 实现右侧目录悬浮效果（24f8042）
  • 目录标题自动添加序号（ba5622d）
  • 目录标题跟随页面滚动自动高亮当前阅读位置（1426098）
  • 文章正文标题也支持自动编号（9839140）
  • 目录标题增加 hover title 提示（5f618fe）

排版与样式

  • 行内代码样式微调
  • blockquote 引用块样式优化
  • 图片自动缩放，适配不同屏幕宽度
  • 块级公式居中
  • 多张图片并排居中（32a0a97）
  • 表情图片去除默认边框（e35aad9）
  • 水平分隔线样式修改（5c0ddec）
  • <em> 标签的斜体字改为楷体字显示，更符合中文排版习惯（64c640a）
  • 发布时间样式调整（2de5092）

交互与功能

  • 外部链接在新标签页打开（target blank）
  • 脚注去掉标题的编号，脚注编号加方括号（c631f7e）
  • Alert 组件样式优化，alert title 替换成中文（fd419a0）
  • 键盘按键（kbd）样式优化（4cd4d29）
  • 评论区样式和提示信息优化

其他主题改动

  • 去掉文章底部的 EOF 标记、本文链接等冗余信息
  • 删去不必要的作者信息，优化布局样式
  • 去掉默认列表样式（6a7d019）
  • page 页增加日期时间等信息（4d1536b），保持与 post 页一致的 DOM 结构（4f9cc5a）
  • 增加 music 等图标（0aaea11、2cc3077）
  • 注释掉热搜词（68bbd60）
  • 去掉 post.content 的 replace（15984bd）

总结

本次升级优化工作涉及面广，主要成果包括：

  1. Markdown 编辑体验质的飞跃：从仅有基础功能的编辑器，升级为支持丰富快捷键、智能列表操作、多种富文本格式的专业级编辑器，体验向 GitHub 编辑器看齐
  2. 渲染引擎全面升级：marked v4 → v18、MathJax v2 → v4、highlight.js 升级，支持 Footnotes、Alert 等 GitHub 风格 Markdown，并将 MathJax 和 TOC 重构为 Marked Extension 插件形式
  3. Ant Design v4 迁移：完成 v3 → v4 升级的后续回归修复工作，清理废弃 API，迁移 moment → dayjs
  4. 主题体验优化：代码块、目录、排版、交互等全方位优化，阅读体验显著提升
  5. 后台管理功能完善：新增分类功能、草稿选项卡，修复大量后台页面的回归问题

发表于 2026-06-01 22:55:21 ，最后修改于 2026-06-01 23:00:11

欢迎留言