WordPress 主题开发入门：模板层级、钩子与子主题
先说结论：WordPress 主题开发只要记住两件事——模板层级决定「用哪个文件」，钩子决定「在哪插入内容」。搞懂这两条，剩下就是 PHP 和 CSS 的活。新手建议先做子主题，别直接改主题文件。 一、模板层级：WordPress 是怎么选
先说结论：WordPress 主题开发只要记住两件事——模板层级决定「用哪个文件」，钩子决定「在哪插入内容」。搞懂这两条，剩下就是 PHP 和 CSS 的活。新手建议先做子主题，别直接改主题文件。
一、模板层级：WordPress 是怎么选文件的
访问一个文章页时，WordPress 会按固定顺序去找模板文件，找到第一个就用它：
single-post-{ slug }.php
single-post.php
single.php
singular.php
index.php首页、分类页、归档页各有自己的链条：
| 页面类型 | 查找顺序（自上而下） |
|---|---|
| 首页 | front-page.php → home.php → index.php |
| 文章页 | single-post-{slug}.php → single-post.php → single.php → singular.php → index.php |
| 页面 | page-{slug}.php → page-{id}.php → page.php → singular.php → index.php |
| 分类页 | category-{slug}.php → category-{id}.php → category.php → archive.php → index.php |
| 搜索结果 | search.php → index.php |
| 404 | 404.php → index.php |
最常见的困惑：「我改了 index.php 没反应」——因为当前页面走的是 single.php，根本没到 index。排查时先看当前页面命中了哪个模板（可用调试插件显示），再改对应文件。
index.php 是最后兜底，任何主题都必须有它，否则主题不合法。
二、一个最小主题的骨架
最少需要这几个文件：
my-theme/
├── style.css （必须有，头部注释声明主题信息）
├── index.php
├── functions.php
├── header.php
├── footer.php
└── sidebar.phpstyle.css 的头部注释是主题身份证：
/*
Theme Name: My Theme
Author: Your Name
Version: 1.0
Text Domain: my-theme
*
缺了这段，后台「外观」里根本看不到你的主题。
三、模板里最该先学会的 5 个函数
get_header()/get_footer()/get_sidebar()：引入公共片段。have_posts()+the_post()：主循环，几乎所有列表和详情都靠它。the_title()/the_permalink()/the_content()：输出内容。wp_head()/wp_footer()：绝对不能漏。很多插件靠这两个钩子注入资源，漏了就会出现「插件装了没效果」。wp_nav_menu()：输出导航菜单。
一个最小循环长这样：
<?php if ( have_posts() ) : ?>
<?php while ( have_posts() ) : the_post(); ?>
<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
<?php the_excerpt(); ?>
<?php endwhile; ?>
<?php else : ?>
<p>没有内容</p>
<?php endif; ?>四、钩子：主题开发的分水岭
钩子分两类：
- 动作（action）：在某个位置「执行一段代码」，如
wp_head、wp_footer。 - 过滤器（filter）：把某个值「改一下再返回」，如
the_content、excerpt_length。
在 functions.php 里加钩子的标准写法：
// 在 head 里插入自定义 meta
add_action('wp_head', function () {
echo '<meta name="theme-color" content="#1a73e8">';
});
// 修改摘要长度
add_filter('excerpt_length', function () {
return 60;
});开发原则：能挂钩子就不要直接改父主题文件，否则父主题一升级，你的改动全丢。
想加主题设置页，用 add_theme_support() 声明功能，用 Customizer（customize_register）加选项，而不是自己写一个配置面板。
五、为什么一定要用子主题
子主题继承父主题的所有功能，你只需放要覆盖的文件：
my-theme-child/
├── style.css （Template: 父主题目录名）
└── functions.php
style.css 里必须写 Template: 父主题目录名，这一行决定它继承谁。
子主题的三个好处：
- 父主题更新，你的改动不丢。
- 只覆盖需要的文件，不用复制整套模板。
- 出问题直接禁用子主题，父主题不受影响。
经典坑：子主题的 style.css 不会自动加载，需要在 functions.php 里手动 enqueue 父主题与子主题的样式。
六、开发时的必备习惯
- 开
WP_DEBUG，把 warning 当错误看。 - 所有输出都过
esc_html()/esc_url()，这是主题审核的硬要求。 - 文本字符串用
__()包裹，方便别人做语言包。 - 用浏览器开发者工具直接在页面上调 CSS，最后再写回文件。
照着这套骨架做一个纯列表页主题，两三天就能跑通。真正的门槛不在语法，而在「知道该改层级里的哪个文件」。