很多人学 Z-BlogPHP，前面环境也搭好了，运行流程也知道一点，但一真正开始改需求，还是会很乱。
乱的根源通常不是不会写代码，而是不知道：
- 这个需求该落主题还是插件
- 该改模板还是改
include.php - 该去后台设置页，还是直接做成文章字段
- 该写在
header.php，还是写在single.php
所以这一篇的目标很明确：
先建立一张“文件职责表”，让你以后看到需求时，先能找到正确落点。
这件事比你背多少函数都更重要。
一、先记住一个总原则：改最小、改对层
Z-BlogPHP 开发最容易犯的错误，不是完全不会写，而是“明明能改对地方，却偏偏改到了更重的一层”。
比如：
- 本来改模板就够了，却写成插件
- 本来改主题逻辑就够了，却改进核心
- 本来应该做成全局配置，却做成每篇文章都要填
- 本来只是后台表单保存，却硬塞到前台模板里
更稳的原则是：
- 先找真正拥有这个行为的文件
- 只改最小那一层
- 能不跨层就不跨层
你后面会发现，很多维护成本，不是功能本身造成的，而是落点选错造成的。
二、主题开发里，最常见的几个文件分别干什么
先看主题目录：
zb_users/theme/<theme>/
├── theme.xml
├── include.php
├── main.php
├── template/
├── style/
├── script/
└── assets/
这几个位置里，最常碰到的是前四个。
1. theme.xml
这是主题元信息文件。
它更像“主题身份证”，而不是业务逻辑文件。
通常负责：
- 主题 ID
- 名称
- 作者信息
- 后台入口路径
include.php入口声明
什么时候看它？
- 想确认主题基本信息
- 想确认后台设置入口
- 想确认主题引用了哪个入口文件
什么时候不该优先改它？
- 前台布局问题
- 页面逻辑问题
- 配置保存问题
这些都不是它的主战场。
2. include.php
这是主题逻辑层最重要的文件之一。
它通常负责：
- Hook 注册
- 主题辅助函数
- 配置默认值
- 配置消费逻辑
- 条件资源加载
- 列表或详情页的派生数据处理
什么时候更适合改这里？
- 某段逻辑会被多个模板复用
- 需要根据条件决定页面行为
- 需要处理主题配置项
- 需要做派生值而不是单纯排版
如果你发现某段代码在多个模板里复制粘贴，通常就是该回到 include.php 的信号。
3. main.php
这是主题后台设置页的主落点。
它通常负责：
- 权限检查
- 主题启用检查
- 表单保存
CheckIsRefererValid()SaveConfig()BuildTemplate()或其他重建动作
什么时候更适合改这里？
- 新增主题设置项
- 保存全局选项
- 做后台表单
- 保存后触发模板或模块重建
它不该承担什么？
- 前台页面结构
- 文章详情页布局
- 评论区展示
这些都不是它的职责。
4. template/*.php
这是前台输出层。
它通常负责：
- 页面结构
- 模板拆分
- 变量输出
- 列表和详情页布局
- 公共头部、页脚、侧栏、评论区组织
什么时候优先改这里？
- 页面长相要变
- 列表卡片结构要变
- 详情页模块顺序要变
- 搜索页、404 页、分类页展示要变
什么时候不要一上来就改模板？
- 明明是缩略图生成逻辑问题
- 明明是配置保存问题
- 明明是字段注入问题
- 明明是评论校验或接口流程问题
那就应该回到逻辑层。
三、模板目录里，再拆一层职责
很多人知道要改模板，但还是会在模板里乱撞。
更稳的做法，是先知道常见模板文件各自最像什么。
header.php
通常负责：
<head>区域- 标题、描述、关键词
- 全局 CSS、全局前置脚本
{$header}输出
你要改这些东西时，优先想它：
- title
- meta description
- favicon
- canonical
- 站点级 head 脚本
footer.php
通常负责：
- 公共页脚
- 全局尾部脚本
{$footer}输出
适合放：
- 公共页脚结构
- 回到顶部
- 末尾脚本引入
index.php
通常负责：
- 首页
- 列表页
- 分类页
- 标签页
- 作者页
- 日期归档
很多主题会在这里基于 $type 再做分支判断。
如果你要改的是：
- 文章列表卡片
- 分页
- 列表空状态
- 首页和分类页的结构差异
它通常就是第一站。
single.php
通常负责文章详情页。
适合放：
- 标题区
- 正文区
- 作者信息
- 相关推荐
- 评论区位置
page.php
如果主题单独提供它，通常负责独立页面。
适合放：
- 关于页
- 联系页
- 服务页
这种不完全等同于普通文章详情的页面结构。
search.php
通常负责搜索结果。
如果没有，有些主题会回落到 index.php。
适合处理：
- 搜索结果标题
- 搜索为空时的提示
- 搜索结果列表结构
comments.php
通常负责：
- 评论列表
- 回复层级
- 评论表单
- 验证码区域
- 回复交互
评论问题一半在这里，一半不在这里。
这一点后面讲评论专题时会再展开。
四、插件开发里，文件职责怎么分
再看插件目录：
zb_users/plugin/<plugin>/
├── plugin.xml
├── include.php
├── main.php
├── includes/
└── vendor/
1. plugin.xml
和主题的 theme.xml 很像，也是元信息层。
负责：
- 插件 ID
- 插件名称
- 作者
- 版本
- 后台入口
它不是具体逻辑实现层。
2. 插件 include.php
这是插件行为真正开始挂接的地方。
通常负责：
RegisterPlugin(...)Add_Filter_Plugin(...)- 引入辅助文件
- 早期初始化
当你想知道一个插件“到底从哪开始生效”，最先就该看这里。
3. 插件 main.php
这是后台设置和管理工具入口。
通常负责：
- 权限检查
- 启用状态检查
- 保存配置
- 管理界面输出
和主题 main.php 一样，它更偏后台表单和管理工具，不是前台渲染层。
4. includes/
当插件逻辑开始变多时，常会把具体行为拆到这里。
比如：
- 评论处理
- 接口调用
- 规则判断
- 辅助函数
如果一个插件比较复杂，真正的业务实现往往就在这里。
5. vendor/
这一般是第三方依赖。
你需要知道它存在，但不要把自己的业务逻辑也乱塞进去。
五、什么需求该落主题，什么需求该落插件
这是开发中最值钱的一道判断题。
更适合放主题的需求
- 首页结构改造
- 列表页视觉调整
- 文章页模块组织
- 主题级配置项
- 和当前主题强绑定的展示逻辑
更适合放插件的需求
- 评论反垃圾
- 后台菜单扩展
- 编辑页新增字段
- 通用功能模块
- API 扩展
- 路由扩展
- 多主题可复用的逻辑
一句话概括：
强绑定外观的，更像主题职责。
强绑定流程和复用的，更像插件职责。
六、什么需求该放 Config，什么需求该放 Metas
这也是高频分歧点。
放 Config
适合：
- 主题默认缩略图
- 全站 SEO 默认值
- 首页文案
- 站点级开关
- 插件 API Key
也就是：
对整个主题或插件都生效的全局设置。
放 Metas
适合：
- 某篇文章的 SEO 标题
- 某篇文章的封面图
- 某个分类的描述
- 某个标签的自定义模板参数
也就是：
挂在单个对象身上的字段。
如果你把这两类东西混着存，后面会非常难维护。
七、一份最实用的“需求落点速查表”
以后拿到需求，你可以先按这个方式判断：
改页面布局
先看：
template/index.phptemplate/single.phptemplate/page.phptemplate/search.php
改站点头部 meta
先看：
template/header.php- 主题
include.php
新增主题设置项
先看：
main.phpinclude.php
给文章加自定义字段
先看：
- 插件或主题
include.php - 编辑页相关 Hook
改评论提交流程
先看：
template/comments.php- 评论相关插件
- 评论 Hook
新增一个特殊 URL 页面
先看：
- 插件或主题
include.php Filter_Plugin_Zbp_PreLoadRegRoute(...)
做后台扩展
先看：
- 插件
main.php - 后台菜单或编辑页 Hook
八、最常见的 5 种落点错误
1. 把页面布局逻辑写进后台设置页
这通常会让代码越来越难读。
2. 把复用逻辑复制进多个模板
短期省事，长期维护最痛。
3. 把主题强绑定逻辑做成重插件
最后会出现：
- 主题和插件互相缠住
- 换主题就不成立
- 职责边界很乱
4. 把单篇文章字段做成全局配置
后面内容编辑会很别扭。
5. 一有需求就先冲核心
这几乎总是过早的。
九、建立“先判断职责，再开始写”的习惯
我很建议你以后每次动手前，都先问自己这四句：
- 这到底是显示问题，还是流程问题
- 这是单页面问题，还是全局问题
- 这是主题职责，还是插件职责
- 这是全局配置，还是对象字段
很多弯路，都是这四个问题没先问清楚。
结语
Z-BlogPHP 并不怕文件多，它真正怕的是你不分层。
只要你先建立起这张职责表：
theme.xml和plugin.xml是元信息层include.php是逻辑和挂接层main.php是后台设置和管理层template/*.php是前台输出层Config是全局设置Metas是对象字段
后面无论你写主题、写插件、调评论、扩后台、做 SEO 二开，落点都会清楚很多。
下一篇我们开始进入真正的主题开发，从一个主题最小可用结构，到底应该长什么样开始讲。
发表评论
发表评论