🎉 开心朋友圈 (KXpyq) — Typecho 主题介绍

版本：v1.0.0
作者：清酒
类型：朋友圈风格单用户博客主题
适配：Typecho 1.2+ / PHP 7.4+

KXpyq 主题安装指南

仿微信朋友圈 Typecho 主题，以说说为核心，支持图文、音乐、视频、链接等多种内容形式。

环境要求

必需

建议安装

快速安装

1. 下载主题

将主题文件夹放到 Typecho 的主题目录：

你的Typecho目录/usr/themes/kxpyq/

确认目录结构如下：

kxpyq/
├── index.php
├── post.php
├── page.php
├── page-about.php
├── page-links.php
├── page-archive.php
├── header.php
├── footer.php
├── comments.php
├── functions.php
├── setting.php
├── ajax.php
├── music-proxy.php
├── img-proxy.php
├── style.css
├── favicon.ico
├── screenshot.png
├── assets/
│   ├── css/
│   ├── js/
│   └── img/
└── lib/
    ├── Meting.php
    └── ip2region/

2. 启用主题

登录 Typecho 后台 → 控制台 → 外观 → 找到「Pyq」→ 启用

3. 基础设置

进入 外观 → 设置外观，按需配置：

其他设置（音乐、社交、公告等）可以后续再配。

4. 完成

现在可以正常发说说了。在后台「撰写」→「撰写文章」即可。

GD 扩展安装（建议）

GD 扩展用于图片缩放缓存、防盗链代理和 EXIF 方向修正。强烈建议安装，可以让图片加载更快、更省带宽。

宝塔面板

1. 登录宝塔面板
2. 软件商店 → PHP 设置 → 对应版本
3. 安装扩展 → 找到 gd → 安装
4. 重启 PHP

apt（Debian / Ubuntu）

# PHP 7.4
sudo apt update
sudo apt install php7.4-gd

# PHP 8.0
sudo apt install php8.0-gd

# PHP 8.1
sudo apt install php8.1-gd

# PHP 8.2
sudo apt install php8.2-gd

# PHP 8.3
sudo apt install php8.3-gd

# 安装后重启 PHP-FPM
sudo systemctl restart php*-fpm

yum（CentOS / RHEL）

# PHP 7.4（Remi 源）
sudo yum install php74-gd

# PHP 8.0
sudo yum install php80-gd

# PHP 8.1
sudo yum install php81-gd

# PHP 8.2
sudo yum install php82-gd

# PHP 8.3
sudo yum install php83-gd

# 安装后重启 PHP-FPM
sudo systemctl restart php*-fpm

Docker 环境

在 Dockerfile 中添加：

RUN apt-get update && apt-get install -y libfreetype6-dev libjpeg62-turbo-dev libpng-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd

验证安装

php -m | grep -i gd

输出 gd 即为安装成功。

或者创建一个 info.php：

<?php phpinfo();

访问后搜索「gd」，确认 GD Support 为 enabled。

可选：安装 EXIF 扩展

EXIF 扩展用于读取手机拍摄照片的方向信息，自动修正旋转。

# apt
sudo apt install php7.4-exif  # 版本号替换为你的 PHP 版本

# yum
sudo yum install php74-exif

# 宝塔面板
PHP 设置 → 安装扩展 → exif

功能说明

✅ 开箱即用（不需要额外安装）

以下功能启用主题后直接可用：

• 说说发布 — 文字、图片、视频、链接
• 评论系统 — AJAX 无刷新提交，支持 @回复
• 点赞 — AJAX 实时点赞/取消
• 分享弹窗 — 微信/微博/QQ/复制链接
• 代码高亮 — Prism.js，16 种语言，暗色主题 + 行号 + 复制按钮
• 图片灯箱 — 点击图片放大查看
• 深色模式 — 跟随系统自动切换
• PJAX 无刷新 — 全站无刷新导航，音乐播放不中断
• 返回顶部 — 滚动后自动出现
• 搜索 — 全文搜索弹窗
• 归档页面 — 按年月分组
• 关于页面 — 社交账号展示 + 弹窗复制
• IP 地理位置 — 评论自动显示所在地区

🖼️ 图片代理

主题内置图片代理功能（img-proxy.php），用于：

• 防盗链 — 防止外部站点直接引用你的图片
• 缩放缓存 — 自动缩放到合适尺寸，节省带宽
• EXIF 修正 — 手机竖拍照片自动旋转（需 EXIF 扩展）

有 GD 扩展时： 图片自动走代理，缩放+缓存+旋转，加载快、省流量。

没有 GD 扩展时： 图片直接显示原图，功能不受影响，但没有缩放缓存。

🎵 音乐功能

音乐功能需要 curl 扩展，有两种使用方式：

方式一：直链模式（推荐）

在后台设置「背景音乐URL」，填入 MP3 直链地址。这种方式不依赖外部 API，最稳定。

方式二：网易云歌曲ID

在后台设置「网易云歌曲ID」，主题会通过内置的 Meting 库自动解析。需要服务器能访问网易云 API。

💡 如果服务器在国内，网易云 API 通常可以直连。如果在国外，可能需要配置代理。

音乐功能包括：

• 顶部导航栏迷你播放器
• 说说内嵌音乐卡片（封面 + 进度条 + 歌词滚动）
• 支持 LRC 歌词和网易云 JSON 歌词格式

📧 评论邮件通知（可选）

主题支持通过 CommentNotifier 插件发送评论邮件通知。

• 不安装：评论功能正常，只是博主收不到新评论邮件提醒
• 安装后：有人评论时自动发送邮件通知博主

安装方式：

1. 下载 CommentNotifier 插件
2. 放到 usr/plugins/CommentNotifier/
3. 后台 → 插件 → 启用

主题已做兼容处理，即使没装此插件也不会报错。

🔗 友情链接（可选）

友链页面需要 Links 插件配合使用。

• 不安装：访问友链页面会显示「友情链接插件未启用」提示
• 安装后：正常展示友链列表，支持分组

安装方式：

1. 下载 Links 插件
2. 放到 usr/plugins/Links/
3. 后台 → 插件 → 启用
4. 后台 → 独立页面 → 新建页面，自定义模板选择「友情链接」

自定义字段

撰写文章时可以使用以下自定义字段扩展内容：

特殊页面

使用方式：后台 → 管理 → 独立页面 → 新建页面 → 自定义模板选择对应模板

头像 CDN

默认使用 cdn.helingqi.com 作为 Gravatar 头像源。后台设置中可以切换：

常见问题

Q: 音乐不播放？

1. 确认 PHP 已安装 curl 扩展：php -m | grep curl
2. 直链模式：确认 MP3 链接可以正常访问
3. 网易云模式：确认服务器能访问网易云 API

Q: 图片加载很慢？

可能是没有安装 GD 扩展，图片没有走缩放缓存。安装 GD 扩展后图片会自动压缩缓存，加载速度会明显提升。

安装方法见上方 GD 扩展安装 章节。

Q: 手机拍的照片方向不对？

安装 EXIF 扩展即可自动修正。安装方法见上方 安装 EXIF 扩展 章节。

Q: 评论提交报错？

1. 确认 Typecho 评论功能已开启
2. 确认 ajax.php 文件可正常访问
3. 检查浏览器控制台是否有网络请求错误

Q: 深色模式不生效？

深色模式跟随系统设置，需要操作系统开启深色模式才会自动切换。

Q: PJAX 页面跳转后功能异常？

主题已内置 PJAX 兼容处理。如果使用了其他 PJAX 插件，可能会冲突，建议关闭第三方 PJAX 插件。

目录结构（完整）

kxpyq/
├── index.php                  # 首页
├── post.php                   # 文章详情页
├── page.php                   # 通用页面
├── page-about.php             # 关于页面
├── page-links.php             # 友链页面
├── page-archive.php           # 归档页面
├── header.php                 # 公共头部
├── footer.php                 # 公共底部
├── comments.php               # 评论模板
├── functions.php              # 主题函数
├── setting.php                # 后台设置页
├── ajax.php                   # AJAX 接口
├── music-proxy.php            # 音乐代理
├── img-proxy.php              # 图片代理
├── style.css                  # 主题样式声明
├── favicon.ico                # 网站图标
├── screenshot.png             # 主题预览图
├── assets/
│   ├── css/
│   │   ├── style.min.css      # 前台样式
│   │   ├── houtai.css         # 后台设置样式
│   │   └── admin-fix.css      # 后台修复样式
│   ├── js/
│   │   ├── app.min.js         # 前台逻辑
│   │   └── houtai.js          # 后台设置逻辑
│   ├── lib/
│   │   ├── fancybox/          # 图片灯箱库
│   │   ├── prism/             # 代码高亮库
│   │   └── qrcode/            # 二维码库
│   └── img/                   # 主题图片资源
├── lib/
│   ├── Meting.php             # 音乐 API 解析库
│   └── ip2region/             # IP 地理位置库
└── INSTALL.md                 # 本文档