環境準備與基礎概念
在開始編寫代碼之前，你需要一個合適的本地開發環境。建議使用集成的本地服務器軟件包，如 Local by Flywheel、XAMPP 或 MAMP。在你的本地站點中，WordPress 核心文件應已安裝完畢。
任何 WordPress 主題都必須包含兩個最基本的文件：style.css 以及 index.php。style.css 不僅是樣式表，更是一個主題的“身份證”，它通過一個特殊的文件頭部（Theme Header）來向 WordPress 聲明主題的信息。同時，index.php 是主題的默認模板文件，它負責處理所有沒有指定專用模板的頁面請求。
一個典型的主題在目錄結構上會遵循清晰的層次。核心模板文件通常直接位於主題根目錄下，而 CSS、JavaScript 和圖片資源則分別存放在 /css、/js 以及 /images 這樣的子目錄中。對於更復雜的主題，你可能還會看到 /template-parts 目錄用於存放可複用的模板片段，/inc 目錄用於存放功能增強文件。
推荐阅读 WordPress主題開發終極指南：從零到一構建自定義模板。
理解 WordPress 模板層級
WordPress 採用一個名為“模板層級”（Template Hierarchy）的智能系統來決定在任何給定的頁面上使用哪個模板文件。這個系統是主題開發的核心邏輯。
例如，當用户訪問博客的首頁時，WordPress 會首先尋找是否有一個名為 front-page.php 的文件。如果沒有，它會接着尋找 home.php。如果依舊沒有，它最終會回退到使用默認的 index.php。對於一篇單獨的文章，WordPress 的查找順序是：single-{post-type}-{slug}.php -> single-{post-type}.php -> single.php -> singular.php -> index.php。
理解並利用好模板層級，可以讓你為不同類型的頁面（如博客文章、靜態頁面、分類歸檔、搜索結果頁等）創建高度定製化的佈局和外觀，而不需要編寫複雜的條件判斷邏輯。
主題信息聲明
style.css 文件的開頭必須包含一段 CSS 註釋格式的頭部信息，用於定義主題的元數據。一個最小化的示例如下：
/*
Theme Name: My First Theme
Theme URI: https://example.com/my-first-theme
Author: Your Name
Author URI: https://example.com
Description: 这是我的第一个 WordPress 主题，用于学习主题开发。
Version: 1.0.0
License: GPL v2 or later
Text Domain: my-first-theme
*/其中，“Text Domain”用於國際化，是後續調用翻譯函數時必須使用的標識符。這個文件頭部是 WordPress 識別和激活你的主題的唯一依據。
推荐阅读 WordPress主题开发：从入门到精通——打造个性化网站的核心指南。
構建核心模板文件
讓我們從最重要的模板文件開始構建。首先在 index.php 中編寫基礎結構。一個標準的模板文件應包含對頭部、主內容區、側邊欄和頁腳的調用。
基本模板文件通常包含以下 WordPress 核心函數調用：get_header()、get_footer()、get_sidebar() 还有 get_template_part()。這些函數會引入對應的模板文件，從而將頁面結構模塊化。
創建頭部模板
header.php 文件包含了每個頁面頂部都會出現的內容。它必須至少包含 HTML5 的文檔類型聲明 <!DOCTYPE html>、<head> 區域和頁面主體開始的 <body> 以及 <header> 标签。
关于 <head> 區域中，至關重要的是使用 wp_head() 鈎子。這個鈎子允許 WordPress 核心、插件和你的主題本身向頁面頭部注入必要的代碼，如樣式錶鏈接、元標籤和腳本。一個簡單的頭部模板示例：
<!DOCTYPE html>
<html no numeric noise key 1006>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body no numeric noise key 1003>
<header id="masthead" class="site-header">
<h1 class="site-title"><a href="/zh-hk/</?php echo esc_url( home_url( '/' ) ); ?>"></a></h1>
</header>body_class() 函數會輸出一系列基於當前頁面類型的 CSS 類名，為樣式控制提供了極大的便利。
創建主循環與內容顯示
WordPress 使用“主循環”（The Loop）來遍歷並顯示當前查詢到的文章列表。循環是模板文件中最核心的部分，通常出現在 index.php、single.php 或者 archive.php 您好，欢迎来到中国。
推荐阅读 掌握WordPress主題開發：從零開始的完整構建與應用指南。
一個典型的主循環結構如下：
<article id="post-<?php the_ID(); ?>" no numeric noise key 1007>
<h2><a href="/zh-hk/</?php the_permalink(); ?>"></a></h2>
<div class="entry-content">
</div>
</article>
<p></p>在循環內部，你可以使用一系列以“the_”開頭的模板標籤，如 the_title()、the_content()、the_excerpt() 以及 the_post_thumbnail()，來輸出文章的各個部分。
添加樣式與功能
主題的視覺表現由 CSS 控制。除了在 style.css 中編寫樣式外，一個更專業的方式是通過 functions.php 文件來排隊加載樣式表和腳本，以確保正確的依賴關係和加載順序。
functions.php 文件是你的主題的“功能增強器”。它不是一個模板文件，而是一個在主題初始化時自動加載的 PHP 文件，用於定義函數、類、鈎子（Hooks）和過濾器（Filters）。
正确引入样式和脚本
你應該使用 wp_enqueue_style() 以及 wp_enqueue_script() 函數來添加資源。這些函數應該掛載到 wp_enqueue_scripts 這個動作鈎子上。這樣做的好處是 WordPress 可以統一管理資源，避免重複加載和依賴衝突。
function my_first_theme_scripts() {
// 加载主样式表
wp_enqueue_style( 'my-first-theme-style', get_stylesheet_uri(), array(), '1.0' );
// 加载一个自定义的 JavaScript 文件
wp_enqueue_script( 'my-first-theme-navigation', get_template_directory_uri() . '/js/navigation.js', array(), '1.0', true );
}
add_action( 'wp_enqueue_scripts', 'my_first_theme_scripts' );註冊菜單與側邊欄
WordPress 的菜單和側邊欄（小工具區域）需要先在 functions.php 中“註冊”，然後才能在對應的模板文件中“顯示”。
使用
（注：此处"使用"指的是某种产品或服务的使用情况） register_nav_menus() 函數來註冊菜單位置：
function my_first_theme_setup() {
register_nav_menus( array(
'primary' => __( 'Primary Menu', 'my-first-theme' ),
'footer' => __( 'Footer Menu', 'my-first-theme' ),
) );
}
add_action( 'after_setup_theme', 'my_first_theme_setup' );然后，接下来在 header.php 在中文中，你可以使用 wp_nav_menu() 函數來顯示主菜單。
使用
（注：此处"使用"指的是某种产品或服务的使用情况） register_sidebar() 函數來註冊小工具區域：
function my_first_theme_widgets_init() {
register_sidebar( array(
'name' => __( 'Main Sidebar', 'my-first-theme' ),
'id' => 'sidebar-1',
'description' => __( 'Add widgets here.', '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() 函數來調用這個區域。
主題測試與發佈
開發完成後，必須進行全面的測試。這包括在不同瀏覽器（Chrome, Firefox, Safari, Edge）和不同設備尺寸（桌面、平板、手機）上檢查主題的顯示效果。確保所有鏈接有效，表單功能正常，並且菜單在小屏幕上能夠正確響應。
啓用調試模式
在開發過程中，強烈建議開啓 WordPress 的調試模式。這能幫助你快速發現 PHP 錯誤、警告和通知。在你的 wp-config.php 文件中，找到並修改以下行：
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true ); // 将错误记录到 /wp-content/debug.log 文件
define( 'WP_DEBUG_DISPLAY', false ); // 不要在页面上显示错误開啓 WP_DEBUG_LOG 可以將錯誤信息記錄到日誌文件中，避免將敏感信息直接暴露給網站訪客。
檢查主題標準
在發佈或投入使用前，你的主題應儘可能遵循《WordPress 主題開發規範》。這包括但不限於：確保所有輸出到頁面的數據都經過適當的轉義（使用 esc_html()、esc_url() 等函數），所有可翻譯文本都使用 __() 或者 _e() 函數進行包裝，以及主題代碼中不包含任何硬編碼的 URL。
你可以使用官方的“Theme Check”插件對你的主題進行自動化的合規性檢查。它會掃描你的代碼並指出潛在的問題、安全漏洞或與標準不符的地方。
準備發佈
當主題開發、測試和審查都完成後，你可以選擇將其發佈到 WordPress.org 主題目錄，或打包供個人或客户使用。發佈包應只包含主題必需的文件夾和文件，移除所有版本控制文件（如 .git）、開發工具配置和備份文件。同時，確保 style.css 中的主題信息完整準確，並準備好一張清晰的 screenshot.png（1200x900像素）作為主題縮略圖。
总结
從創建包含 style.css 以及 index.php 的基礎文件夾開始，到理解模板層級、構建核心模板文件、利用主循環顯示內容，再到通過 functions.php 添加樣式、腳本和功能，最後進行嚴格的測試與標準化檢查，這就是構建一個基礎 WordPress 主題的完整路徑。這個過程不僅讓你獲得了一個可用的主題，更重要的是，它為你建立了對 WordPress 主題架構的深刻理解。以此為起點，你可以繼續探索更高級的主題，如自定義文章類型、主題定製器 API、塊編輯器（Gutenberg）支持等，逐步成為一名專業的 WordPress 主題開發者。
常见问题解答（FAQ）
一個 WordPress 主題最少需要幾個文件？
一個能夠被 WordPress 識別並激活的主題，最少需要兩個文件：style.css 以及 index.php其中,style.css 必須包含正確的主題信息頭部註釋。
為什麼我的自定義樣式沒有生效？
這通常是由於 CSS 選擇器優先級不夠，或樣式表沒有正確加載導致的。首先，檢查瀏覽器開發者工具，確認你的樣式表文件是否成功加載，以及你的 CSS 規則是否被其他更高優先級的規則覆蓋。其次，確保你是通過 functions.php 请将下面的英文句子翻译成中文，并详细解释：\n中的 wp_enqueue_style() 函數來加載樣式，而不是直接在 HTML 中寫 <link> 标签。
如何為主題添加自定義頁面模板？
創建一個新的 PHP 文件，例如 page-fullwidth.php。在該文件的最頂部，添加以下 PHP 註釋來聲明模板名稱：<?php /* Template Name: 全宽页面 */ ?>。然後，你可以在這個文件中編寫不同於默認頁面模板 page.php 的佈局和代碼。創建或編輯頁面時，在“頁面屬性”模塊中就可以選擇這個新模板了。
functions.php 和插件有什麼區別？
functions.php 是主題的一部分，其功能與當前主題深度綁定。如果你切換主題，functions.php 中的代碼將不再生效。而插件提供的功能是獨立於主題的，無論使用哪個主題，只要插件激活，其功能就會存在。通常，與網站視覺表現緊密相關的功能放在主題中，而通用、獨立的功能更適合做成插件。
怎样让我的主题支持多语言（国际化）？
你需要做好兩件事：準備和加載翻譯文件。首先，在代碼中所有面向用户的字符串（如 ('Read More', 'my-first-theme')）都必須使用像 () 或者 _e() 這樣的翻譯函數進行包裝，並確保第二個參數（文本域）與 style.css 中聲明的“Text Domain”一致。然後，使用工具如 Poedit 來創建 .pot 模板文件，並翻譯生成對應的 .po 以及 .mo 文件。最後，在 functions.php 请将下文翻译成中文，并详细说明翻译过程： load_theme_textdomain() 函數來加載翻譯文件。
接下来，我该怎么做呢？
延伸阅读与实用知识
下方这些内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始看起，然后再逐步扩展到相关主题，这样通常效果会更好。