[程序发布] FlintHub V1.2.0 → V1.2.13 改动总览

统计口径：以 V1.2.0 为基线（326 个文件），逐版本比对发布清单（manifest）里每个文件的 SHA-256，得出「新增 / 修改 / 删除」的真实差异，再与各版改动说明逐条对照。 覆盖 13 个版本（1.2.1 ~ 1.2.13），时间跨度 2026-10-20 → 2026-10-26， 共触碰 41 个实质文件（另有 version.php 每版必改）。

有修改过文件的用户，可以参考一下。

一、总览

版本速览

「改动文件」为该版实际改动的文件数（不含 version.php）；同一文件在多版被改动会重复计入。

二、按类别汇总

A. 新增功能（8 项）

B. 体验优化（9 项）

C. 问题修复（10 项）

D. 安全与稳定性加固（1.2.7 专项）

E. 插件生态与文档

三、逐版详解

V1.2.1 — 为插件生态新增 3 个表单挂载位

注册页、登录页、帖子回复框的表单里各新增一个插件挂载点，位置都在提交按钮上方、表单内部。

• 这 3 个挂载位只对插件生效：没装相关插件时页面上不产生任何多余元素，站长与访客完全无感。
• 插件作者可据此把验证组件（人机验证、协议勾选等）直接挂进表单，隐藏字段随表单一起提交。
• 纯扩展点改动：不改数据库、不改配置项、不改任何现有布局与交互。

涉及文件：app/Views/auth/login.php、app/Views/auth/register.php、app/Views/thread/show.php、docs/插件开发规范.md

V1.2.2 — 修复表情被放大到 96×96

现象：装上第三方编辑器插件（如 vditor、cherry）之后，帖子详情页里的站内表情显示成 96×96 大图； 不装插件时是正常的 28×28。楼中楼里因为文字短、缩进窄，对比最刺眼。

根因（四层，缺一层都不会出现）：

1. 表情输出为 <img class="emoji-emotion">；
2. 表情原图像素就是 96×96，没有 CSS 约束就是 96px；
3. 全站唯一的尺寸约束 img.emoji-emotion{width:28px;height:28px} 只写在 editor.css；
4. 而 editor.css 是条件加载的 —— 任何把回复框换成第三方编辑器的插件都会让它不再加载。

→ 一句话：「内容」的样式被寄存在了「编辑器资产」里，编辑器一被替换，内容就掉样式。

修复：把该规则上移到全局基座 modern.css 最末尾（editor.css 里那条保留）。 必须放末尾是因为它和 .post-text-content img 特异性完全平手，只能靠「源序在后」取胜。

顺带修好：博客详情页此前也有同样症状（核心控制器本来就没给它设编辑器标记），一并解决。

另一处：渲染白名单放行 <mark>，让编辑器的「高亮」按钮真正可用（此前会被 unwrap 成纯文本）。 属性白名单没有任何放宽。

涉及文件：app/Helpers/Content.php、assets/css/editor.css、assets/css/modern.css

V1.2.3 — 发帖 / 发博客表单布局对齐

1. 发帖页：「分类 + 标题」那一行没有下边距，「内容」二字直接贴在输入框底边。补 mn-mb-14，间距变为 14px。
2. 发博客页：标题、分类原是两个独立整行块，顺序为「标题在前、分类在后」，分类下拉还被限宽 300px。 改为合并成一行、分类在前标题在后，参数与发帖页完全一致（分类 flex:1、标题 flex:3，窄屏自动换行）。 ⚠️ 分类下拉的 mn-maxw-300 必须换成 mn-w-full，否则在 flex:1 格子里不会撑满。
3. 写博客页与编辑博客页共用同一个模板，一处改动同时覆盖两个页面。

涉及文件：app/Views/post/create.php、app/Views/blog/edit.php

V1.2.4 — 编辑器开放事件总线

修复（4 项）：

• 块级格式命令可能摧毁整个编辑区；
• 内容编码失败导致正文丢失；
• Markdown 与可视化切换后格式 / 颜色 / 表情丢失；
• Markdown 模式粘贴网页内容只剩纯文本。

新增接口：

• 三个事件：就绪、选区变化、提交前；
• 两个方法：读选区、替换选区；
• 插件可据此给编辑器加划词气泡、AI 改写、语法检查，无需改动核心。

配套改进：

• 插件拿到的选区内容带原有格式（加粗、颜色、链接），不再只剩纯文本；
• 点气泡按钮不会再插错位置：按钮点下后编辑器会记住原本选中的位置，即使光标已跳到按钮上也能准确插回；
• 站长可一键熔断：万一某个插件把编辑器搞坏，在模板里加一行 window.FLINT_EDITOR_HOOKS = false 即可关掉所有编辑器钩子，无需改插件或回滚核心。

文档：插件开发规范升至 v1.7，新增「前端编辑器事件总线」整章。

涉及文件：app/Helpers/Content.php、assets/css/editor.css、assets/js/editor.js、lang/{zh,zh_tw,en}.php、docs/插件开发规范.md

V1.2.5 — 编辑器「快捷键」按钮补回图标

现象：编辑器工具栏最后一个按钮（「快捷键」）显示为空白，按钮可点、功能正常，只是看起来像空方块。

根因：该按钮用的图标类是 .fa-keyboard-o，而 fontawesome.css 是手写的类清单（99 个）， 不是 FontAwesome 官方全量 CSS —— 里面没有这一条。.fa 只提供字体族与对齐，字形由 .fa-xxx:before { content } 提供，缺这条 → <i> 里没有任何内容 → 彻底空白。

⚠️ 要区分两种失败：完全空白 = CSS 缺 :before（本次）；显示成方块 □ = CSS 有定义但字体子集里没有该码点。 两者都不报错、控制台干净。

修复：补一行 .fa-keyboard-o:before { content: "\f11c"; }。不需要重跑字体子集化（该码点两套子集字体里都已存在）。

涉及文件：assets/css/fontawesome.css

V1.2.6 — 右栏按语义分流 + 核心兜底用户主页

① 右栏主按钮按页面语义分流

原来右栏用户卡片的按钮在任何页面都是「发帖」，在帖子详情页点它却跳去版块列表，语义错位。

显隐门禁与详情页回复框同源（回复权限 + 归档 + 删除预览 + 登录态）→ 归档帖、删除预览、 无权限版块都不渲染按钮，不会出现「点了没反应」的按钮。

② 右栏统计区按插件激活态分流

用户主页插件激活时走插件统计（含粉丝 / 关注 4 格）；未激活时走核心口径（主题 / 回复 / 浏览量 3 格）， 粉丝 / 关注整块不渲染 —— 不留「0 粉丝」这种假数据。 顺带修掉一个隐藏缺陷：统计接口原先只传作者 ID、不传访客 ID，导致按游客口径过滤（私密版块帖子数被误减）。

③ 新增核心兜底用户主页 /u/{id}

个人主页一直由插件提供，插件没装 / 没激活 / 被停用时，前台点用户名直接 404 —— 对新站和卸载插件的站点是硬伤。

核心自带一个极简用户主页：头像、用户名、等级徽章、注册时间、签名、三项统计、最近发布。

• 路由排在插件注册钩子之后 → 插件优先、核心兜底；
• ctype_digit 校验；只公开 status=active 用户；字段白名单（不含 email / password）；
• 非法 ID / 不存在 / 非 active → 显式 404。
• ⚠️ 只接管单段 /u/{id}。/u/{id}/followers、/u/{id}/threads 等子路由仍归插件，插件未激活时继续 404。

④ 详情页右栏插件面板下线（新增钩子）

对插件作者的影响：原来挂在 right_sidebar_after 上、只想在详情页显示的面板， 把钩子文件复制一份改名 right_sidebar_detail_after.php 即可，之后跑一次 Plugin::refresh()。 只想留在列表页的不用改任何东西。

⑤ 博客详情页右栏同步收敛：原先把 /blog/{id} 也当成列表页，「站点统计 / 友情链接」照样出现，现加条件区分。

涉及文件：app/Controllers/UserController.php（新）、app/Views/user/show.php（新）、app/Models/User.php、app/Views/_components/right_sidebar.php、index.php、docs/插件开发规范.md

V1.2.7 — 后台密钥加固告警全面修复

① 告警文案在「（内容为」处截断

文案里含 <?php return '你的密钥'; 代码示例，视图直接输出、没有 HTML 转义。 浏览器遇到「小于号 + 问号」进入 bogus comment（伪注释）状态，一路吞到下一个「大于号」—— 那个「大于号」正是 </li> 的。后果：两条文案都被截断（站长不知道该往文件里写什么）、 「更换密钥会导致库内既有密文无法解开」整段被吞（关键警告看不到）、列表结构被破坏。

② 为什么「设置了密钥，告警还在」

视图的显示条件是 OR：SMTP 与队列是两条独立告警，只设一条，另一条仍会让横幅整体显示。 （15 个场景实测：只设 SMTP → 仍显示；只设队列 → 仍显示；两个都设 → 才消失。）

③ 四种「设了但静默无效」的写法

旧逻辑用 require 读密钥文件，写法稍有不对就静默回落默认值（零报错、日志无记录）： 没有 return、return ''、return ' '（trim 后为空）、值恰好等于默认值。

④ 密钥文件带 UTF-8 BOM 会静默降级 session 安全配置

require 会执行文件，BOM 在 PHP 开始标签之前被输出 → headers already sent → config.php 里 6 条 session.* 的 ini_set 与 session_start() 全部失效： cookie_httponly / use_strict_mode / cookie_secure / cookie_samesite 全部没设上， 登录态丢失。而生产环境 display_errors=0，一条 warning 都看不到。

修法（四处一起）：

⑤ 新装站点误报：安装时把密钥默认值替换成随机 32 字节，但判定仍是「等于默认值」→ 新装站点恒为告警。 改为模板直接声明「不是默认值」。

⑥ 文案改写（三语同步）：标题补一句「SMTP 与队列两条需分别设置」；protected/mail_key.php / cron_key.php 提到环境变量之前（文件方式不受 PHP-FPM clear_env 影响）；明确写出「文件必须是 UTF-8 无 BOM」； 补一句「宝塔等面板的 PHP-FPM 默认 clear_env=yes，getenv() 读不到」。

涉及文件：app/Helpers/KeyGuard.php（新）、app/Controllers/Admin/DashboardController.php、app/Views/admin/index.php、index.php、install.php、lang/{zh,zh_tw,en}.php

V1.2.8 — PC 端界面优化（本区间最大一版）

本版唯一一次数据库结构变更：users 表新增 hide_left_sidebar（INTEGER DEFAULT NULL， NULL = 不收缩）。已内置到自动补列补丁里，升级后首个请求自动生效，无需手工 SQL。

涉及文件：assets/js/layout.js（新）、app/Controllers/NotificationController.php、app/Controllers/ThemeController.php、app/Helpers/Notification.php、app/Helpers/Theme.php、app/Helpers/UserPrefs.php、app/SplitDB/Schema.php、app/Views/layouts/main.php、app/Views/notifications/index.php、app/Views/theme/settings.php、app/Views/thread/show.php、assets/css/modern.css、index.php、lang/{zh,zh_tw,en}.php、docs/插件开发规范.md

V1.2.9 — 四个主题改浅色顶栏

涉及文件：assets/css/themes/modern-{crimson,ember,jade,purple}.css

V1.2.10 — 顶部 logo 去掉描述行并放大

改了什么：顶部导航左侧 logo 原来是两行（第一行图标 + 站名，第二行站点描述）。 本版去掉描述行，改为挂在 logo 链接的 title 属性上 —— 鼠标悬停由浏览器提示，移开即消失。

为什么：① 第二行在 ≤768px 本来就是隐藏的，手机上白占一行高度却看不到内容； ② 前台两行、后台单行，观感不一致；③ 站点描述在页脚与 <meta name="description"> 里都有，不必重复。

尺寸放大（≥1024px 生效）：

导航栏高度不变（高度由变量固定，logo 变矮只会垂直居中）。 769–1023px 这一档只回原尺寸、不放大（中间导航块本来就紧）。 ≤768px 完全不变（手机端图标本来就是隐藏的）。

细节：描述为空时不输出 title 属性（否则会挂一个空提示框）；描述用 HTML 转义，含双引号也不会撑破属性。

涉及文件：app/Views/layouts/main.php、assets/css/modern.css

V1.2.11 — 发帖页右栏按钮改「我的主题」

只在发帖页生效，其它页面右栏按钮一行未动。

为什么要改：

1. 在发帖页上，这个按钮是**「清空重来」**：它指向的 /post/new 就是当前页，点一下 = 重新 GET 同一路径 → 编辑器归零、版块预选丢失。
2. 它和页底「发布」按钮长得几乎一样：页底是主色 + new-post 图标，右栏这个也是主色 + 同一个图标。一个提交、一个清空，视觉上却分不出来。
3. 两个按钮只隔 6px：右栏宽 260px，面板内宽 228px，两钮各 111×28.8px，鼠标从正文移到右栏时很容易扫到。

涉及文件：app/Views/_components/right_sidebar.php

V1.2.12 — 首页标题加副标题，补回两处站名

① 首页浏览器标题增加副标题

FlintHub  →  FlintHub - 轻量级 PHP 论坛、博客系统

副标题可以在后台改：设置 → 基本信息 → 首页副标题（留空则不显示）。

② 只有首页生效：内页标题保持原样。因为内页已经是「页面名 - 站名」，再追加会变成 论坛 - FlintHub - 轻量级 PHP 论坛、博客系统（28 字符），浏览器标签页只显示前 12~15 个中文字， 后半截全被截掉，反而起不到定位作用。

③ 顺带补回两处缺失的站名（审计全站 239 处标题输出，核心 2 处缺）：

④ 顺带修掉一个真 bug：后台保存基本信息的控制器漏了清页面缓存（其它保存入口都有，只有这一个没有）， 导致改完副标题首页仍是旧标题。

涉及文件：app/Views/layouts/main.php、app/Views/admin/settings_basic.php、app/Controllers/Admin/SettingsController.php、app/Views/thread/show.php、app/Views/user/show.php、lang/{zh,zh_tw,en}.php

V1.2.13 — 修复插入图片后光标落在图片前面

现象：上传图片（工具栏选图 / 直接粘贴截图）成功后，图片插进来了，但光标停在图片之前 —— 接着打字，字会跑到图片前面去；想写在图片下方必须先手动点一下。

根因：上传占位 <span> 被 replaceChild 换成 <img> 时，按 DOM 规范，移除节点要调整所有 live Range 的边界点 —— 若起点是 (parent, offset)、被移除节点索引为 idx，则 offset > idx 时要减 1。 而插入占位时刚把光标设成「占位之后」（即 offset = idx + 1）→ 替换后 offset 被减成 idx， 正好落在图片之前。

修复：替换之前先记住「光标是否仍紧跟占位之后」，替换后只有仍满足才把光标移到图片之后。

为什么必须做这个前置判断：上传是异步的（几百毫秒到数秒）。如果无脑把光标设到图片后面， 用户在上传期间把光标移到别处，图片传完时光标会被抢回来，打字位置突然跳走 —— 那比原 bug 更难用。

覆盖范围：工具栏选图上传、粘贴单张图片、粘贴多张图片（批量）三条入口都走同一个函数，一处修好全部生效。 Markdown 模式不受影响。

验证：回归套件 10 项全部通过（正常插入 / 用户移走光标 / 上传失败 / 批量多图四类场景）。

涉及文件：assets/js/editor.js

四、升级须知

1. 数据库

只有一处结构变更：V1.2.8 给 users 表加了 hide_left_sidebar 列（INTEGER DEFAULT NULL）。 该列已内置到自动补列补丁里（带执行标记，升级后首个请求自动补），不需要手工执行 SQL。

其余 12 个版本均无表结构、索引、业务数据变更。

2. 缓存

升级后请到后台「维护 → 清理缓存」点一次。原因：首页与论坛列表页对游客是永久静态缓存 （不按时间过期），不清的话游客看到的仍是旧页面，容易误判成「升级没生效」。 （此后在后台改设置时会自动清缓存。）

3. 插件

• V1.2.6 新增钩子：原来挂在 right_sidebar_after 上、只想在详情页显示的面板，需把钩子文件复制一份改名 right_sidebar_detail_after.php，之后跑一次插件刷新。只想留在列表页的不用改。
• V1.2.1 / 1.2.4 新增的扩展点（表单挂载位、编辑器事件总线）都是纯增量，不影响已有插件。

4. 主题

若站点使用了第三方目录主题，以下改动核心不会覆盖到它，需要主题自行同步：

5. 回滚

全部为文件覆盖式升级，回滚只需把文件换回旧版即可，无副作用。 hide_left_sidebar 列留着不影响旧版本运行（旧代码不读它）。

五、附：完整变更文件清单

41 个实质文件（version.php 每版必改，已单列）

根级（3）

app/ 核心（13）

app/Views/ 视图（12）

静态资源（9）

语言与文档（4）

六、一句话总结

V1.2.0 → V1.2.13 这 13 个版本，主线是三件事：

1. 把「插件能干什么」的边界往外推 —— 表单挂载位、编辑器事件总线、右栏详情页钩子，让插件能做出更细的集成，而不用改核心；
2. 修掉一批「不报错、只有用户能感觉到」的问题 —— 表情变巨图、高亮按钮没反应、快捷键按钮空白、告警文案被吞、密钥带 BOM 静默降级 session、插图后光标跑到图片前面；
3. PC 端观感统一 —— 左栏可收起、操作收纳进「更多」、logo 精简放大、四个主题改浅色顶栏。

全程零删除文件，唯一一次数据库结构变更（新增一列）也已内置自动补列。