AI摘要
小武站
前言
本手册基于子比主题最新稳定版文件结构编写，旨在帮助开发者快速理解主题模块化架构、定位功能文件、掌握二次开发规范。手册覆盖了从根目录入口、核心加载器、业务模块、静态资源到开发规范的完整内容，是主题定制与维护的权威参考文档。
一、根目录文件与入口核心
根目录文件是主题的启动入口与全局配置中心，决定了主题的基础运行逻辑。
| 文件名 | 功能说明 | 开发场景 |
|---|---|---|
functions.php |
主题核心入口，加载所有模块、初始化环境 | 主题启动流程修改、全局钩子注入 |
style.css |
主题元信息文件，定义名称、版本、作者等 | 主题标识修改、版本号管理 |
index.php |
站点首页入口文件 | 首页布局与渲染逻辑修改 |
header.php |
网站头部模板 | 导航栏、头部 JS/CSS、SEO 标签修改 |
footer.php |
网站底部模板 | 备案信息、统计代码、底部交互修改 |
single.php |
文章详情页模板 | 文章内容页布局修改 |
page.php |
独立页面模板 | 通用页面布局修改 |
archive.php |
归档 / 分类页模板 | 列表页布局修改 |
404.php |
404 错误页模板 | 错误页样式与跳转逻辑修改 |
comments.php |
评论区模板 | 评论列表与表单渲染修改 |
二、inc/ 核心功能目录（主题心脏）
2.1 inc/inc.php – 核心加载器
- 功能：定义主题常量、检测 PHP 版本、初始化加载机制、按依赖顺序加载所有子模块。
- 关键：所有模块的加载顺序在此定义，修改时需注意依赖关系，避免模块报错。
2.2 inc/dependent.php – 前置依赖工具函数
| 函数 / 功能 | 说明 | 开发场景 |
|---|---|---|
_pz($name, $default) |
获取主题配置项（带默认值） | 自定义功能中读取后台配置 |
_spz($name, $value) |
设置主题配置项 | 自定义配置项写入逻辑 |
zib_get_option_meta() |
元数据读取（带缓存） | 高效读取文章 / 用户元数据 |
zib_user_meta() |
用户元数据读写 | 用户信息扩展开发 |
zib_post_meta() |
文章元数据读写 | 文章自定义字段开发 |
.3 inc/options/ – CSF 配置框架（后台设置核心）
子比主题基于 CSF 框架实现的可视化配置系统，包含以下关键文件：
| 文件名 | 功能说明 |
|---|---|
options.php |
配置模块入口，加载 CSF 框架 |
admin-options.php |
后台核心配置面板（全局设置） |
metabox-options.php |
文章编辑页元配置项 |
profile-options.php |
用户资料页配置项 |
action.php |
配置项保存与校验钩子 |
upgrade.php |
版本升级数据迁移 |
zib-code.php |
主题授权码校验 |
2.4 inc/functions/ – 功能函数库（业务逻辑核心）
主题所有业务功能的实现文件，按功能模块划分：
| 文件名 | 功能说明 |
|---|---|
functions.php |
函数库入口，加载所有业务模块 |
zib-tool.php |
通用工具函数（字符串、数据处理） |
zib-theme.php |
主题基础功能（支持特性、钩子挂载） |
zib-head.php |
页面<head>标签输出（SEO、资源引入） |
zib-header.php |
头部导航与用户入口功能 |
zib-footer.php |
底部功能与统计代码 |
zib-post.php |
文章通用逻辑（浏览量、权限控制） |
zib-single.php |
文章详情页专属逻辑 |
zib-index.php |
首页布局与模块渲染 |
zib-content.php |
文章内容过滤与短代码解析 |
2.4.1 inc/functions/user/ – 用户系统模块
完整实现用户注册、登录、权限、等级、签到等功能：
| 文件名 | 功能说明 |
|---|---|
user.php |
用户系统主入口 |
user-auth.php |
登录 / 注册 / 找回密码认证 |
user-level.php |
用户等级与经验值系统 |
user-checkin.php |
用户签到功能 |
user-cap.php |
用户权限控制 |
page/user-center.php |
前端用户中心页面 |
2.4.2 inc/functions/bbs/ – 论坛系统模块
主题内置论坛功能的实现文件，包含版块、帖子、评论、版主管理等逻辑。
2.4.3 inc/functions/shop/ – 商城系统模块
2.4.4 inc/functions/message/ – 消息系统模块
2.5 inc/class/ – 核心工具类库
封装了主题所有通用复杂操作，是功能开发的基础依赖：
| 文件名 | 功能说明 |
|---|---|
db-class.php |
数据库操作封装 |
file-class.php |
文件上传与处理 |
qrcode.class.php |
二维码生成 |
sms-class.php |
短信发送接口 |
meilisearch-class.php |
全文搜索集成 |
2.7 inc/code/ – 核心代码模块
| 文件名 | 功能说明 |
|---|---|
require.php |
核心模块自动加载入口 |
aut.php |
授权码校验逻辑 |
update.php |
主题在线更新处理 |
三、zibpay/ 支付与付费系统（核心商业模块）
| 文件名 / 目录 | 功能说明 |
|---|---|
functions.php |
支付系统入口 |
class/order-class.php |
订单核心类 |
functions/zibpay-post.php |
文章付费阅读 |
functions/zibpay-download.php |
付费下载功能 |
functions/zibpay-vip.php |
VIP 会员系统 |
functions/zibpay-balance.php |
用户余额系统 |
shop/alipay/ |
支付宝支付接口 |
shop/wechat/ |
微信支付接口 |
page/*.php |
支付相关前端页面（订单、充值、提现） |
四、oauth/ 第三方登录模块
实现主流平台 OAuth 授权登录，降低用户注册门槛：
| 文件名 / 目录 | 功能说明 |
|---|---|
oauth.php |
第三方登录入口 |
wechat/login.php |
微信登录 |
weiboagent/login.php |
微博登录 |
| 其他扩展（QQ/GitHub/Gitee 等） | 多平台登录支持 |
五、pages/ 自定义页面模板
后台新建页面时可直接套用的内置模板，无需从零开发：
| 文件名 | 功能说明 |
|---|---|
user-sign.php |
登录 / 注册 / 找回密码页面 |
newposts.php |
前端发布文章页面 |
download.php |
资源下载页面 |
archives.php |
文章归档页面 |
links.php |
友情链接页面 |
forums.php |
论坛首页模板 |
六、template/ 模板部件
通用界面组件的模板片段，可在不同页面复用：
| 文件名 | 功能说明 |
|---|---|
content-404.php |
404 页面内容模板 |
comments.php |
评论区模板 |
excerpt.php |
文章摘要模板 |
single-dosc.php |
文档类文章详情模板 |
七、yiyan/ 一言功能模块
主题内置的随机名言展示功能，用于提升页面氛围感：
| 文件名 | 功能说明 |
|---|---|
qv-yiyan.php |
一言功能核心实现 |
八、action/ 动作钩子处理
主题前后端交互的核心中枢，所有用户操作的后台处理逻辑：
九、静态资源文件目录
9.1 css/ 样式文件
| 文件名 | 功能说明 |
|---|---|
main.css |
主题全局主样式 |
bootstrap.css |
Bootstrap 框架样式 |
admin-main.css |
后台设置面板样式 |
swiper.css |
轮播组件样式 |
*.min.css |
对应压缩版样式文件 |
9.2 js/ 脚本文件
| 文件名 | 功能说明 |
|---|---|
main.js |
主题全局主脚本（导航、交互、懒加载） |
| 其他功能脚本（轮播、AJAX、支付等） | 对应模块的前端交互逻辑 |
9.3 fonts/ 字体文件
9.4 img/ 图片资源
十、其他文件与依赖
| 文件名 / 目录 | 功能说明 |
|---|---|
composer.json/composer.lock |
PHP 依赖管理配置文件 |
vendor/ |
Composer 安装的第三方依赖包 |
🔧 二次开发最佳实践指南
1. 自定义功能代码存放
- 在主题根目录创建
func.php，主题会自动加载，且在线更新不会被覆盖，是存放自定义代码的最佳位置。
2. 自定义小工具开发
- 使用
Zib_CFSwidget::create()方法，基于主题 CSF 框架快速创建可视化配置的自定义小工具。
3. 后台配置项扩展
- 在
inc/options/目录下，基于 CSF 框架 API 新增配置项，自动集成到主题后台设置面板。
4. 钩子使用
zib_require_end：主题所有文件加载完成后的钩子，适合在主题初始化后注入自定义逻辑。
5. 配置项读取规范
- 统一使用
_pz('option_name')函数获取主题配置，自带默认值处理，安全稳定。
6. 开发避坑建议
- 禁止直接修改主题核心文件（如
inc/、zibpay/目录下文件），避免更新被覆盖。 - 支付、授权相关文件涉及资金与安全，非必要不修改。
- 新增功能优先通过钩子 / 过滤器实现，保证主题可升级性。
手册结语
若您发现内容有误或已失效，请在下方 留言 反馈，我会及时核实更新。
© 版权声明
本网站部分文件及内容来自互联网，版权归原作者所有。转载需授权，侵权必究。部分内容受《网络出版服务管理规定》保护，未经许可禁止商业使用。
THE END
暂无评论内容