# LanternPress

**Repository Path**: muzinext/LanternPress

## Basic Information

- **Project Name**: LanternPress
- **Description**: 一款经典报纸复古风 Typecho 主题，内置文章点赞、阅读量统计、目录树、模态框搜索、跟随系统主题色、归档 / 友链 / 标签云三大独立页面模板，支持瀑布流加载、图片灯箱、代码高亮复制。性能上实现懒加载、内容缓存、数据库优化；安全上配备 CSP、HSTS、XSS 防护与接口速率限制。适配 PHP 8 与 Typecho 1.3.0+，全站响应式布局。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://muzihome.com/archives/271.html
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-06
- **Last Updated**: 2026-10-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LanternPress 主题

一款经典报纸复古风 Typecho 主题，适配 PHP 8 与 MySQL 8。

> 作者：木子小鱼

> 项目地址：https://github.com/muzihome/LanternPress

> 当前版本：v2.4.0

> 更新日志：[LOG.md](./LOG.md)

---

## 目录

- [主题介绍](#主题介绍)
- [功能特性](#功能特性)
- [环境要求](#环境要求)
- [安装方法](#安装方法)
- [主题配置](#主题配置)
- [文章自定义字段](#文章自定义字段)
- [独立页面模板](#独立页面模板)
- [常见问题](#常见问题)
- [更新日志](#更新日志)
- [开源许可](#开源许可)

---

## 主题介绍

**LanternPress** 是一款经典报纸复古风 Typecho 主题，基于 LanternTown 二次开发。内置文章点赞、阅读量统计、目录树、模态框搜索、跟随系统主题色、归档 / 友链 / 标签云三大独立页面模板，支持瀑布流加载、图片灯箱、代码高亮复制。性能上实现懒加载、内容缓存、数据库优化；安全上配备 CSP、HSTS、XSS 防护与接口速率限制。适配 PHP 8 与 Typecho 1.3.0+，全站响应式布局。

**版本对比：**

| 项 | 原始 LanternTown v1.0.0 | 当前 LanternPress v2.4.0 |
|---|---|---|
| 文件数 | 30 | 32 |
| 配置项 | 12 | 30 |
| 独立页面模板 | 0 | 3 |
| 文章交互功能 | 基础 | 点赞、阅读量、目录树、灯箱、代码复制 |
| 无障碍 | 无 | 跳转链接、键盘焦点轮廓、ARIA 语义（WCAG 2.1 AA 对比度） |
| PWA | 无 | Web App Manifest、SVG 主题图标 |

---

## 功能特性

### 视觉与主题
- 经典报纸复古风格设计，5 种主题色可选（复古黄 / 纯白色 / 灰白色 / 暗夜黑 / 跟随系统）
- 「跟随系统」模式自动根据浏览器/系统深色偏好切换明暗主题
- 首页图片支持灰白/彩色两种显示模式
- 响应式布局，适配桌面、平板、手机
- 移动端导航菜单样式统一，搜索按钮与菜单项风格一致

### 文章功能
- **阅读量统计**：Cookie 防刷，24 小时内同一文章只计一次
- **点赞功能**：AJAX 无刷新，Cookie 防重复（1 年内不可重复点赞），IP 速率限制防刷
- **文章目录树**：可按文章单独开启/关闭，移动端（≤767px）不加载目录树模块，避免小屏布局错乱
- **图片灯箱**：原生 JS 实现，点击放大查看，支持分组画廊循环、键盘左右切换与缩放，已在链接内的图片不重复包裹
- **代码高亮**：Prism.js 实现，支持行号显示、一键复制、语言标签
- **段首缩进**：文章正文段首自动缩进 2 个字符
- **图片懒加载**：原生 `loading="lazy"` + IntersectionObserver 双重保障
- **上下篇导航**：复合条件排序，避免时间戳相同时漏篇
- **文章页增强**：版权声明、作者简介、打赏二维码、社交媒体链接、阅读时长估算、字数统计
- **内容处理缓存**：文章内容处理结果数据库缓存，配置变更自动失效，长文章性能提升明显

### 首页功能
- **推荐文章轮播**：原生 JS 实现（自动播放、触摸滑动、循环切换），支持自定义推荐文章 ID
- **最新文章列表**：支持缩略图、摘要、阅读量、点赞数
- **两种翻页模式**：页码翻页 / 瀑布流加载更多（AJAX 无刷新，15 秒超时保护）
- **自定义导航菜单**：支持 `名称|URL` 格式，留空自动显示独立页面
- **模态框搜索**：点击「搜索」居中弹出，输入框与按钮主题色统一

### 评论功能
- **AJAX 无刷新提交**：事件委托模式，DOM 替换后无需重新绑定，避免内存泄漏
- **头像镜像代理**：支持 Gravatar 及自定义镜像地址，解决国内访问慢的问题
- **嵌套评论**：支持多级嵌套回复
- **表单智能填充**：autocomplete 属性，浏览器自动填充姓名/邮箱/网址
- **XSS 防护**：评论内容统一 HTML 转义，防止存储型 XSS

### 独立页面模板
- **归档页**：按年份/月份归档所有文章，带文章数量统计，数据自动缓存
- **友链页**：展示友情链接，支持 Markdown 列表格式
- **标签云**：展示所有文章标签，按使用频次显示不同大小

### 性能优化
- **图片懒加载**：IntersectionObserver 单例实现，避免重复创建 observer 导致内存泄漏
- **资源预加载**：preload / preconnect，加速关键资源加载
- **数据缓存**：归档页文件缓存，文章发布时自动清除
- **数据库优化**：字段操作请求内静态缓存、单条 SQL upsert、推荐文章批量查询
- **原子递增**：阅读量/点赞使用 SQL 原子递增（`INSERT ... ON DUPLICATE KEY UPDATE int_value = int_value + 1`），避免高并发竞态条件
- **AJAX 片段请求**：瀑布流加载更多只请求文章列表片段，减少整页流量
- **图标缓存**：SVG 数组静态缓存，避免重复构建
- **请求超时**：fetch 请求 15 秒 AbortController 超时控制
- **内容缓存**：文章内容处理结果文件缓存（`cache/content/{cid}.php`），结构版本化失效，不再占用数据库 fields 表
- **按需加载**：Prism 代码高亮仅在正文含代码块/围栏时加载，无代码文章零开销
- **首屏优化**：首屏首张卡片缩略图即时渲染、正文首图 `fetchpriority="high"`，改善 LCP

### 安全加固
- **安全响应头**：CSP / X-Frame-Options / X-Content-Type-Options / Referrer-Policy
- **HSTS**：HTTPS 站点自动启用 Strict-Transport-Security
- **速率限制**：点赞接口 IP 速率限制（10 秒内最多 5 次），flock 文件锁避免并发竞态
- **XSS 防护**：全局 HTML 输出转义
- **URL 校验**：防止 javascript: / data: 协议注入
- **目录保护**：缓存目录 `.htaccess` 保护，防止直接访问
- **可信代理**：IP 获取支持可信代理白名单（`LT_TRUSTED_PROXY_IPS`），防止客户端伪造 IP 绕过速率限制

### 其他特性
- **全站国际化**：`_t()` / `_e()` 支持，便于多语言翻译
- **自定义 CSS/JS**：后台直接填写，无需修改主题文件
- **统计代码注入**：支持百度统计、Google Analytics 等
- **双备案显示**：ICP 备案号 + 公安备案号（自动链接至 beian.mps.gov.cn）
- **返回顶部**：平滑滚动按钮
- **阅读进度条**：文章页顶部显示阅读进度
- **移动端优化**：菜单点击链接后自动关闭、目录树浮动按钮、搜索模态框

---

## 环境要求

| 项目 | 最低版本 | 推荐版本 |
|---|---|---|
| Typecho | 1.2.0 | 1.3.0 |
| PHP | 8.0 | 8.2 / 8.3 / 8.4 |
| MySQL | 5.7 | 8.0 |
| 浏览器 | - | Chrome / Edge / Firefox / Safari 最新版 |

> 本主题已在 **PHP 8.2 + Typecho 1.3.0 + MySQL 8** 环境下充分测试。

---

## 安装方法

### 方法一：直接上传（推荐）
1. 下载主题压缩包
2. 解压后将 `LanternPress` 文件夹上传到 Typecho 主题目录 `usr/themes/`
3. 登录 Typecho 后台 → 外观 → 启用「LanternPress」主题
4. 点击「设置外观」进行主题配置

### 方法二：Git 克隆
```bash
cd /path/to/usr/themes/
git clone https://github.com/muzihome/LanternPress.git
```
> 注意：源码仓库（Git）内的 `assets/css/` 为可读的未压缩版（`lantern.css` / `iconfont.css`），而模板引用的是压缩版文件名（`*.min.css`）。**Git 克隆后需先在本机执行构建**再部署，否则 CSS 无法加载：
> ```bash
> php .build/deploy-sync.php    # 生成压缩 CSS/JS 并同步到部署目录
> ```
> 发布压缩包与测试站均使用构建产物，下载压缩包直接上传无需此步骤。

### 目录权限
确保缓存目录可写（归档缓存、点赞限流、文章内容文件缓存均写入此目录，`cache/content/` 会自动创建）：
```bash
chmod 755 usr/themes/LanternPress/cache
```

#### Web 服务器防护
`cache/` 下均为 PHP 运行时产物（含 `<?php exit; ?>` 前缀），Apache 已由内置 `.htaccess` 拒绝直接访问；**Nginx 不会读取 `.htaccess`**，必须在站点配置中显式拒绝：
```nginx
location ^~ /usr/themes/LanternPress/cache/ {
    deny all;
    return 403;
}
```
建议同时为带版本号参数的静态资源开启长缓存（主题已通过 `?v=` 版本号解决更新失效问题）：
```nginx
location ~* ^/usr/themes/LanternPress/assets/ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}
```

---

## 主题配置

登录后台 → 外观 → 设置外观，可配置以下 30 个选项：

### 基础设置
| 配置项 | 说明 |
|---|---|
| 站点 LOGO 地址 | 填写图片 URL，在网站标题处显示 LOGO |
| 海报 LOGO 地址 | 生成文章海报时使用的站点 LOGO；留空自动选用导航栏 LOGO / 站点 LOGO / JSON-LD LOGO |
| favicon 地址 | 网站图标地址 |
| 自定义导航菜单 | 每行一个，格式：`名称\|URL`，留空自动显示所有独立页面 |
| 首页推荐阅读 | 推荐文章 ID，用 `\|\|` 分隔，如：`3\|\|4` |
| 首页文章图片 | 每行一张图片 URL，按文章 ID 稳定分配 |
| 首页图片是否默认灰白显示 | 灰白 / 彩色 |

### 显示设置
| 配置项 | 说明 |
|---|---|
| 翻页模式 | 页码翻页模式 / 加载更多（瀑布流 AJAX） |
| 主题色 | 复古黄 / 纯白色 / 灰白色 / 暗夜黑 / 跟随系统 |
| 文章页布局 | 右侧边栏（默认）/ 左侧边栏 / 无侧边栏；移动端（≤1150px）自动转单列 |
| 长文折叠 | 开启后正文高度超过「折叠阈值」时折叠显示，点击「阅读剩余 X%」展开；仅影响前端显示，不影响 SEO |
| 折叠阈值(px) | 正文实际高度超过此值才触发折叠，默认 2000 |
| 折叠显示高度(px) | 折叠后保留的正文高度，默认 1500；移动端自动按视口折算 |
| 最小剩余比例(%) | 折叠后剩余内容占比低于此值时不折叠，默认 20 |
| 文章页侧边栏模块 | 多选：文章目录 / 搜索框 / 微言 / 广告位 / 分类目录 / 最新文章 / 热门文章 / 最新评论 / 标签云 / 站点信息；未配置时默认全部显示 |
| 侧边栏微言 | 一行一条，格式：日期\|内容（如：09-05\|把复杂的事情做简单）；留空隐藏该模块 |
| 侧边栏广告位 | 自定义 HTML/文本，展示在文章页侧边栏；留空隐藏（建议尺寸 360×250） |
| 文章底部广告位 | 自定义 HTML/文本，展示在文章正文底部（工具栏与上/下一篇导航之间）；留空隐藏 |
| 版权声明 | 在文章结尾显示版权声明 |
| 作者简介 | 在文章结尾显示作者简介 |
| 一句话自我介绍 | 展示在文章页作者介绍处 |
| 打赏收款二维码 | 二维码图片地址，一行一个，最多两个 |
| 社交媒体链接 | 格式：`名称:url:链接` 或 `名称:qr:二维码地址` |
| 自定义页脚文案 | 留空显示默认版权信息，填写后替换页脚第一行 |

### 备案设置
| 配置项 | 说明 |
|---|---|
| 备案号 | ICP 备案号，如：`桂ICP备XXXXXXXX号` |
| 公安备案号 | 公安备案号，自动链接至 beian.mps.gov.cn |

### 高级设置
| 配置项 | 说明 |
|---|---|
| 自定义 CSS | 原样输出到 `<style>` 中，可覆盖主题样式 |
| 自定义 JS | 原样输出到页脚 `<script>` 中；在主题脚本（lantern.core.js）加载前执行，请勿依赖主题脚本对象（如 `window.Lantern`） |
| 统计代码 | 原样输出到页脚，支持直接粘贴统计站点代码 |
| 头像镜像地址 | Gravatar 代理地址，如 `https://cravatar.cn/avatar/` |

---

## 文章自定义字段

在文章编辑页面的「自定义字段」中可设置：

| 字段名 | 类型 | 说明 |
|---|---|---|
| articleDesc | 文本 | 文章摘要，展示到首页；不填写则默认取文章前 130 字 |
| bannerUrl | 文本 | 文章主图 URL，用于首页缩略图和文章页顶部 |
| directoryStatus | 下拉 | 是否开启文章目录树：`off`（关闭，默认）/ `on`（开启） |

---

## 独立页面模板

创建独立页面时，在「自定义模板」中选择：

### 归档页（archive-template.php）
- 按年份/月份归档所有已发布文章
- 显示每个月的文章数量
- 数据自动缓存，文章发布/修改时自动更新

### 友链页（flinks-template.php）
- 在页面内容中按以下格式填写友链：
```markdown
- [站点名称](https://example.com) - 站点描述
- [另一个站点](https://example2.com) - 另一个描述
```

### 标签云页（tagcloud-template.php）
- 自动展示所有文章标签
- 标签大小按使用频次自动调整
- 点击标签跳转到对应标签的文章列表

---

## 常见问题

### Q：点赞功能点击无反应？
A：检查以下几点：
1. 确保主题已启用且 functions.php 已正确加载
2. 检查浏览器控制台是否有 JS 报错
3. 确认 `cache` 目录可写（速率限制需要写入缓存）
4. 同一文章 1 年内只能点赞一次（Cookie 限制），清除 Cookie 后可重新点赞
5. 点赞接口有 IP 速率限制（10 秒内最多 5 次），频繁点击会被限流

### Q：归档页不更新？
A：归档页使用文件缓存，文章发布/修改/删除时会自动清除缓存。如手动修改了数据库，可删除 `usr/themes/LanternPress/cache/archive-cache.php` 文件手动清除。

### Q：Gravatar 头像加载慢？
A：在主题配置中填写「头像镜像地址」，推荐使用：
- `https://cravatar.cn/avatar/`
- `https://gravatar.loli.net/avatar/`
- `https://cdn.v2ex.com/gravatar/`

### Q：如何添加友链？
A：创建独立页面，选择「友链页」模板，在页面内容中按以下格式填写：
```markdown
- [站点名称](https://example.com) - 站点描述
- [另一个站点](https://example2.com) - 另一个描述
```

### Q：自定义导航菜单如何配置？
A：在主题配置的「自定义导航菜单」中，每行填写一个菜单项，格式为 `名称|URL`：
```
首页|/
归档|/archives.html
关于|/about.html
谷歌|https://google.com
```
留空则自动显示所有已发布的独立页面。

### Q：瀑布流「加载更多」不工作？
A：检查以下几点：
1. 确认翻页模式设置为「加载更多」
2. 检查浏览器控制台是否有 JS 报错
3. 确认服务器支持 AJAX 请求（返回 `from=ajax` 参数时只输出文章列表片段）
4. 网络异常时请求 15 秒超时，按钮会显示「请求超时，请重试」

### Q：文章内容修改后页面没有更新？
A：v2.3.0 起文章内容处理结果使用文件缓存（`cache/content/{cid}.php`），带结构版本校验。文章发布/修改时会自动删除对应缓存；v2.4.0 起内容缓存结构版本 `LT_CONTENT_CACHE_VERSION` 由正文处理相关文件（`inc/core.php` / `functions.php` / `post.php` / `sidebar.php`）的修改时间自动派生——主题升级修改了正文处理逻辑后全站缓存自动一次性失效，无需手动递增版本号。如手动修改了数据库，可删除 `cache/content/` 下对应 cid 文件，或清空整个目录（会自动重建）。
> 从 v2.2.x 升级时，历史缓存残留在数据库 `fields` 表（`name='ltProcessedContent'`），不再被读取；确认站点正常后可执行一次清理：`DELETE FROM typecho_fields WHERE name='ltProcessedContent';`（表前缀按实际调整）。

### Q：如何配置可信代理白名单？
A：在 Typecho `config.inc.php` 中添加：
```php
define('LT_TRUSTED_PROXY_IPS', ['127.0.0.1', '代理服务器IP']);
```
定义后，仅当直连对端（`REMOTE_ADDR`）属于白名单时，才采信其带来的 `X-Forwarded-For` / `X-Real-IP` 头，防止客户端伪造 IP 绕过点赞速率限制。**未定义时默认不信任任何转发头**，一律使用 `REMOTE_ADDR`。
> 反向代理（Nginx/CDN）后部署的站点必须配置此项，否则所有访客的 IP 都会被识别为代理服务器地址，导致点赞速率限制全员共享。

### Q：如何升级主题？
A：备份当前主题目录 → 覆盖新版本文件 → 登录后台 → 外观 → 禁用后重新启用主题 → 检查配置项是否完整 → 清除 OPcache。

---

## 更新日志

更新日志请查看 [LOG.md](./LOG.md)。

**近期版本：**
- **v2.4.0**（2026-10-02）：文章页底部布局重构（7 分享工具栏 + 阅读/评论/收藏统计 + 相关推荐且不推荐自己 + 生成海报）；后台新增「文章页侧边栏模块」多选（10 模块）；侧边栏去除内部滚动条、文章目录样式与页面协调
- **v2.3.0**：正式发布版——安全加固（点赞 CSRF、评论令牌、缓存格式加固）；首页轮播 4 秒自动 + 控制按钮悬停显示/离开消失；移动端文章页/独立页不再加载目录树；Web App Manifest 与主题图标；无障碍（跳转链接、键盘焦点、对比度、减弱动态效果）；内容文件缓存、列表查询优化、Prism 按需加载、LCP 优化、限流 GC；全站唯一 h1、结构化数据、归档描述、feed/搜索路由化；Typecho 1.3.0 与 PHP 8.2+ 适配
- **v2.2.2**：热修版——首页轮播 resize 冻结兜底、卡片键盘委托守卫、克隆幻灯片懒加载、搜索页 noindex、部署脚本失败不写盘与 cache 运行时文件保护
- **v2.2.1**：Typecho 1.3.0 规范与 PHP 8.2+ 全面审查修复（密码保护链路、三方言 upsert、安全响应头、搜索关键词取值等）
- **v2.2.0**：第三方库原生 JS 化（移除 jQuery/Headroom/Swiper/Fancybox/ClipboardJS，保留 Prism），目录结构整合（partials/、assets/vendor/）
- **v2.1.6**：上线前最终审查修复（移除未使用导入、版本号统一）
- **v2.1.5**：第三次代码审查 5 项修复（PHP 7.4 兼容、版本号同步、CSS 注入防护、文章存在性校验）
- **v2.1.4**：README 重写与 FAQ 补充
- **v2.1.3**：移除 lantern.config.js 的 preload，消除浏览器警告
- **v2.1.2**：修复文章列表缩略图空值处理
- **v2.1.1**：代码审查 5 项修复（原子递增、配置哈希、flock锁、可信代理、点赞超时）

---

## 开源许可

本主题基于原始作者 TypeRenew/Yangsh888 的 LanternTown 主题二次开发，遵循原始项目许可证。

二次开发部分由[木子小鱼](https://muzihome.com)维护，欢迎提交 [Issue](https://github.com/muzihome/LanternPress/issues) 和 [Pull Request](https://github.com/muzihome/LanternPress/pulls)。

**项目地址：** [https://github.com/muzihome/LanternPress](https://github.com/muzihome/LanternPress)

**备用地址：**[https://gitee.com/muzinext/LanternPress](https://gitee.com/muzinext/LanternPress)