Robes Typecho 主题2.7.1

毛玻璃风格 Typecho 主题 · 版本 2.7.1 · 适用 Typecho 1.2 及以上

Robes 是一套偏「个人小站」的毛玻璃主题：左侧栏常驻、顶栏集中了通知面板与小站，文章页自带目录与阅读体验优化，评论侧做了无感人机验证和邮件提醒，另外还带友圈、相册、友链墙、归档、留言板这些独立页面模板。

一、特性总览

二、环境要求

三、安装与首次配置

3.1 安装

1. 后台 → 外观 → 安装主题 → 上传 Robes-2.7.1.zip。
2. 压缩包内顶层目录必须叫 robes，不要改名：主题里有几处路径写死了这个目录名，改名会导致评论验证和私密评论失效。
3. 启用主题，访问一次首页，让主题自动创建缓存目录。

3.2 首次配置检查清单

• 基础：Logo、底部版权、备案号、Favicon、建站日期
• 外观：确认强调色与背景色，圆角与模糊度按喜好调
• 布局：深色模式选「跟随系统」或「用户切换」
• 功能：设置首页图片位来源（建议「文章封面」）、相册分类 ID
• 内容：写一条站内公告、一句站长心情
• 社交：按需填写，留空不显示
• 页面：建好六个独立页面（见第十章）

升级提示：主题设置存在数据库里，覆盖文件不会丢；漂流瓶内容在 usr/cache/notice/bottles.json，升级前备份这一个文件即可。

四、外观与布局

4.1 可调项

4.2 实现方式

所有外观参数由 functions.php 的 themeCSSVars() 输出成 :root 上的 CSS 变量（如 --accent、--glass-blur、--sidebar-w），样式表统一引用变量，所以改一处全站生效，不需要重新编译或上传样式文件。深色模式配色写在 css/base.css 的 html.dark 里。

五、首页与图片位

5.1 图片位三种来源

5.2 交互细节

• 轮播背景是双层结构，交叉淡入切换，不闪白。
• 图片位左上角有实时天气，按访客 IP 自动定位城市，显示描述、温度、体感、湿度、风向。
• 首页卡片图片懒加载渐显（IntersectionObserver），滚动时顶部有渐变遮罩。

5.3 天气实现

前端请求 extras/weather.php，服务端先按 IP 做地理定位（结果缓存 7 天），再请求天气：首选 Open-Meteo（免密钥），失败回退 wttr.in；天气结果缓存 20 分钟，请求失败时缓存 2 分钟避免反复重试。整个过程由服务端代理，不把第三方接口暴露给浏览器。

六、通知面板

顶栏铃铛打开的面板分四个标签页。

实现方式

• 公告在服务端解析，不占用数据库。
• 评论数据由 notice.php 提供，只接受 count / list / read / seen 四个动作，其余一律拒绝。
• 已读状态写在站点 usr/cache/notice/ 下（seen_*.txt 记录水位、read_*.json 记录逐条已读），不污染评论表。

七、小站：站长心情与漂流瓶

7.1 站长心情

设置里的「站长心情」一句话，显示在小站顶部，并自动带当天日期；留空显示默认文案。

7.2 漂流瓶

• 「捞一个」随机取一条别人的瓶子，可以连续捞。
• 「扔个瓶子」昵称可留空（最多 12 字），正文最多 120 字，实时字数统计。
• 数据落在站点 usr/cache/notice/bottles.json，最多保留 400 条。

7.3 防滥用规则

• 同一 IP 两次投掷间隔 45 秒，每天最多 20 条。
• 写入用 flock 串行化，避免并发写坏 JSON。
• 空内容、超长内容直接拒绝，返回中文提示。

迁移：新站想延续老站的瓶子，把老站的 usr/cache/notice/bottles.json 复制到新站同路径即可，不需要导数据库。

八、文章页

目录、灯箱、分享、进度都在 js/article.v2.js 与 js/main.v2.js 里实现，不依赖任何前端框架。

九、评论体系

9.1 无感人机验证（默认开启）

页面打开时静默向 verify/verify.php?action=challenge 申请一个签名 token，并附带一道轻量计算题（PoW）；提交评论时连同答案一起校验。用户全程无感知，脚本刷评论则需要付出计算成本。token 的签名密钥由站点配置派生，换域名或改配置后旧 token 自动失效，属于正常现象。

9.2 私密评论（可选）

开启后评论框多一个「私密」勾选：勾选的评论只有作者本人和管理员可见，其他人看到占位提示。实现上给评论表自动补一个 private 字段（全新安装也会自动补列），并用 robes_priv Cookie 记住访客身份，不需要改 Typecho 核心。

9.3 评论邮件通知（可选）

先启用模块：在站点根目录 config.inc.php 末尾追加

$__robesCommentMail = __TYPECHO_ROOT_DIR__ . '/usr/themes/robes/comment-mail/bootstrap.php';
if (is_file($__robesCommentMail)) require_once $__robesCommentMail;

然后到 外观 → Robes 设置 → 邮件通知 填 SMTP：

模块内置 PHPMailer，新评论与回复提醒各有一套模板；未配置 SMTP 时回退 mail()，多数虚拟主机禁用了这个函数，表现就是「发送成功但收不到」。

9.4 其他

• 访客可以删除自己刚发布的评论（js/comment-del.js）。
• 评论提交后局部刷新评论区，不整页跳转。

十、独立页面

这六个模板不会自动出现，需要新建页面后在右侧「自定义页面模板」里选择。

创建步骤：后台 → 管理 → 新建页面 → 填标题与内容 → 右侧「自定义页面模板」选择对应文件 → 发布。

10.1 友圈

读取 links 表里的友链地址，抓取各站 RSS，缓存 7 天；抓取失败保留旧数据、1 小时后重试；完全没有可用链接时显示空状态，不会报错。

10.2 相册

把要展示的文章归到一个分类（例如 ID 6），在设置里把「相册分类 ID」填成该分类，相册页就会按文章封面与正文图片生成瀑布流。

10.3 友链在线检测

开启后友链卡片会带在线状态：浏览器端先做一次探测，再调用本地接口 extras/api-link-check.php，服务端用 curl_multi 并发检测（每批 8 个），整体几秒内返回；结果在浏览器缓存 1 小时。设置里可整体关闭。

十一、完整设置项对照表

十二、自定义样式示例

把下面代码粘到「自定义 CSS」即可，不需要改主题文件：

/* 让卡片更不透，标题字号略大 */
:root {
  --glass-opacity: 0.62;
  --radius-md: 16px;
  --text: #222831;
}

/* 隐藏页脚署名（也可以用设置项关闭） */
.theme-credit { display: none !important; }

自定义 JS 适合放统计代码、第三方评论等，注入位置在页脚脚本之后，可以直接使用 window.ROBES 里的配置（如 ROBES.themeUrl）。

十三、缓存、性能与 CDN

• 静态资源统一带 ?v=版本号 参数，改版本号即全站换新地址，避免浏览器缓存。
• CSS 按页面按需加载，非首屏样式用 media="print" 延迟应用；首屏关键资源做了 preload。
• 主题运行数据统一在站点 usr/cache/notice/：公告已读、漂流瓶、友圈 RSS、文章解析缓存。
• 若套了 CDN，升级后记得刷新 HTML 与 CSS/JS 缓存，否则页面引用的还是旧版本。

十四、升级与迁移

1. 备份 usr/cache/notice/（漂流瓶与已读状态）和数据库。
2. 解压新包，把整个 robes 目录覆盖到 usr/themes/robes。
3. 后台确认主题仍是启用状态；设置项存在数据库，不会丢。
4. 刷新首页，确认资源版本号已变化。
5. 新站要延续数据，把备份的 bottles.json 放回新站同路径。

十五、常见问题

改了颜色/宽度没生效？ 设置保存后强制刷新一次；套了 CDN 需要刷缓存。宽度只填数字，带不带 px 都可以。

后台版本号还是旧的？ 后台显示的是 index.php 头部的 @version，覆盖文件刷新页面即更新。

首页天气一直是「加载中」？ 检查 extras/weather.php 是否能访问、PHP 是否有 curl；服务器无法访问外网时该块会自动隐藏，不影响排版。

友链状态一直灰的？ 确认设置里「友链检测」开启，且 extras/api-link-check.php 可访问；部分站点有防火墙，检测失败属正常。

友圈空白？ 先装友情链接插件并添加几条链接，友圈只聚合 links 表里的站点。

漂流瓶扔不出去？ 同一 IP 45 秒一条、每天 20 条上限，超限会提示稍后再试；确认 usr/cache/notice/ 可写。

评论提示验证过期？ 换域名、改配置或清理 Cookie 后旧 token 会失效，刷新页面重新获取即可。

邮件发送成功但收不到？ 多半是用了 mail() 被主机拦截，改填 SMTP；QQ、163 必须用授权码，且发件人地址要和 SMTP 账号一致。

相册页没有图片？ 检查「相册分类 ID」是否填对，且该分类下文章有封面或正文图片。

十六、目录结构

robes/
├── functions.php          # 设置项、CSS 变量、SEO、JSON-LD
├── header.php             # 顶栏、通知面板、小站
├── footer.php             # 页脚、移动端 Tab 栏、脚本引入
├── sidebar.php            # 侧栏
├── index.php              # 首页
├── post.php               # 文章页
├── comments.php           # 评论区
├── notice.php             # 通知面板接口
├── bottle.php             # 漂流瓶接口
├── comment-private.php    # 私密评论
├── verify/                # 评论无感验证（token + PoW）
├── comment-mail/          # 评论邮件通知（含 PHPMailer）
├── extras/
│   ├── weather.php        # 天气接口（IP 定位 + 多源回退）
│   └── api-link-check.php # 友链并发检测（curl_multi）
├── css/                   # base / home / components / article / pages / ri
├── js/                    # main / home / article / comment-del / vibe / pow-worker
├── fonts/                 # 内置 ZQL 字体子集
├── img/                   # 图标等静态资源
└── admin/                 # 设置页 UI 模板

十七、开发者备注

• 版本号：functions.php 顶部 ROBES_ASSET_VER，改它可以让全部静态资源换新 URL。
• 配色变量：css/base.css 的 :root 与 html.dark 两段，改动即时生效。
• 主题目录名固定为 robes，header.php、notice.php、verify/verify-core.php 里有硬编码路径。
• 接口都做了动作白名单与来源校验，新增接口请沿用 verify/ 与 notice.php 的写法。