開發環境與專案初始化
在開始構建自定義 WordPress 主題之前，建立一個高效的開發環境是至關重要的第一步。這不僅能確保程式碼的規範性，還能極大提升開發效率和除錯體驗。
本地開發環境的搭建
推薦使用本地伺服器軟體，如 Local by Flywheel、MAMP 或 XAMPP，它們能快速在您的電腦上搭建一個包含 PHP、MySQL 和 Apache/Nginx 的執行環境。安裝好本地伺服器後，下載並安裝最新版本的 WordPress。接下來，在 WordPress 安裝目錄的 wp-content/themes 資料夾下，建立一個新的資料夾，例如 my-custom-theme，這將是您主題的根目錄。
主題核心檔案的建立
一個最基本的 WordPress 主題只需要兩個檔案：style.css 以及 index.php。首先，建立 style.css 檔案，其作用不僅是定義樣式，更重要的是透過檔案頭部的註釋資訊向 WordPress 宣告您的主題。
推荐阅读 终极WordPress主题开发指南：从零开始搭建自定义WordPress网站主题。
/*
Theme Name: My Custom Theme
Theme URI: https://yourdomain.com/
Author: Your Name
Author URI: https://yourdomain.com/
Description: 一个从零开始构建的自定义 WordPress 主题。
Version: 1.0.0
License: GPL v2 or later
Text Domain: my-custom-theme
*/Text Domain 用於國際化，它將作為後續翻譯文字的識別符號。緊接著，建立最基本的 index.php 檔案，可以先只包含一個簡單的 HTML 結構。完成這兩個檔案後，您就可以在 WordPress 後臺的“外觀”->“主題”中看到並啟用這個空白的主題了。
主題結構與模板層級
理解 WordPress 的模板層級是開發主題的核心。它決定了 WordPress 如何根據不同的請求（如文章頁、頁面、分類存檔）自動選擇對應的模板檔案進行渲染。
核心模板檔案及其作用
WordPress 會按照特定的順序查詢模板檔案。最基本的流程是從最具體的模板回退到最通用的模板。例如，當訪問一篇單獨的文章時，WordPress 會依次尋找：single-post-{id}.php, single-post.php, single.php最后是 singular.php，如果都未找到，則使用 index.php。同理，主頁會先尋找 front-page.php，然後才是 home.php。掌握這個層級關係，可以讓您透過建立特定的模板檔案來精確控制不同頁面的佈局。
创建常用模板文件
除了 index.php，您應該逐步建立以下關鍵模板檔案來構建完整的主題結構：
- header.php: 網站頭部，包含 <head> 區域和頂部導航。
- footer.php: 網站底部。
- sidebar.php侧边栏。
- functions.php: 主題的功能檔案，用於新增功能、註冊選單、小工具區等。
- page.php: 用於渲染單個頁面。
- single.php: 用於渲染單篇文章。
- archive.php：用於渲染分類、標籤、作者等存檔頁。
关于 index.php 您可以在其中使用 get_header(), get_footer(), get_sidebar() 等模板標籤來引入這些模組化部分，實現程式碼複用。
推荐阅读 深入解析WordPress主題開發：從入門到精通的核心技術指南。
核心功能與主題選項
functions.php 檔案是您主題的“大腦”，所有後端邏輯和功能增強都在這裡進行。它會在主題初始化時自動載入。
新增主題支援與註冊功能
通过 add_theme_support() 函式，您可以宣告主題支援的各種功能。例如，啟用文章縮圖（特色影象）是現代主題的標配。
function my_theme_setup() {
// 添加文章和评论的 RSS feed 链接到 head
add_theme_support( 'automatic-feed-links' );
// 启用文章缩略图功能
add_theme_support( 'post-thumbnails' );
// 启用自定义菜单功能
add_theme_support( 'menus' );
// 让 WordPress 管理文档标题
add_theme_support( 'title-tag' );
// 启用对古腾堡编辑器的宽对齐和颜色支持
add_theme_support( 'align-wide' );
add_theme_support( 'editor-color-palette', array( /* ... */ ) );
}
add_action( 'after_setup_theme', 'my_theme_setup' );您還需要註冊導航選單位置和小工具區域（側邊欄）。
function my_theme_menus() {
register_nav_menus( array(
'primary' => __( '主导航菜单', 'my-custom-theme' ),
'footer' => __( '底部菜单', 'my-custom-theme' ),
) );
}
add_action( 'init', 'my_theme_menus' );
function my_theme_widgets_init() {
register_sidebar( array(
'name' => __( '主侧边栏', 'my-custom-theme' ),
'id' => 'sidebar-1',
'description' => __( '在此添加小工具。', 'my-custom-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_theme_widgets_init' );引入樣式表與指令碼檔案
正確的資源引入方式是透過 wp_enqueue_style() 以及 wp_enqueue_script() 函数，并将它们挂载到 wp_enqueue_scripts 鉤子上。
function my_theme_scripts() {
// 引入主样式表
wp_enqueue_style( 'my-theme-style', get_stylesheet_uri(), array(), wp_get_theme()->get('Version') );
// 引入自定义 JavaScript 文件
wp_enqueue_script( 'my-theme-navigation', get_template_directory_uri() . '/js/navigation.js', array(), wp_get_theme()->get('Version'), true );
// 如果评论功能开启且是单篇文章/页面，加载评论回复脚本
if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
wp_enqueue_script( 'comment-reply' );
}
}
add_action( 'wp_enqueue_scripts', 'my_theme_scripts' );迴圈與模板標籤
“迴圈”是 WordPress 用於從資料庫中檢索內容並在頁面上顯示的預設機制。理解並正確使用迴圈是動態內容展示的基礎。
標準迴圈的結構
在模板檔案中，您會經常看到類似下面的程式碼結構，這就是 WordPress 的主迴圈。
推荐阅读 WordPress主题开发入门到精通：从零开始构建自定义主题。
<article id="post-<?php the_ID(); ?>" no numeric noise key 1008>
<header class="entry-header">
<h2 class="entry-title"><a href="/zh-tw/</?php the_permalink(); ?>"></a></h2>
</header>
<div class="entry-content">
</div>
</article>
<p><?php _e( '抱歉，没有找到任何内容。', 'my-custom-theme' ); ?></p>have_posts() 以及 the_post() 函式控制著迴圈的進行。the_title(), the_content(), the_permalink() 等模板標籤用於輸出當前文章的具體資訊。在迴圈外部，您可以使用 is_home(), is_single(), is_page() 等條件標籤來判斷當前頁面型別，從而執行不同的邏輯。
自定義查詢與迴圈
有時您需要顯示非主迴圈的內容，例如在首頁顯示某個特定分類的文章。這時可以使用 WP_Query 類來建立自定義查詢。
<?php
$custom_query = new WP_Query( array(
'category_name' => 'featured',
'posts_per_page' => 3,
) );
if ( $custom_query->have_posts() ) :
while ( $custom_query->have_posts() ) : $custom_query->the_post();
// 输出文章内容...
endwhile;
wp_reset_postdata(); // 重置全局 $post 数据
endif;
?>总结
從零開始開發一個 WordPress 主題是一個系統性的工程，它涵蓋了從環境搭建、結構規劃、功能實現到動態內容展示的全過程。核心在於理解模板層級機制，它決定了頁面的渲染邏輯；熟練運用 functions.php 來擴充套件主題功能；並掌握“迴圈”這一基石來輸出資料。遵循 WordPress 編碼標準和最佳實踐，例如正確引入資源、使用翻譯函式、新增足夠的主題支援，將確保您的主題健壯、高效且易於維護。透過本篇指南的步驟實踐，您將能夠構建出一個結構清晰、功能完備的自定義主題，為更高階的開發打下堅實的基礎。
常见问题解答（FAQ）
開發WordPress主題必須掌握哪些核心技術？
您需要掌握 PHP（用於後端邏輯和模板）、HTML/CSS（用於結構和樣式）、JavaScript（用於互動）的基礎知識。最重要的是理解 WordPress 核心概念，如模板層級、鉤子（Hooks）、動作和過濾器（Actions & Filters）、迴圈（The Loop）以及 WordPress 提供的各種函式和類。
如何讓我的主題支援古騰堡編輯器？
首先，在 functions.php 请将下文翻译成中文，并详细说明翻译过程： add_theme_support() 啟用相關功能，例如 editor-styles、align-wide 和自定義顏色面板。其次，為編輯器建立專用的樣式表，並透過 add_editor_style() 函式引入，以確保後臺編輯器的視覺體驗與前臺一致。您還可以建立塊樣式（Block Styles）或自定義塊（Custom Blocks）來提供更豐富的編輯功能。
主題開發中如何實現多語言支援？
WordPress 使用 GNU gettext 框架進行國際化（i18n）。在程式碼中，所有需要翻譯的文字都應使用特定的函式包裹，如 () 用於在 PHP 中翻譯，_e() 用於翻譯並直接回顯，esc_html() 用於翻譯並轉義 HTML。在 JavaScript 中則使用 wp.i18n.__()。然後，使用 Poedit 等工具提取這些文字生成 .pot 檔案，並翻譯為 .po 和 .mo 檔案。最後，在 style.css 正确设置头部信息 Text Domain 並在 functions.php 请将下文翻译成中文，并详细说明翻译过程： load_theme_textdomain() 載入翻譯檔案。
怎样为我的主题添加自定义设置页面？
對於簡單的選項，可以使用 WordPress 內建的“定製器”（Customizer）API，它提供了直觀的實時預覽介面。對於更復雜的需求，可以建立基於選項頁（Options Page）的設定介面。推薦使用 WordPress Settings API 來安全地註冊、驗證和儲存設定。您也可以使用高階自定義欄位（ACF）或 Carbon Fields 這類第三方庫，它們能極大簡化建立自定義欄位和選項頁面的過程。
下一步，该怎么做呢？
延伸阅读与实用知识
下方列出的内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始阅读，然后逐步扩展到相关主题，这样效果通常会更好。