仿烧饼博客风格的 Typecho 主题（USB for Typecho）

aijun 仿烧饼博客 U.SB 风格的 Typecho 主题，Light / Dark 双配色

主题简介

USB for Typecho 是一款由 aijun 参照 U.SB Design 视觉风格制作的 Typecho 主题，主打简洁卡片式布局与细腻的明暗双主题。主题无 jQuery、无构建依赖、无独立后端，全部前端资源（JS / CSS / 字体 / 图片）本地内置，无任何站外资源请求，纯 Typecho 模板 + 原生 CSS/JS 实现，安装即用。

基本信息

功能特性

外观与主题

• Light / Dark 双配色，后台可设「跟随系统 / 浅色 / 深色」默认策略
• 访客可手动切换主题，选择结果记忆在本地（localStorage），未手动选择时自动跟随系统
• 深色模式下唯一强调色为金黄 #ffcc00，链接、导航、按钮整体和谐
• 平滑主题切换过渡、滚动条、Tooltip 气泡等细节打磨
• 导航栏 Logo 支持浅色 / 深色双图自动切换，可配置高度

布局与排版

• 首页 Hero 星空（星星闪烁动画 + 鼠标轨迹星星/爱心，遵循 prefers-reduced-motion 时自动禁用）
• 首页 / 归档双列文章卡片流：标题、日期、字数、预计阅读时间、摘要、标签药丸
• 完整响应式：桌面双列、移动端单列 + 汉堡菜单
• 正文 .prose 排版：正文链接淡色点线下划线、悬停波浪线高亮

文章页

• 悬浮文章目录（ToC）：宽屏侧边吸附，移动端底部按钮弹出抽屉面板
• 字数统计与预计阅读时间（中文按字、英文按词统计，约 300 字/分钟）
• 文章信息卡：标题、永久链接、作者、发布时间、最后编辑时间、版权协议、标签
• 广告位：自定义广告 HTML，留空显示默认占位广告
• 分享：Mastodon / X / Bluesky / Telegram / Email / 一键复制链接
• 上一篇 / 下一篇导航卡片
• 代码块 macOS 风格窗口化（红黄绿点 + 语言标签 + 复制按钮）

站内功能

• 站内搜索：顶部搜索按钮（快捷键 Ctrl/Cmd + K），前端实时过滤标题与摘要，索引按需加载并缓存
• RSS 订阅入口（导航按钮 + 页脚图标）
• 回到顶部（长页面滚动后出现）
• 嵌套评论，最深 6 层，回复表单随位置自动调整样式

后台与管理

• 「设置外观」页左侧悬浮选项目录 + 右侧内容按 6 组分类，字段再多也不迷路
• 主题配置支持 JSON 导入 / 导出，换主题、换机器一键迁移
• 社交链接与友情链接提供可视化编辑器，无需手写 JSON
• 页面顶部自动显示当前主题版本与发行版链接
• 兼容 XCaptcha 评论验证码插件（启用即生效，无需改主题）
• 自定义 Gravatar 头像源（国内可用 cravatar.cn 加速）

代码高亮

采用 Gruvbox 配色方案：Gruvbox Light（浅色，奶油纸底 #fbf1c7）与 Gruvbox Dark（深色，#171412）自动适应主题模式，默认跟随系统 / 站点主题，访客手动切换后同步生效。高亮库为本地内置的 highlight.js 11.9.0（assets/js/highlight.min.js），仅文章 / 独立页面加载，无需外网。

环境要求

• Typecho：1.3.x 稳定版（1.2.x 亦可，功能按 1.3 开发）
• PHP：7.4 起；推荐 8.0+（兼容 8.1 / 8.2 / 8.3）
• 数据库：MySQL 5.7+（含 8.x）、SQLite 均可
• 浏览器：现代浏览器（Chrome / Edge / Firefox / Safari 最新两个大版本）；搜索浮层与部分动效依赖 ES6+ 与 fetch
• 网络：无要求。字体、代码高亮、图片等全部资源随主题本地化，内网 / 离线环境完整可用（仅功能跳转链接如分享、备案查询需要外网）

安装与升级

安装

1. 将主题文件夹命名为 usb 上传到 Typecho 主题目录 /usr/themes/
2. 进入后台 控制台 → 外观，启用主题
3. 进入 外观 → 设置外观，按需填写配置后点击「保存设置」

升级

1. 备份当前主题配置：设置外观页顶部「导出 JSON」
2. 用新版本文件覆盖旧主题文件（主题配置保存在 Typecho 数据库中，不会被覆盖，可放心替换）
3. 如需要刷新全站静态资源缓存，仅需递增 index.php 的 @version，并强制刷新浏览器验证

页面类型

主题全部页面由 Typecho 模板机制实现，共 8 类：

公共模板：header.php（导航 / 搜索浮层 / 主题切换）、footer.php（社交栏 / 版权备案 / 返回顶部）、functions.php（主题函数与设置面板）。

顶部导航自动生成：首页 + 全部分类 + 全部独立页面，当前所在项自动高亮（文章页会高亮其所属分类）。分类与独立页面新增后无需改动模板代码。

独立页面模板

page-tags.php、page-archives.php、page-links.php 为带 @package custom 的独立页面模板，需在后台创建独立页面后指定：

1. 后台 管理 → 独立页面 → 新增
2. 填写标题（如「标签」「归档」「友情链接」），正文可留空
3. 右侧「高级选项 → 模板」下拉选择对应模板
4. 发布后访问该页面地址即可

可选细节：

• 标签云页：可用自定义字段 description 覆盖页面副标题（不填则显示默认文案）
• 归档页 / 标签页：标题下方自动显示统计数字
• 友链页：数据在「设置外观 → 友情链接」中用可视化编辑器维护，无需在页面正文编辑

后台设置

入口：外观 → 主题（仿U.SB烧饼博客）→ 设置外观。

设置页为自定义分组布局：

1. 顶部版本卡：显示「您现在使用的是 USB for Typecho {版本号}，点击查看最新发行版」，版本号自动读取 index.php 的 @version
2. 顶部「主题配置导入 / 导出」卡：导出 JSON / 导入 JSON
3. 左侧悬浮「选项目录」：6 个分组锚点，随滚动自动高亮当前位置，底部带「保存设置」按钮（按钮虽在目录内，仍与表单正确关联提交）
4. 右侧内容：按 6 组分区排布，组标题字号明显大于字段标题，层级清晰，底部另有一枚「保存设置」按钮

配置项总表

按设置页分组顺序列出全部配置项（默认值与作用说明）：

外观

站点信息

文章相关

评论

友情链接

社交链接与友情链接均以 JSON 存储于对应输入框，但请通过可视化编辑器维护（「+ 添加」/ 每行删除按钮），编辑器实时同步回输入框，保存后生效。

开发者

配置导入 / 导出

设置页顶部「主题配置导入 / 导出」卡提供两个操作：

• 导出 JSON：将上述全部配置项收集为格式化 JSON 文件下载（sb-theme-config.json），不含任何数据库敏感信息，可安全分发
• 导入 JSON：选择此前导出的 JSON 文件，导入后界面即时刷新（社交链接 / 友链编辑器立即重建显示），最后点击「保存设置」写入数据库

典型场景：切换其他主题后再启用本主题，或在新站点部署——导出 → 换主题 / 迁移 → 启用主题 → 导入 → 保存，配置即完整迁移。

前台交互说明

目录结构

usb/
├── index.php            首页：Hero + 文章卡片流 + 分页
├── archive.php          分类 / 标签 / 搜索 / 日期 / 作者归档列表
├── post.php             文章详情页
├── page.php             通用独立页面
├── page-tags.php        标签云页（独立页面模板）
├── page-archives.php    归档页（独立页面模板）
├── page-links.php       友情链接页（独立页面模板）
├── comments.php         评论模块（嵌套评论渲染 + 表单）
├── header.php           公共头部：导航 / 搜索浮层 / 主题预加载脚本
├── footer.php           公共底部：社交栏 / 版权备案 / 返回顶部
├── functions.php        主题函数、设置面板（分组布局）、主题钩子
├── screenshot.png       后台外观预览图
├── LICENSE              MIT 许可证
├── README.md            说明文档
└── assets/
    ├── css/
    │   ├── tailwind.css    预编译 Tailwind 工具类（勿手改，见开发者参考）
    │   ├── theme.css       主题设计样式：配色变量 / prose / 代码窗 / ToC / 评论等
    │   └── highlight.css   Gruvbox 代码高亮配色（Light / Dark 自适应）
    ├── js/
    │   ├── main.js             全部前端交互（原生 JS，无依赖）
    │   └── highlight.min.js    highlight.js 11.9.0 主包（本地化）
    └── fonts/
        ├── SpaceGrotesk-*.woff2    拉丁正文字体（400/500/600/700，本地化）
        └── IoskeleyMono-*.woff2    等宽字体（正文代码 / 等宽文本用）

常见问题（FAQ）

Q：切换主题后再启用，后台配置还在吗？
切换其他主题，再启用本主题；跨站点迁移均需要用「导出 JSON / 导入 JSON」。

Q：导入 JSON 后为什么社交链接 / 友链没显示？
导入成功即应立即显示（编辑器会即时重建）；若数据无变化，请确认导入的是本主题导出的 JSON 且键名完整，然后点击「保存设置」写入数据库——刷新页面后才从数据库读取。

Q：为什么我的文章没有目录 / 分享复制等？

• 目录：需要正文含至少 2 个 H2~H6 标题，且后台「文章目录」开启；H1 不进目录
• 代码窗口化：仅作用于 .prose 内的 <pre>；复制依赖 clipboard API，非 HTTPS 环境可能回退失败（提供 execCommand 兜底）

Q：代码高亮不生效？
高亮由本地内置的 highlight.js（assets/js/highlight.min.js）触发，仅文章 / 独立页面加载，无需外网。若文章代码未高亮，请确认该页面 pre code 语言类写法正确（`language-xxx 围栏），并强制刷新浏览器。

Q：评论头像不显示？
默认 Gravatar 源为 https://gravatar.com/avatar，国内访问不稳时，在「设置外观 → 评论 → Gravatar 源」改为 https://cravatar.cn/avatar 即可。

Q：如何修改首页每页文章数？
后台「设置 → 阅读 → 每页文章数目」，主题自动跟随（首页与归档列表均生效）。

Q：正文样式想微调 / 加统计代码？
优先使用「开发者」分组：自定义 CSS（head 内 style）、自定义 HTML（head）、自定义 body 底部 HTML（</body> 前，可放统计 / 客服脚本），无需改模板。

Q：主题文件夹叫什么名字？
发布包名 usb。后台「外观」列表中主题名取 index.php 的 @package，与文件夹名无关；导入导出 JSON 亦与文件夹名无关。

更新记录

1.0.1（当前）

• 全站资源本地化：移除 Google Fonts @import 与 highlight.js CDN 引用，字体 / 高亮库 / 广告占位图全部下载到主题 assets/ 内
• 静态资源 URL 追加 ?v= 版本参数（版本号唯一来自 index.php 的 @version，由 sb_theme_version() 读取），升级后递增即可刷新访客缓存
• 后台「设置外观」改版：顶部版本提示卡 + 配置导入 / 导出卡置顶；左侧悬浮「选项目录」+「保存设置」；内容按 外观 / 站点信息 / 文章相关 / 评论 / 友情链接 / 开发者 6 组分区
• 社交链接与友情链接可视化编辑器支持导入配置后即时重建显示
• 新增深色 Logo 独立配置（logoImgDark）；移除「站点统计代码」字段（可用开发者组自定义 body HTML 实现）
• 若干细节修复：标签云页样式外置、分享 tooltip 遮挡、深浅主题下部分配色与层级问题

1.0.0

• 首个发布版本：完整页面体系、Light/Dark 双主题、搜索 / ToC / 代码高亮 / 分享 / 星空等全部特性

许可说明

主题代码采用 MIT License，详见主题内 LICENSE 文件。设计风格参照 U.SB，Ioskeley Mono 字体版权归其作者所有，请按需确认再行分发。