Mango 是从 WordPress 主题 Mango 移植并持续维护的 Typecho 双栏主题，提供响应式文章列表、深浅色模式、文章图片灯箱、浏览与点赞统计、评论等级、友情链接和主题配置备份等功能。
- Typecho 1.2 或更高版本。
- PHP 8.0 或更高版本。
- 在线更新需要 PHP ZipArchive，并且 cURL 或
allow_url_fopen至少有一项可用。 - 数据库账号需要
ALTER TABLE权限。主题首次统计浏览量和点赞数时，会在contents表中自动创建views、likes字段。 usr/cache/目录需要可写，站内图片缩略图缓存保存在usr/cache/timthumb/。- Links 插件为可选依赖。友情链接页面和首页底部友情链接需要该插件创建
links数据表，初始化后即使插件停用也能直接读取数据。
- 从 Releases 下载最新版本并解压。
- 将主题目录放入 Typecho 的
usr/themes/，建议将目录命名为Mango。 - 登录 Typecho 后台，进入
控制台 > 外观，启用 Mango。 - 进入
设置外观，按下文完成主题配置。 - 清理站点、浏览器或 CDN 缓存后访问前台。
- 在
控制台 > 外观 > 设置外观 > 备份与恢复中点击“保存主题配置”。 - 备份已有主题目录和自定义修改。
- 使用新版本文件覆盖旧版本。
- 保持升级前后的主题目录名一致。Typecho 按目录名保存主题设置，更改目录名会使原设置无法自动加载。
- 重新进入主题设置页确认选项，并清理页面缓存、CDN 缓存和浏览器缓存。
不要直接覆盖自行修改过的模板；先比较差异再合并，否则自定义代码会丢失。
所有选项均位于 控制台 > 外观 > 设置外观。
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 站点 LOGO 地址 | 内置 Mango 图标 | 填写完整图片 URL 或站内图片地址；留空时仅显示站点标题。 |
| 站点 favicon 地址 | 内置 Mango 图标 | 浏览器标签页图标地址。 |
| 默认文章缩略图地址 | 内置占位图 | 文章没有图片或图片加载失败时使用。 |
| Gravatar 镜像 | https://cravatar.cn/avatar/ |
自定义头像镜像前缀时必须保留末尾 /。 |
| 显示模式 | 自动切换 | 可选“自动切换”“始终浅色”“始终深色”。自动模式按本地时间在 06:00 至 18:00 使用浅色，其余时间使用深色。 |
| 文章列表加载模式 | 页码模式 | 可切换为“加载更多”；加载更多使用主题内置 JSON 请求。 |
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 备案号码 | 空 | 留空不显示；填写后链接到工信部备案网站。 |
| 首页底部链接 | 不显示 | 启用后直接读取 links 数据表中状态为启用且分类名为“推荐”的链接，不依赖插件输出函数。 |
| 自定义页脚内容 | 空 | 支持 HTML，可放置统计代码或其他页脚内容。只粘贴可信来源的代码。 |
“侧边栏模块”可以组合选择以下内容：
- 最新文章
- 最近回复
- 热门文章，按评论数排序
- 热门标签，按文章数量排序
- 其它，包括登录入口和 RSS 链接
数量设置：
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 最新文章数量 | 3 |
控制最新文章模块的条目数。 |
| 热门文章数量 | 5 |
控制热门文章模块的条目数。 |
| 热门标签数量 | 20 |
控制热门标签模块的条目数。 |
“好友邮箱”用于评论区好友认证，一行填写一个邮箱，也支持使用逗号或空格分隔。邮箱匹配不区分大小写。
评论区会根据同一邮箱的历史评论数显示等级。若启用了 Links 插件且友情链接记录中的 user 字段与评论邮箱一致，还会显示博友身份。
文章编辑页的自定义字段中提供“推荐位”选项，默认不勾选。勾选“显示在首页推荐位”并发布文章后，该文章会进入首页幻灯片；取消勾选后不再显示。多篇推荐文章按发布时间从新到旧排列，草稿和未发布文章不会显示。
主题在文章编辑页增加“文章摘要”字段。填写后，首页文章列表优先显示该内容；留空则自动截取正文前 180 个字符。
主题会从以下内容中提取图片：
- HTML
<img>标签 - Markdown 图片语法
- 正文中的 JPG、JPEG、PNG、GIF、WebP 图片直链
列表最多展示前 9 张图片。超过 9 张时，第 9 张图片会显示剩余数量。站内图片使用主题内置 TimThumb 生成 400 x 400 缩略图；站外图片直接使用原地址，不经过服务器代理。
图片异常时依次检查：
usr/cache/和usr/cache/timthumb/是否可写。- 图片 URL 是否能从浏览器直接访问。
- 站点是否部署在子目录，以及 Typecho 的站点地址是否正确。
- “默认文章缩略图地址”是否有效。
主题会在 Typecho 的 contents 表中自动创建：
views：文章浏览量likes：文章点赞数
浏览量和点赞均通过 Cookie 限制同一浏览器的重复计数。若一直显示为 0，请确认数据库账号具有修改表结构和更新数据的权限。
文章和独立页面编辑器会增强附件列表，提供图片预览、全选、取消全选和批量插入。图片以 Markdown 图片语法插入，其他附件以 Markdown 链接语法插入。
- 在后台新建独立页面。
- 标题可填写“文章归档”。
- 将页面缩略名设为
archives。 - 发布页面。
主题通过 page-archives.php 按年份分组列出所有已发布文章，并显示日期和评论数。
- 安装并启用 Links 插件。
- 在后台新建独立页面。
- 标题可填写“友情链接”。
- 将页面缩略名设为
links。 - 发布页面。
主题通过 page-links.php 直接读取 links 数据表，并按分类字段分组展示链接；只要数据表存在，即使插件暂时停用也可以正常显示。所有友情链接均在新窗口打开。头像优先级为：链接图片、邮箱 Gravatar、主题内置占位图。未检测到数据表时，页面会提示安装并启用 Links 插件完成初始化。
如果页面正文中保留了旧的 <links ...> 插件标签，主题会忽略该标签的输出，统一使用数据表生成链接卡片。
主题根据页面或分类的缩略名自动选择 Bootstrap Icons。未匹配的分类使用默认文件夹图标。
| 缩略名 | 图标 |
|---|---|
memos |
对话 |
links |
友情链接 |
about |
信息 |
tags |
标签 |
categories |
分类 |
search |
搜索 |
archives |
日历 |
comments |
评论 |
help |
帮助 |
gbook |
留言 |
tools |
工具 |
| 缩略名 | 图标 |
|---|---|
images、photo |
图片 |
share |
分享 |
NULL |
公告 |
memos |
对话 |
codes |
代码 |
diary |
日记 |
logs |
用户 |
test |
日历 |
tools |
工具 |
music |
音乐 |
links |
链接 |
video |
视频 |
books |
图书 |
games |
游戏 |
themes |
调色板 |
plugins |
插件 |
主题设置页支持服务器端配置备份：
- “保存主题配置”将当前主题设置保存到 Typecho 数据库。
- 备份列表最多显示最近 20 条，可恢复或删除。
- 恢复操作会覆盖当前主题设置。
- 备份不包含文章、独立页面、评论、附件、Links 数据或主题文件。
建议在升级主题、修改大量配置和更换站点环境前创建备份。主题目录名改变后，旧设置和备份不会自动关联到新目录名。
每次进入主题设置页时，主题都会清除 usr/cache/mango-theme-release.json 并重新请求 GitHub Releases 检查最新正式版。当前版本已经是最新版本时不显示“主题更新”区域；无法访问 GitHub 时不会影响前台页面。
发现新版本后，“主题更新”区域会显示“在线更新”按钮。更新流程如下：
- 从项目官方 GitHub Release 下载 ZIP 包。
- 检查 ZIP 路径、符号链接、文件数量、解压大小、主题结构和版本号。
- 将当前主题文件打包备份，默认只保留最近 5 份。
- 将新版本复制到同级暂存目录。
- 交换主题目录；任何安装或复核错误都会尝试恢复旧目录。
- 保留原主题设置并清理版本检查缓存。
更新前文件备份优先保存在 Typecho 根目录上级的隐藏更新目录；该位置不可写时使用 PHP 系统临时目录。更新完成后的后台提示会显示备份绝对路径。
在线更新会完整替换当前主题目录，额外添加或直接修改的主题文件不会合并。请先保存自定义修改。主题目录及其上级目录必须可写；检测到 .git 时在线更新会拒绝覆盖，请改用 git pull。
确认主题目录名是否与升级前一致。Typecho 使用主题目录名区分设置。
先安装并启用 Links 插件完成 links 数据表初始化，并确认表中存在状态为启用且分类名精确为“推荐”的链接。初始化后无需保持插件启用。
安装并启用 Links 插件完成数据表初始化，再刷新友情链接页面。初始化后页面会直接读取 links 表，不要求插件持续启用。页面缩略名必须为 links。
确认 PHP 有权创建并写入 usr/cache/timthumb/，同时核对 Typecho 站点地址和图片 URL。主题禁止 TimThumb 拉取远程图片，这是预期的安全限制。
确认数据库账号具有 ALTER TABLE 和 UPDATE 权限，并检查 PHP 错误日志中是否存在 views 或 likes 字段创建失败的信息。
确认 PHP 已启用 ZipArchive，服务器可以通过 HTTPS 访问 github.com 和 api.github.com，并且主题目录及其上级目录可写。Git 工作区请使用 git pull。无法满足这些条件时，从 Releases 下载压缩包并按“从旧版本升级”步骤手动覆盖。
- 增加简约版友情链接与文章归档独立页面模板，保留原有页面模板。
- 简约版归档增加文章总字数、归档年份和建站天数统计。
- 修复页码模式的页码样式，并适配移动端和深色模式。
- 修复移动端菜单项过多时无法继续向下滚动的问题。
- 优化文章详情页“最后更新于”的展示样式和时间语义。
- 每次进入主题设置页时清空版本检测缓存并重新检查更新。
- 首页底部友情链接改为直接读取
links数据表，不再调用 Links 插件输出函数。 - 首页底部仅显示状态为启用且分类名为“推荐”的链接。
- 移除主题设置中的推荐位文章 CID，改用文章自定义字段“推荐位”。
- 推荐文章按发布时间从新到旧展示，草稿和未发布文章自动排除。
- 当前版本已是最新版本时，不再显示“主题更新”区域。
- 友情链接页面中的链接统一改为在新窗口打开。
- 移除文章目录设置、标题解析和侧边栏目录代码。
- 移除霞鹜文楷字体文件、加载样式和字体设置。
- 增加 GitHub Release 在线检查和后台一键更新。
- 更新前自动备份主题文件，默认保留最近 5 份。
- 增加 ZIP 路径、符号链接、大小、主题结构和目标版本校验。
- 使用暂存目录交换安装，失败时自动回滚旧主题。
- 友情链接页面改为直接读取
links数据表，插件停用后仍可展示已有链接。
- 恢复 Typecho 标准头部钩子，保证插件可以正常向页面
<head>注入资源。 - 修复部分环境下评论提交的来源校验与安全令牌问题。
- 移除
gotopage.php及站外链接跳转提示页，文章和评论中的链接恢复原始地址。 - 友情链接页面改为当前窗口打开。
- 重构 README，补齐安装、设置、内容发布、备份恢复和排错说明。
- 原 WordPress 主题：HUiTHEME/Mango
- Typecho 移植与维护：jkjoy