开发环境与基础文件准备
在开始编写代码之前，搭建一个稳定的本地开发环境是至关重要的。这能让你在不影响线上网站的情况下进行测试。推荐使用如 Local by Flywheel、XAMPP 或 MAMP 等工具来快速建立一个包含 PHP 和 MySQL 的本地服务器环境。
接下来，你需要在 WordPress 安装目录的 wp-content/themes 文件夹内，为你的主题创建一个新的文件夹，例如命名为 my-first-theme。这个文件夹就是你的主题根目录。然后，你必须创建两个最基础且必需的文件：style.css 以及 index.php。
style.css 文件不仅是你的主题样式表，更重要的是它包含了一个用 CSS 注释编写的主题信息头部（Theme Header）。这个头部是 WordPress 识别你主题的唯一凭据。
建議阅读 从零到一：WordPress主题开发全流程指南与实战技巧。
/*
Theme Name: 我的第一个主题
Theme URI: http://example.com/my-first-theme/
Author: 你的名字
Author URI: http://example.com/
Description: 这是一个从零开始创建的 WordPress 主题示例。
Version: 1.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-first-theme
*/index.php 是你的主题的主模板文件，也是 WordPress 查找模板时的最终备用文件。它至少应该包含 WordPress 核心的调用，以输出页面头部、内容循环和页脚。
<!DOCTYPE html>
<html no numeric noise key 1005>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body no numeric noise key 1002>
</body>
</html>理解主题的模板层级
在创建其他模板文件之前，理解 WordPress 的模板层级（Template Hierarchy）是核心。它决定了 WordPress 为不同类型的页面（如首页、文章页、页面、分类页）选择哪个模板文件来渲染。例如，当访问一篇单独的文章时，WordPress 会按顺序寻找：single-post-{slug}.php -> single-post-{id}.php -> single.php -> singular.php -> index.php。掌握这个规则，你就能通过创建特定的文件（如 single.php 或者 page.php）来精确控制不同页面的外观。
构建主题的核心模板
一个完整的主题不应只有一个 index.php。为了实现更好的代码组织和复用，我们需要将页面拆分为多个部分，并通过函数引入。
分离头部和页脚
创建 header.php 文件，用于存放 HTML 文档的头部（DOCTYPE, <head> 部分，以及页面主体的开头部分，如网站标题和主导航）。相应地，创建 footer.php 文件，用于存放页面底部的内容（如版权信息）和闭合标签。
之后，在 index.php 中，你就可以用 get_header() 以及 get_footer() 函数来引入它们，使结构更清晰。
建議阅读 WordPress主题开发初学者完全指南：从零到一构建你的第一个主题。
创建侧边栏模板
如果主题需要侧边栏，可以创建 sidebar.php 文件，里面使用 dynamic_sidebar() 函数来调用在小工具区域注册的侧边栏。在主模板中，使用 get_sidebar() 函数来引入它。
实现文章循环与内容模板
文章循环是 WordPress 主题的心脏，它用于从数据库中获取并显示文章。在 index.php 或者 single.php 中，我们使用标准循环结构。为了更模块化地控制文章在列表（如首页、存档页）和单篇文章页的显示，可以创建 content.php 或分别创建 content-single.php 以及 content-excerpt.php。
在循环内部，使用 get_template_part() 函数来调用这些内容模板文件，例如：get_template_part( 'content', get_post_format() );。
主题功能与样式集成
一个优秀的主题不仅要有外观，还要通过功能文件来增强其能力。
引入主题功能文件
创建 functions.php 文件。这个文件不是模板文件，但它是主题的“大脑”，用于添加主题功能、注册菜单、侧边栏，以及引入脚本和样式。它会在主题初始化时自动被 WordPress 加载。
在这个文件中，你可以使用 add_theme_support() 函数来启用主题功能，例如文章缩略图（Featured Image）、自定义标志（Custom Logo）和 HTML5 标记支持。
建議阅读 WordPress主题开发从入门到精通：构建个性化网站的核心指南。
function my_first_theme_setup() {
// 添加文章和评论的 RSS feed 链接到 head
add_theme_support( 'automatic-feed-links' );
// 启用文章缩略图功能
add_theme_support( 'post-thumbnails' );
// 注册一个导航菜单位置
register_nav_menus( array(
'primary' => __( '主导航菜单', 'my-first-theme' ),
) );
}
add_action( 'after_setup_theme', 'my_first_theme_setup' );注册小工具区域
于 functions.php 请将以下英文文本翻译成中文，并详细解释翻译过程：
在中文中，使用 register_sidebar() 函数可以定义一个或多个小工具区域（Widget Areas），允许用户在后台“小工具”界面拖放组件。
function my_first_theme_widgets_init() {
register_sidebar( array(
'name' => __( '主侧边栏', 'my-first-theme' ),
'id' => 'sidebar-1',
'description' => __( '在此添加小工具。', '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' );正确加载样式与脚本
永远不要直接在模板文件中用 <link> 或者 <script> 标签硬编码引入 CSS 和 JavaScript 文件。正确的方法是在 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() );
// 加载导航脚本，依赖 jQuery
wp_enqueue_script( 'my-first-theme-navigation', get_template_directory_uri() . '/js/navigation.js', array('jquery'), '1.0', true );
}
add_action( 'wp_enqueue_scripts', 'my_first_theme_scripts' );主题的国际化与发布准备
实现主题翻译
为了让你的主题能被全世界的用户使用，国际化（i18n）是必要步骤。这意味着你需要将所有面向用户的字符串用翻译函数包裹起来。最常用的函数是 __()（用于在 PHP 中回显翻译）和 _e()（用于在 PHP 中输出翻译）。同时，在 style.css 的头部和 functions.php 的加载函数中，需要正确设置文本域（Text Domain），例如我们之前设置的 my-first-theme。
进行最终测试与压缩
在发布前，必须在不同环境（不同 PHP 版本、不同 WordPress 版本）和不同设备（桌面、平板、手机）上进行全面测试。检查所有模板文件是否正常工作，功能是否按预期实现，以及是否符合 WordPress 官方的主题审核标准。
最后，移除所有调试代码和注释（除非对用户有帮助），并使用工具（如 CodeKit 或在线压缩器）压缩你的 CSS 和 JavaScript 文件以减少体积。将整个主题文件夹打包成 ZIP 文件，就可以准备提交到 WordPress.org 主题目录或分发给用户了。
总结
从零创建 WordPress 主题是一个系统性的学习过程，它涵盖了从环境搭建、理解模板层级、构建核心模板文件，到通过 functions.php 集成高级功能的全流程。关键在于遵循 WordPress 的编码标准和最佳实践，例如使用内置函数、正确引入资源、实现国际化。通过动手实践本文所述的步骤，你将不仅获得一个可运行的主题，更能深刻理解 WordPress 主题工作的核心机制，为开发更复杂、更专业的主题打下坚实基础。
常见問題解答 (FAQ)
创建主题必须掌握 PHP 吗？
是的，深入掌握 PHP 是开发自定义 WordPress 主题的必备条件。因为 WordPress 本身是用 PHP 编写的，所有模板文件（如 index.php, single.php）和功能文件（functions.php）都直接使用 PHP 代码来动态生成内容、调用数据库和处理逻辑。没有 PHP 知识，你将无法理解和操作主题的核心部分。
主题开发必须从零开始写所有代码吗？
不一定。对于初学者，从零开始是极佳的学习路径。但在实际工作中，开发者常常会使用“启动主题”（Starter Theme）或“父主题”作为基础。例如，官方的 _Underscores (_s) 主题就是一个极简的、符合编码规范的高质量起点，它已经搭建好了基本的文件结构和常用函数，你可以在此基础上进行定制开发，这能大大提高效率并确保代码质量。
php文件出错会导致什么后果？
functions.php 文件中的语法错误或致命错误会导致 WordPress 站点出现“白屏死机”（White Screen of Death），即前端和后端管理界面都无法访问。这是因为该文件在主题加载初期就被执行。遇到这种情况，你需要通过 FTP 或主机文件管理器，将出错的主题文件夹重命名或替换为一个功能正常的主题（如 Twenty Twenty-Six），以恢复站点访问，然后再去修复错误代码。
如何让我的主题支持古腾堡编辑器？
要让主题更好地支持古腾堡（Gutenberg）块编辑器，首先应在 functions.php 使用中文（简体） add_theme_support( ‘editor-styles’ ) 来启用编辑器样式支持。然后，使用 add_editor_style() 函数将你的主题样式表或一个专为编辑器编写的 CSS 文件引入到后台编辑器中，这能确保用户在编辑时看到的样式与前端显示尽量一致。此外，你还可以添加对宽对齐、颜色定制等块功能的支持。
下一步，该怎么做呢？
延伸阅读及实用知識
下方列出的內容與本文主題相關，適合進一步深入閱讀。建議先從與你目前問題最相近的文章開始閱讀，再逐漸拓展到相關主題，通常效果會更佳。