WordPress 主题开发：新手入门指南

发布于 作者:

WordPress 主题本质上是一组文件，它们共同决定了你的网站长什么样、怎么运作。对新手来说，大的困惑往往不是“怎么写代码”，而是“从哪里开始”——这套系统里文件太多、概念太杂，很容易让人摸不着头脑。

这篇文章把官方文档里核心的东西拎出来，用更容易理解的方式讲清楚：主题到底是什么、分为哪几种、你需要哪些工具、怎么搭建一个能用的主题。文章里有不少实际代码片段，你可以直接复制粘贴去测试。如果你刚开始接触 WordPress 主题开发，跟着这篇文章走一遍，基本就能建立起一个清晰的框架认知。

什么是 WordPress 主题？

简单说，WordPress 主题就是你网站的“皮肤”加“骨架”。它控制两件事：一是你的网站长什么样（视觉设计），二是内容怎么展示给访客（页面结构）。

从技术角度看，一个主题就是放在 wp-content/themes/ 目录下的一堆文件。这些文件协同工作，把 WordPress 数据库里存储的文章、页面、分类等信息，渲染成访客在浏览器里看到的 HTML 页面。

经典主题 vs 区块主题

WordPress 主题目前分为两大流派：

经典主题（Classic Theme） 依赖 PHP 模板文件来构建页面。比如 header.php 管头部、footer.php 管底部、index.php 是后的兜底模板。这种方式的优点是灵活、可控性强，但需要懂 PHP。

区块主题（Block Theme） 是 WordPress 后来推出的新方向，用 HTML 文件加区块标记来搭建页面布局，配合 theme.json 控制全局样式。它的好处是可以通过站点编辑器可视化地调整布局，不用写 PHP 也能完成大部分工作。

注意：这两种方式目前并存，不是谁取代谁。经典主题依然广泛使用，区块主题代表了未来的方向。新手可以根据自己的学习目标选择从哪边入手。

主题文件结构：基础的骨架

不管你用哪种方式开发，一个 WordPress 主题至少需要两个文件：

style.css——不光是写样式的地方，文件头部还包含了主题的元信息（名称、作者、版本等），WordPress 就是靠这个来识别和显示你的主题的。

text

/*
Theme Name: 我的一个主题
Theme URI: https://example.com
Author: 你的名字
Author URI: https://yourwebsite.com
Description: 这是一个简单的主题
Version: 1.0
License: GPL v2 or later
*/

index.php——这是所有模板文件的“后防线”。当 WordPress 找不到更具体的模板来显示当前内容时，就会退而求其次用 index.php。

注意：仅有这两个文件，你的主题就能被 WordPress 识别和激活，虽然它什么内容也显示不出来——接下来你需要往里填充更多模板文件。

经典主题的核心模板文件

一个完整的经典主题通常会包含这些文件，它们各司其职：

文件作用
header.php网页头部，通常包含 <head> 区域和导航菜单
footer.php网页底部，版权信息、关闭标签等
sidebar.php侧边栏，小工具区域
single.php单篇文章的详情页
page.php独立页面的详情页
archive.php归档页面（分类、标签、日期等）
404.php页面找不到时显示的内容
functions.php主题的功能扩展文件，注册菜单、小工具、加载脚本等都在这里

模板层级：WordPress 如何决定用哪个文件

WordPress 有一套“模板层级”（Template Hierarchy）规则——根据访问的内容类型，从具体的模板开始找，找不到就依次往后退，后退到 index.php。

举个例子：访客打开一篇文章。WordPress 的查找顺序是：

  1. single-{post-slug}.php（比如 single-hello-world.php）
  2. single.php
  3. singular.php
  4. index.php

这个机制的好处是：你可以为特定内容创建专属模板，而不影响其他页面。

模板标签：在模板里“变出”内容

模板标签是 WordPress 提供的内置函数，用来在模板文件中动态获取和显示数据。

常见的几个：

php

<?php the_title(); ?>          // 输出文章标题
<?php the_content(); ?>        // 输出文章正文
<?php the_permalink(); ?>      // 输出文章链接
<?php the_author(); ?>         // 输出作者名字
<?php the_time('Y年n月j日'); ?> // 输出发布时间

要在模板里引入其他模板文件，用这些函数：

php

<?php get_header(); ?>   // 引入 header.php
<?php get_sidebar(); ?>  // 引入 sidebar.php
<?php get_footer(); ?>   // 引入 footer.php

WordPress 主循环（The Loop）

主循环是 WordPress 主题里核心的代码段。它负责从数据库里查出文章，然后逐个输出。

一个基本的循环长这样：

php

<?php if ( have_posts() ) : ?>
    <?php while ( have_posts() ) : the_post(); ?>
        <h2><?php the_title(); ?></h2>
        <div><?php the_content(); ?></div>
    <?php endwhile; ?>
<?php else : ?>
    <p>暂无内容</p>
<?php endif; ?>

代码逻辑：have_posts() 检查有没有文章，有则进入 while 循环，the_post() 把当前文章的数据准备好，然后就可以用 the_title() 这些模板标签输出了。

functions.php：主题的“大脑”

这个文件在主题加载时被执行，用来注册主题功能、加载脚本样式、添加钩子等。

注册导航菜单和侧边栏的典型写法：

php

<?php
// 在 functions.php 中

function mytheme_setup() {
    // 注册导航菜单
    register_nav_menus( array(
        'primary' => '主导航',
        'footer'  => '底部导航',
    ) );
    
    // 注册侧边栏
    register_sidebar( array(
        'name'          => '侧边栏',
        'id'            => 'sidebar-1',
        'before_widget' => '<div class="widget">',
        'after_widget'  => '</div>',
    ) );
    
    // 启用特色图片功能
    add_theme_support( 'post-thumbnails' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

注意：add_action('after_setup_theme', ...) 是 WordPress 的钩子机制，意思是在主题初始化完成后执行 mytheme_setup 这个函数。新手刚开始可能不太理解，照着用就行，后续会慢慢熟悉。

区块主题：新方向

区块主题的核心文件是 theme.json，它是一个 JSON 格式的配置文件，控制全局的颜色、字体、间距等设计变量。

简单的 theme.json：

json

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#0073aa",
          "name": "主色"
        }
      ]
    }
  }
}

模板文件则换成 HTML 格式，用区块标记来组合页面：

html

<!-- 在 templates/index.html 中 -->
<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:post-title /-->
<!-- wp:post-content /-->
<!-- wp:template-part {"slug":"footer"} /-->

<!-- wp:... --> 这种注释风格的代码就是区块标记，WordPress 会解析它们并渲染成对应的区块。template-part 用来引用 parts/ 目录下的可复用组件（如头部、底部）。

注意：区块主题需要 WordPress 5.9 以上版本才能完整支持。如果你用的是更早的版本，建议先升级或者从经典主题入手。

快速上手：搭建一个主题

一步：搭建本地环境

推荐用 LocalWP（免费且好用）在电脑上快速搭建 WordPress 本地环境，这样怎么折腾都不影响线上网站。

二步：创建主题文件夹

在 wp-content/themes/ 下新建一个文件夹，比如 my-first-theme。

三步：创建必要文件

在里面新建 style.css 和 index.php，把上面示例的代码填进去。然后去后台“外观 → 主题”里激活它。

四步：添加更多模板

依次创建 header.php、footer.php、functions.php，然后在 index.php 中用 get_header() 和 get_footer() 把它们串联起来。刷新前台页面，你就能看到变化了。

总结

WordPress 主题开发的核心概念可以归结为：

  1. 主题就是一组文件，放在 wp-content/themes/ 下，style.css 和 index.php 是底线要求。
  2. 模板层级决定了 WordPress 用什么文件来显示什么内容——越具体的模板优先级越高，找不到就层层回退到 index.php。
  3. 主循环是所有动态内容的输出引擎，have_posts() 和 the_post() 是它的启动开关。
  4. functions.php 是功能扩展中心，注册菜单、小工具、加载资源都在这里完成。
  5. 区块主题代表新方向，用 theme.json 和 HTML 模板替代 PHP，降低开发门槛。

新手建议先从经典主题入手，弄明白模板层级和主循环这两个核心机制，再慢慢接触区块主题。动手写几个简单的模板，比看再多文档都管用。