准备工作与环境搭建
在开始编写代码之前，一个稳定且高效的本地开发环境至关重要。这不仅能让你离线工作，还能避免在线上服务器直接操作带来的风险。首先，你需要安装一个本地服务器环境，例如 XAMPP、MAMP 或更专业的 Local by Flywheel。这些工具会为你配置好 Apache、MySQL 和 PHP，这是运行 WordPress 的基石。
接下来，你需要下载最新的 WordPress 核心文件，并将其安装到本地服务器中。完成基础安装后，就可以着手创建你的主题目录了。所有 WordPress 主题都位于 /wp-content/themes/ 目录下。请在此处创建一个新的文件夹，例如 my-first-theme。这个文件夹的名称就是你的主题标识。
一个有效的 WordPress 主题至少需要两个核心文件：style.css 和 index.php。style.css 文件不仅是样式表，更是一个主题的“身份证”，其文件头注释包含了主题的所有元信息。
推荐阅读 打造专业网站：从零开始开发一个自定义WordPress主题的完整指南。
主题样式表文件头信息
style.css 文件的开头必须包含一段特定的 CSS 注释，用于向 WordPress 描述你的主题。这些信息会显示在后台的“外观”->“主题”管理页面中。
/*
Theme Name: 我的第一个主题
Theme URI: https://example.com/my-first-theme/
Author: 你的名字
Author URI: https://example.com/
Description: 这是一个用于学习 WordPress 主题开发的简单定制主题。
Version: 1.0.0
License: GPL v2 or later
Text Domain: my-first-theme
*/其中，Text Domain 用于国际化，应与你的主题文件夹名称保持一致。而 index.php 是主题的默认模板文件，是所有页面的后备模板。最初，它可以只是一个简单的 HTML 结构，用于测试主题是否被 WordPress 正确识别。
理解模板层级与创建核心模板
WordPress 使用一套名为“模板层级”的智能系统来决定为特定的页面请求加载哪个模板文件。理解这套规则是主题开发的核心。简单来说，当用户访问一个页面时，WordPress 会按照从最具体到最通用的顺序寻找对应的模板文件。
例如，当访问一篇 ID 为 5 的博客文章时，WordPress 会依次寻找：single-post-5.php -> single-post.php -> single.php -> singular.php -> 最后才是 index.php。如果找到了匹配的文件，就会使用它；否则，会继续向下寻找。
创建文章单页模板
single.php 是用于显示单篇博客文章的标准模板。在这个文件中，你将使用一系列 WordPress 核心的模板标签和函数来输出文章内容。
推荐阅读 WordPress主题开发入门：从零到一构建你的第一个主题。
<?php get_header(); ?>
<main id="primary" class="site-main">
<?php
while ( have_posts() ) :
the_post();
?>
<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
<header class="entry-header">
<h1 class="entry-title"><?php the_title(); ?></h1>
<div class="entry-meta">
发布于：<?php the_date(); ?> | 作者：<?php the_author(); ?>
</div>
</header>
<div class="entry-content">
<?php the_content(); ?>
</div>
<footer class="entry-footer">
<?php the_tags('标签：', ', ', '<br>'); ?>
</footer>
</article>
<?php
// 输出上一篇、下一篇文章导航
the_post_navigation();
endwhile;
?>
</main>
<?php get_sidebar(); ?>
<?php get_footer(); ?>这个模板使用了 the_post() 来设置全局 $post 变量，然后通过 the_title()、the_content() 等函数输出文章数据。同时，它引入了模板部件：get_header(), get_sidebar(), get_footer()。
创建页面模板
page.php 模板用于显示静态页面。它的结构与 single.php 类似，但通常不包含分类、标签等典型的文章元数据。你可以根据需要创建更多特定页面模板，例如为“关于我们”页面创建一个名为 page-about.php 的文件，WordPress 会自动将其应用于标题或别名（slug）为“about”的页面。
集成模板部件与导航菜单
为了保持代码的模块化和可重用性，WordPress 主题通常将页头、页脚、侧边栏等部分拆分为独立的“模板部件”文件。通过使用 get_template_part() 函数，你可以在不同模板中轻松引入这些部件。
构建主题的头部文件
header.php 文件包含了 HTML 文档的头部（ 区域）以及网站顶部的可视部分，如 logo 和主导航。
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
<?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>
<header id="masthead" class="site-header">
<div class="site-branding">
<?php
if ( has_custom_logo() ) {
the_custom_logo();
} else {
?>
<h1 class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>"><?php bloginfo( 'name' ); ?></a></h1>
<p class="site-description"><?php bloginfo( 'description' ); ?></p>
<?php
}
?>
</div>
<nav id="site-navigation" class="main-navigation">
<?php
wp_nav_menu(
array(
'theme_location' => 'menu-primary',
'menu_id' => 'primary-menu',
'container' => false,
)
);
?>
</nav>
</header>关键函数 wp_head() 允许 WordPress 核心、插件和其他脚本向页面头部添加必要的代码（如 CSS、JS 链接）。wp_nav_menu() 函数用于输出一个已注册的导航菜单。
注册导航菜单位置
导航菜单需要先在主题中“注册”位置，用户才能在后台的“外观”->“菜单”中分配菜单。这通常在主题的 functions.php 文件中完成。
推荐阅读 从零开始学习WordPress主题开发：打造个性化网站的完整指南。
function my_first_theme_setup() {
// 注册一个主导航菜单
register_nav_menus(
array(
'menu-primary' => esc_html__( '主导航', 'my-first-theme' ),
'menu-footer' => esc_html__( '页脚导航', 'my-first-theme' ),
)
);
// 支持自定义Logo
add_theme_support( 'custom-logo' );
// 支持文章和评论的 RSS feed 链接
add_theme_support( 'automatic-feed-links' );
// 支持标题标签功能
add_theme_support( 'title-tag' );
}
add_action( 'after_setup_theme', 'my_first_theme_setup' );register_nav_menus() 函数注册了两个菜单位置。通过 add_theme_support() 函数，我们启用了自定义 Logo、标题标签等特性，这是现代 WordPress 主题开发的标准做法。
主题功能与样式进阶
functions.php 文件是你的主题“控制中心”，用于添加功能、修改默认行为、加载脚本和样式表。它与插件的作用类似，但专门作用于你的主题。
安全地引入样式与脚本
正确的样式和脚本加载方式是使用 wp_enqueue_style() 和 wp_enqueue_script() 函数，并将它们挂载到 wp_enqueue_scripts 这个动作钩子上。
function my_first_theme_scripts() {
// 引入主样式表
wp_enqueue_style( 'my-first-theme-style', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) );
// 引入自定义 JavaScript 文件
wp_enqueue_script( 'my-first-theme-navigation', get_template_directory_uri() . '/js/navigation.js', array(), wp_get_theme()->get( 'Version' ), true );
}
add_action( 'wp_enqueue_scripts', 'my_first_theme_scripts' );这种方式确保了依赖关系正确，并且避免了重复加载。函数 get_stylesheet_uri() 返回主 style.css 的 URL，而 get_template_directory_uri() 返回主题目录的 URL。
创建侧边栏小工具区域
小工具区域（Sidebar）允许用户通过后台拖拽的方式自定义内容区块。注册一个小工具区域同样在 functions.php 中完成。
function my_first_theme_widgets_init() {
register_sidebar(
array(
'name' => esc_html__( '主侧边栏', 'my-first-theme' ),
'id' => 'sidebar-1',
'description' => esc_html__( '在此添加小工具。', 'my-first-theme' ),
'before_widget' => '<section id="%1$s" class="widget %2$s">',
'after_widget' => '</section>',
'before_title' => '<h2 class="widget-title">',
'after_title' => '</h2>',
)
);
}
add_action( 'widgets_init', 'my_first_theme_widgets_init' );注册后，你就可以在 sidebar.php 模板部件中使用 dynamic_sidebar( 'sidebar-1' ) 函数来输出这个区域了。
总结
本指南系统地介绍了 WordPress 主题开发的核心流程。从搭建本地开发环境、创建基本主题文件，到理解并实现 WordPress 强大的模板层级系统，再到集成模板部件、注册导航菜单和小工具区域，并最终在 functions.php 中安全地扩展主题功能。遵循这些步骤，你已经成功构建了一个结构清晰、功能完整且符合 WordPress 编码标准的自定义主题。这为你日后开发更复杂、功能更丰富的主题奠定了坚实的基础。记住，主题开发是一个持续学习的过程，不断实践并参考官方文档是提升技能的关键。
FAQ 常见问题
### 什么是 WordPress 模板层级？
模板层级是 WordPress 用来决定不同类型页面使用哪个模板文件的一套规则。它是一个从具体到通用的查找顺序。例如，对于一篇特定的文章，WordPress 会优先寻找与该文章ID或文章类型匹配的特定模板，如果找不到，则逐级回退到更通用的模板，直到最后的 index.php。理解层级关系对于创建结构正确的主题至关重要。
为什么必须使用 wp_enqueue_style 来加载样式？
使用 wp_enqueue_style() 和 wp_enqueue_script() 是 WordPress 官方推荐的、标准化的资源加载方式。它能正确处理依赖关系（例如确保 jQuery 在自定义脚本之前加载），避免同一资源被重复加载，并且与缓存插件、子主题等生态系统良好兼容。直接在模板文件中使用 或 标签是一种不推荐的做法。
functions.php 文件与插件有什么区别？
functions.php 文件是主题的一部分，其功能随主题的激活而激活，随主题的切换而失效。它主要用于添加与该主题视觉表现和功能紧密相关的特性。而插件提供的功能通常独立于主题，即使更换主题，插件功能依然存在。一般来说，如果某个功能与主题的样式或布局强相关，可以放在 functions.php；如果它是通用功能，则更适合做成插件。
如何让我的主题支持多语言（国际化）？
让主题支持多语言，即国际化（i18n），主要涉及以下几个步骤：首先，在 style.css 的头部和所有 load_theme_textdomain() 调用中正确设置 Text Domain。其次，在 functions.php 中调用 load_theme_textdomain() 函数来指定语言文件目录。最后，也是最关键的一步，在主题的所有 PHP 模板文件和 functions.php 中，对所有面向用户的字符串使用 WordPress 的翻译函数进行包装，例如 esc_html__( ‘文本’, ‘my-first-theme’ ) 或 _e( ‘文本’, ‘my-first-theme’ )。完成后，可以使用 Poedit 等工具生成 .pot 模板文件，供翻译人员创建不同语言的 .po 和 .mo 文件。
下一步，接下来该怎么做？
延伸阅读与实用知识
下面这些内容与本文主题相关，适合继续深入阅读。优先从与你当前问题最接近的文章开始看，再逐步扩展到周边主题，效果通常会更好。