CategoryCustomTag 插件开发日志 - 2025年2月

📝 项目概述

CategoryCustomTag 是一个为 Typecho 博客系统开发的分类增强插件，旨在为不同分类提供独立的 tag 模板、自动加载分类 CSS 和自定义分页数量功能。该插件通过钩子系统与 Typecho 深度集成，极大地提升了分类页面的灵活性和用户体验。

✨ 2025年2月开发内容

核心功能实现

1. 分类自定义 Tag 模板

• 实现了为不同分类设置独立 tag 模板的功能
• 支持灵活的映射配置（分类slug:模板文件名）
• 实现了子分类自动继承父分类的 tag 模板
• 支持无限层级的分类结构
• 未找到匹配模板时使用主题默认的 tag.php

2. 自动加载分类 CSS

• 实现了分类页面自动加载对应 CSS 文件
• 扩展到文章页面和 tag 页面的 CSS 自动加载
• 支持一级分类的智能识别
• 子分类自动继承父分类的 CSS
• 通过全局常量 __CATEGORY_SLUG__ 传递分类信息

3. 自定义分类分页数量

• 实现了为每个分类单独设置每页文章数量的功能
• 支持配置映射（分类slug:文章数量）
• 子分类自动继承父分类的分页设置
• 通过全局常量 __CATEGORY_PAGE_SIZE__ 传递配置
• 未设置的分类使用系统默认值

4. 智能来源识别

• 实现了基于 HTTP Referer 的来源分类识别
• 实现了基于 Cookie 的来源分类追踪
• Cookie + Referer 双机制确保准确性
• 支持 30 分钟的 Cookie 过期时间

5. Tag 页面增强

• 实现了 Tag 页面显示来源分类的子分类导航
• 实现了 Tag 页面显示来源分类的所有标签
• 与分类页面保持完全一致的导航和标签显示
• 支持智能回退机制（无来源分类时显示相关标签）

6. 前端脚本集成

• 开发了 category-tag.js 前端脚本
• 在分类页面自动设置 Cookie
• 修改 tag 链接添加分类标识
• 支持点击事件重新设置 Cookie

7. 调试功能

• 实现了可视化的调试信息输出
• 显示来源分类、匹配模板、分类层级链
• 显示 CSS 文件状态和路径
• 仅管理员可见，不影响普通用户

🐛 发现的问题与解决方案

问题1：Cookie 依赖性

问题描述：
如果用户禁用 Cookie，来源分类追踪功能会失效，导致 Tag 页面无法使用正确的模板和 CSS。

解决方案：

• 实现了 Cookie + Referer 双机制
• 当 Cookie 不可用时，回退到 Referer 识别
• 添加了详细的错误处理和日志记录

问题2：HTTP_REFERER 不可靠

问题描述：
某些浏览器、隐私插件或安全设置会阻止 HTTP_REFERER 的发送，导致来源识别失败。

解决方案：

• 优先使用 Cookie（更可靠）
• Cookie 不可用时使用 Referer（备用方案）
• 添加了来源分类的验证逻辑

问题3：配置界面复杂

问题描述：
用户需要手动配置映射规则，格式要求严格，容易出错。

解决方案：

• 提供了详细的配置说明和示例
• 添加了配置格式验证
• 实现了快速检查功能，显示模板文件状态
• 提供了 config-example.txt 配置示例

问题4：模板文件管理不便

问题描述：
用户需要手动在主题目录创建和管理模板文件，缺少可视化管理界面。

解决方案：

• 提供了详细的模板文件创建指南
• 实现了模板文件存在性检查
• 在配置面板显示模板文件状态
• 提供了示例模板文件

问题5：CSS 文件管理不便

问题描述：
用户需要手动创建 CSS 文件，无法预览效果。

解决方案：

• 提供了详细的 CSS 文件创建指南
• 实现了 CSS 文件存在性检查
• 在调试信息中显示 CSS 文件状态
• 提供了示例 CSS 文件

问题6：子分类分页数量继承问题

问题描述：
初始版本中，子分类的分页数量设置没有正确继承父分类的配置。

解决方案：

• 修改了 beforeRender() 方法的逻辑
• 确保子分类能够正确继承父分类的分页设置
• 添加了详细的调试信息显示继承关系

问题7：自定义分类模板的分页逻辑

问题描述：
如果主题有自定义分类模板（如 category/music.php），插件设置的分页数量不会生效。

解决方案：

• 在文档中提供了自定义分类模板的分页逻辑代码
• 提供了详细的修改指南
• 确保用户能够在自定义模板中正确使用分页功能

问题8：Tag 页面导航不一致

问题描述：
初始版本中，Tag 页面没有显示子分类导航，与分类页面不一致。

解决方案：

• 修改了 sub-nav.php 的子分类显示逻辑
• 支持从插件常量 __CUSTOM_TAG_CATEGORY_SLUG__ 读取来源分类
• 实现了 Tag 页面显示子分类导航
• 添加了智能回退机制

问题9：Tag 页面标签显示不正确

问题描述：
初始版本中，Tag 页面显示的是相关标签，而不是来源分类的所有标签。

解决方案：

• 修改了 sub-nav.php 的标签显示逻辑
• Tag 页面优先显示来源分类的所有标签
• 无来源分类时显示相关标签（回退机制）
• 确保与分类页面完全一致

问题10：全局常量命名冲突

问题描述：
插件使用的全局常量可能与主题或其他插件冲突。

解决方案：

• 使用了独特的常量命名前缀（__CATEGORY_）
• 同时支持旧版本常量名以保持兼容性
• 在文档中明确说明了常量的用途

🔧 技术亮点

1. 双机制来源识别

• Cookie + Referer 双机制确保准确性
• Cookie 优先，Referer 备用
• 支持多种用户环境

2. 递归分类查找

• 向上查找一级分类
• 支持无限层级的分类结构
• 智能的模板匹配算法

3. 全局变量支持

• 通过全局常量传递分类信息
• 主题文件可以方便地获取分类数据
• 支持多种页面类型

4. 钩子系统集成

• 利用 Typecho 的 beforeRender hook
• 在模板渲染前执行逻辑
• 无侵入式集成

5. 前端脚本自动加载

• 在分类页面自动加载脚本
• 零配置即可使用
• 支持延迟加载确保 DOM 准备就绪

6. 完善的调试支持

• 可视化的调试信息
• 详细的日志记录
• 仅管理员可见

7. 灵活的配置系统

• 支持多种配置格式
• 配置验证和错误提示
• 实时文件状态检查

📊 开发数据

• 代码行数：约 800 行（PHP + JavaScript）
• 开发周期：2周
• 版本迭代：4个版本（v1.0.0 - v3.0.0）
• 钩子数量：1个
• 全局常量：3个
• 文档数量：15个
• 测试环境：Chrome, Firefox, Safari, Edge, 移动端浏览器
• 兼容性：支持 Typecho 1.0+ 版本

🚀 功能特性

Tag 模板管理

• ✅ 分类自定义 Tag 模板
• ✅ 子分类自动继承
• ✅ 无限层级支持
• ✅ 模板优先级匹配

CSS 自动加载

• ✅ 分类页面自动加载 CSS
• ✅ 文章页面自动加载 CSS
• ✅ Tag 页面自动加载 CSS
• ✅ 子分类自动继承

分页数量控制

• ✅ 自定义分类分页数量
• ✅ 子分类自动继承
• ✅ 系统默认值回退

Tag 页面增强

• ✅ 显示子分类导航
• ✅ 显示来源分类标签
• ✅ 与分类页面一致
• ✅ 智能回退机制

用户体验

• ✅ 零配置脚本加载
• ✅ 双机制来源识别
• ✅ 可视化调试信息
• ✅ 详细的文档支持

📝 版本历史

v3.0.0 (2026-02-12)

• 新增「自定义分类分页数量」功能
• 优化 CSS 自动加载逻辑，支持所有页面类型
• 修复子分类分页数量继承问题
• 修复自定义分类模板的分页逻辑
• 完善调试信息输出
• 更新使用文档

v1.2.0 (2026-02-12)

• Tag 页面显示子分类导航
• Tag 页面显示来源分类标签
• 修改 sub-nav.php 智能逻辑
• 添加智能回退机制

v1.1.0 (2026-02-12)

• Tag 页面自动加载分类 CSS
• 全局变量支持
• 调试信息增强

v1.0.0

• 初始版本发布
• 分类自定义 Tag 模板
• 子分类继承
• Cookie 追踪

💡 开发心得

CategoryCustomTag 插件的开发过程让我深刻体会到了以下几个关键点：

1. 用户体验的一致性：Tag 页面与分类页面保持完全一致的导航、标签和样式，大大提升了用户体验的连贯性。
2. 双机制的可靠性：Cookie + Referer 双机制确保了来源识别的准确性，即使在某些特殊环境下也能正常工作。
3. 全局变量的便利性：通过全局常量传递分类信息，让主题文件能够方便地获取和使用分类数据。
4. 文档的重要性：15个详细的文档涵盖了快速开始、安装配置、使用案例、测试调试等各个方面，大大降低了用户的使用门槛。
5. 调试功能的必要性：可视化的调试信息不仅帮助开发者排查问题，也让用户能够快速定位配置错误。
6. 版本迭代的持续性：从 v1.0.0 到 v3.0.0，每个版本都带来了实质性的功能改进，体现了持续优化的价值。

开发时间：2025年2月
插件版本：3.0.0
开发人员：AI Assistant
兼容性：Typecho 1.0+