OneBlog 主题使用文档

作者寄语：我相信大多数博主都跟我一样，对于自己的博客花园秉持着“纵一文不值，也千金不换”的态度。因为这里，承载着我们太多的东西。特别是坚持写下去的博主，在博客中记录，或许是另一种意义上的信仰。我认为，在当下这种浮躁而虚无的生活节奏中，这种信仰很可贵。多年之后，我们回首自己的一生，不该是虚无缥缈的，而应该是真正存在过。那些物质的东西，都会随着时间慢慢销蚀，而我们写下的文字，最趋近于永恒。希望你在用上这款主题之后，不忘初心，坚持把自己的博客写下去。

版权声明

本主题由彼岸临窗设计编写，并已取得中华人民共和国国家版权局颁发的计算机软件著作权登记证书（登记号：2025SR0334142）和外观设计专利证书（证书号：第7121519号），作者保留所有权利。致敬开源，本主题自2025年1月1日起，以GPL-2.0协议授权广大用户免费使用。任何个人或单位在注明来源的基础上，均可以免费无偿使用本主题，但不得以任何形式售卖（包括但不限于以付费下载、积分购买、vip用户可见等形式向用户提供下载链接，下同），否则视为侵权。基于GPL-2.0协议，本主题允许在保留来源（同时包含署名和链接）的基础上对源代码进行修改，但修改后的源码只能自己使用或免费开源，不得以任何形式售卖。

环境配置

1.服务器环境

推荐使用Linux系统、PHP8.2，Mysql8.0，Ngnix1.24，该环境为开发测试阶段以及主题官网的稳定运行环境，其他环境未作兼容性测试，但不影响正常使用。如有问题，请在Github官方仓库提issue。

2.Typecho版本

本主题基于Typecho1.3开发，请在下载本主题之前安装好Typecho官方稳定版。如果你使用的是Typecho旧版本，请自行解决兼容性问题。为了安全性和稳定性考虑，后续主题的更新只可能适配Typecho最新版本。

如果你还未安装Typecho，请前往Typecho官网下载安装。

3.服务器推荐

如果你想要新购国内服务器，推荐前往腾讯云最新活动选取合适的机器。

如果你想新购免备案境外服务器，推荐前往云岭星算选取合适的机器。

安装主题

1. 下载主题
   前往 GitHub 仓库 下载最新版本的主题压缩包。国内用户也可使用 GitCode 镜像仓库。
2. 上传主题
   将下载的主题文件夹重命名为 OneBlog，上传到 Typecho 安装目录下的 usr/themes/ 目录中。
3. 确认目录结构
   确保目录结构为 usr/themes/OneBlog/...，而非 usr/themes/OneBlog-lite/...。
请确保你使用的是官方正版，除了上述Github官方仓库和Gitcode镜像仓库，其他任何渠道都无法保证主题的完整性和安全性。如果你是从其他渠道下载安装的，为避免漏洞和后门，建议第一时间更换成官方正版。如果你是从其他渠道购买的，那么毫无疑问，你使用的是盗版，欢迎向主题作者举报。

your-site/
├── usr/
│   └── themes/
│       └── OneBlog/        ← 主题根目录
│           ├── index.php
│           ├── functions.php
│           ├── header.php
│           ├── footer.php
│           ├── post.php
│           ├── page.php
│           ├── archives.php
│           ├── links.php
│           ├── memos.php
│           ├── module/
│           ├── static/
│           └── ...

启用主题

1. 登录 Typecho 后台管理面板。
2. 进入 控制台 → 外观 页面。
3. 在主题列表中找到 OneBlog，点击 「启用」。
4. 启用后点击 「设置外观」，进入主题设置页面进行初始化配置。

LOGO 设置

主题支持两种 LOGO 风格：文字 LOGO 和 图片 LOGO。

Slogan 与 Favicon

自定义菜单

主题内置自定义菜单功能，在后台设置面板的「自定义菜单」字段中配置。

格式：每行一个菜单项，参数用英文逗号隔开。

菜单项名称,链接,图标类名
菜单项名称,链接,图标类名,_blank

示例：

首页,/,iconfont icon-home
相册,/photos,iconfont icon-pic,_blank

首页 Banner

首页顶部支持展示 Banner 文章区域（PC 端杂志效果，移动端幻灯片自动切换）。

标签页背景图

填写图片 URL 后，会在移动端标签归档页的顶部背景区域显示。分类归档页的背景图片请直接在对应分类的描述中填写图片链接。

网站标识图（SEO）

用于 SEO 优化的网站标识图，建议尺寸：1280×720。填写后搜索引擎抓取时会使用该图片作为网站缩略图。

底栏与备案号

创建微语页面

微语功能需要创建一个使用专用模板的独立页面：

1. 进入后台 管理 → 创建页面。
2. 页面标题填写「微语」（或你喜欢的名称）。
3. 在右侧边栏中找到 「自定义模板」，选择 「微语页面」 模板。
4. 页面缩略名（slug）建议填写 memos。
5. 发布页面后，在自定义菜单中添加该页面的链接即可。

创建友链页面

友链页面依赖插件：Links

插件地址：https://github.com/Mejituu/Links

备用下载地址：https://cdn2.lanzouu.com/iQdqF2kmccnc

1. 进入后台 管理 → 创建页面。
2. 页面标题填写「友链」。
3. 自定义模板选择 「友情链接」。
4. 页面缩略名建议填写 links。

创建归档页面

1. 进入后台 管理 → 创建页面。
2. 页面标题填写「归档」。
3. 自定义模板选择 「归档页面」。
4. 页面缩略名建议填写 archives。

创建相册页面

考虑到文章数据结构的合理性和轻量化，自V3.6.1版本起，本主题已移除原有的相册、书单等功能模块，如果您需要继续使用这些功能，建议使用V3.5.3版本（仓库中保留了old分支，切换到old分支下，打包下载即可）。

针对周边功能模块，后续考虑通过插件的形式实现。目前，已开发出完美适配本主题的相册插件。如果您在2025年7月27日之前，曾经赞助过本项目，无论金额多少，本插件均可以免费授权给您个人使用。如需购买相册插件（当前版本定价50元），请加QQ群后私信群主，插件详细介绍：Typecho原生相册插件 - Album V0.1。

相册功能依赖插件：Album

1. 进入后台 管理 → 创建页面。
2. 页面标题填写「相册」。
3. 自定义模板选择 「相册页面」。
4. 页面缩略名建议填写 photos。

封面图与缩略图

文章列表中的缩略图按以下优先级自动获取：

1. 文章编辑时填写的 自定义字段「封面图片」
2. 文章正文中的 第一张图片
3. 如果开启了「随机高清缩略图」，则显示 随机图片
4. 以上均无时，不显示缩略图

自定义字段

在文章编辑页面底部，主题提供了以下自定义字段：

DNS 预解析

用于加速第三方资源的 DNS 解析，每行填写一个域名，已内置以下域名的预解析，无需重复配置：

https://at.alicdn.com
https://weavatar.com
https://cncdn.cc

Sitemap检测更新频率

单位为秒填写后，则网站每隔指定时间会自动检测网站内容数据是否更新，以自动更新sitemap.xml文件，可根据自身更新文章的频率设置。

缩略图参数

如果你的图片存储在 CDN 或云存储服务上，且支持图片处理参数（如腾讯云 COS、阿里云 OSS 等），可以在此填写缩略图参数。

例如填写 !small，则文章列表的缩略图会自动拼接为 图片URL!small。留空则显示原图。

代码块美化

默认开启，开启后会美化文章中的代码区域（语法高亮、一键复制等）。技术博客请保持开启，纯生活记录类博客建议关闭以减少资源加载。

随机高清缩略图

自动夜间模式

开启后，网站将在每天 19:00 至次日 05:00 自动默认启用夜间模式，访客切换后，以访客的偏好设置为准。

评论验证（CF / 极验）

主题支持两种评论安全验证方式，优先使用 Turnstile（如果填写了 CF 密钥，极验会被忽略）：

方式一：Cloudflare Turnstile（推荐）

方式二：极验验证

社交按钮

自定义字体

可选择并应用你喜欢的文章字体，内置字体部分全部均可供个人免费使用，大部分也均可商用，但为了避免版权风险，请在商用前确认授权协议。如果内置字体无法满足您的需求，可以在下方css中自定义字体或通过其他途径添加并设置自己喜欢的字体。

自定义 CSS

可在此填写自定义 CSS 代码，用于覆盖默认样式，尽情开始你的自定义。此 CSS 优先级最高。

/* 示例：不显示网站背景图 */
html {
    background-image: none;
}

/* 示例：修改网站背景图 */
html {
    background-image: url("https://example.com/your-background.jpg");
}

自定义 JS

填写自定义 JavaScript 代码，填写后会直接加载至页脚。适用于添加统计代码、第三方组件等。

// 示例：添加umami统计代码
<script defer src="https://cloud.umami.is/script.js" data-website-id="xxxx"></script>

主题色

在后台设置中可以选择主题色调，默认为 #ff5050。支持颜色选择器直接取色，或切换后手动填写RGB\HSL\HEX值。

备份与恢复

主题支持一键备份与恢复所有设置项，方便在切换主题后恢复之前的配置。

• 备份：点击后台主题说明中的「备份主题配置」按钮，当前设置会保存到 usr/uploads/BackupSetting_OneBlog.txt
• 恢复：点击「恢复主题配置」按钮，将从备份文件中读取并覆盖当前设置。

评论邮件通知

OneBlog 主题已完美适配CommentNotifier插件，可实现邮件通知中也能显示表情。在配置该插件时，在[表情重载]下方的输入框填写 parseEmojis 即可。如果你想获得与官网邮件通知模板一样的效果，请下载下方邮件皮肤后上传到该插件文件夹CommentNotifier/template/目录下，解压并确保文件名为 OneMail ，然后在typecho后台 - 控制台 - 评论邮件提醒外观 选择并启用OneMail。

插件地址：https://github.com/jrotty/CommentNotifier

备用下载地址：https://cdn2.lanzouu.com/izcBe2qes12j

邮件皮肤下载地址：https://cdn2.lanzouu.com/i0Jav2qes9xi

分类页面个性化

移动端的分类页面有分类背景图和分类描述等字段显示，如果你想自定义，直接在后台分类描述中进行填写。直接填写分类图片的url地址和中文分类描述即可，主题代码会自动抓取分类图片和分类文字描述。

增值插件

OneBlog 主题本身完全免费开源，以下增值插件为独立付费产品，按需选购：

常见问题

Q：启用主题后后台或前台出现异常报错？

请检查是否已重命名，打包下载的主题包名称默认为OneBlog-lite（仓库名+分支名），请务必修改为OneBlog。

Q：启用主题后页面样式异常？

可能是浏览器缓存导致，请按 Ctrl + Shift + R（Mac 为 Cmd + Shift + R）强制刷新页面。

Q：启用主题后附件页面/作者页面出现404？

本主题主要偏向于内容本身，很多冗余功能都被移除了。使用本主题后，Typecho默认的附件页面/作者页面会跳转到404页面，如果你想让它们正常显示，请删除主题文件中functions.php的以下代码：

//附件页面和作者页面重定向到404页面
function redirect_404(){
    $request = Typecho_Request::getInstance();
    $pathInfo = $request->getPathInfo();
    // 使用正则表达式匹配路径
    if (preg_match('/^\/(attachment\/\d+|author\/\w+)/i', $pathInfo)) {
        // 调用 404 页面
        $options = Typecho_Widget::widget('Widget_Options');
        $url = $options->siteUrl . '404';
        header("Location: $url");
        exit;
    }
}
// 在页面加载之前调用
Typecho_Plugin::factory('Widget_Archive')->beforeRender = 'redirect_404';

Q：网站的错误页面并非跳转到主题内置的404.php页面，而是跳转到Nginx默认的404 Not Found页面？

原因分析： 这是由于Nginx配置中存在默认的error_page设置，其优先级是最高的，覆盖掉了主题的404逻辑。

解决办法：登录你的服务器面板，打开对应的Nginx配置文件，找到:

error_page 404 /404.html

这一行，将它用#注释掉，也就是修改为:

# error_page 404 /404.html

然后保存并重载Nginx服务。

Q：如何设置文章的封面图？

编辑文章时，在页面底部的自定义字段区域，在「封面图片」字段中填写图片 URL 即可。

Q：评论验证不生效？

请确认已正确填写验证密钥。CF Turnstile 和极验只需配置一组即可，系统会优先使用 CF。已登录管理员不需要验证。为了最大程度减少无关元素的干扰，启用验证后只有正式提交评论时才会弹出验证，请在测试时模拟真实的提交行为。

Q：微语页面没有图片上传按钮？

图片上传功能需要安装付费插件 MemosImage，未安装时仅支持纯文字微语。

Q：如何修改公安备案号的跳转链接？

需要在主题文件 footer.php 中找到公安备案号的相关代码，自行修改跳转链接。

Q：如何联系作者或反馈问题？

• 优先在 GitHub Issues 中反馈
• 加入 QQ 交流群：939170079
• 通过 LiteBBS 讨论交流