開發環境同項目初始化
進入現代WordPress主題開發嘅第一步，係建立一個高效且符合標準嘅本地開發環境。今日，我哋唔再直接喺伺服器上進行開發，而係用本地工具鏈嚟提升效率。
對於本地環境，你可以揀一體化工具，例如 Local、Laragon 或 MAMP。呢啲工具一鍵式安裝Apache/Nginx、PHP同MySQL，大大簡化咗環境配置過程。揀邊一個主要取決於你嘅操作系統偏好同具體功能需求。
點樣正確設定主題目錄結構
一個清晰、有組織嘅目錄結構係專業主題開發嘅基石。佢唔單止可以令你自己輕鬆維護代碼，亦方便其他開發者理解同協作。現代WordPress主題通常跟隨一種類似「模式」嘅結構。
推薦閱讀 WordPress主題開發入門指南：從零開始創建你嘅第一個自訂主題。
喺你嘅WordPress安裝目錄下嘅 wp-content/themes 文件夾入面，創建一個以你主題名稱命名嘅文件夾，例如 my-awesome-theme。然後，喺呢個文件夾入面，建議建立以下核心目錄：
* /assets：用嚟存放所有靜態資源。
* /assets/css：存放樣式表，例如 style.css 同埋 editor-style.css。
* /assets/js：存放JavaScript檔案。
* /assets/images：存放圖片、圖標等媒體檔案。
* /assets/fonts：存放自訂字型。
* /template-parts：存放可重用嘅模板片段，例如頁眉、頁腳、文章元數據等等。
* /inc 或 /includes：存放主題功能增強檔案，例如自訂函數、小工具註冊、自訂文章類型定義等等。
* /patterns（可選但推薦）：存放全站編輯器嘅區塊模式定義檔案。
建立必需嘅主題信息檔案
每個WordPress主題都必須有一個叫做 style.css 嘅檔案，佢唔單止係樣式表，更加係主題嘅「身份證」。呢個檔案頂部嘅註釋頭信息係WordPress識別主題嘅關鍵。
/*
Theme Name: 我的炫酷主题
Theme URI: https://example.com/my-awesome-theme
Author: 你的名字
Author URI: https://yourwebsite.com
Description: 一个专为博客和杂志网站设计的现代化、响应式WordPress主题。
Version: 1.0.0
Tested up to: 6.5
Requires at least: 6.0
Requires PHP: 7.4
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-awesome-theme
Domain Path: /languages
*/其中，Text Domain 用於國際化，係你嘅主題喺翻譯檔案中嘅唯一標識。Requires at least 同埋 Requires PHP 呢個指定咗主題運行所需嘅最低WordPress同PHP版本，對用戶體驗同安全性都好重要㗎。
另外，為咗支援全站編輯器（FSE）功能，你仲需要創建一個 theme.json 檔案。呢個檔案係Gutenberg編輯器同主題之間溝通嘅橋樑，用嚟全局定義樣式、調色板、排版設定等等。
構建核心主題模板
模板檔案係WordPress主題嘅骨架，佢哋決定咗唔同類型嘅內容點樣呈現出嚟。WordPress會根據「模板層級」自動揀合適嘅模板檔案嚟顯示頁面。
推薦閱讀 WordPress主題開發入門指南：從零開始打造客製化網站。
最基本嘅兩個模板文件係 index.php（主模板，作為兜底選擇）同埋 style.css（樣式表）。但要創建一個功能完整嘅主題，你需要從以下幾個核心模板開始構建。
點樣構建網站頭部同尾部
網站頭部同尾部係每個頁面共用嘅部分。我哋會將佢哢分別放喺 header.php 同埋 footer.php 入面。
在 header.php 檔案入面，你需要放HTML文檔嘅head部分，並調用WordPress嘅核心函數。關鍵函數包括 wp_head()，佢容許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">
<?php wp_head(); ?>
</head>
<body no numeric noise key 1002>
<?php wp_body_open(); ?>
<header id="masthead" class="site-header">
<!-- 你的网站导航和Logo代码 -->
</header>footer.php 就負責閂返喺 header.php 喺度打開嘅標籤，並調用 wp_footer() 函數，呢個對於載入腳本同插件功能係至關重要嘅。
點樣創建文章循環
文章循環係WordPress主題嘅核心邏輯，佢用嚟從數據庫度搵同顯示文章。呢個邏輯通常擺喺 index.php、single.php（單篇文章）或 page.php（單頁）中。
一個基礎嘅文章循環結構如下。佢用 have_posts() 同埋 the_post() 函數嚟遍歷查詢到嘅文章。
推薦閱讀 終極指南：點樣開發一個強大又靈活嘅WordPress主題。
<article id="post-<?php the_ID(); ?>" no numeric noise key 1007>
<header class="entry-header">
<h2 class="entry-title"><a href="/yue/</?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
</header>
<div class="entry-content">
<?php the_content(); ?>
</div>
</article>
<p><?php esc_html_e( 'Sorry, no posts matched your criteria.', 'my-awesome-theme' ); ?></p>
<?php endif; ?>喺呢個循環入面，你用到咗多個模板標籤，例如 the_title() 輸出文章標題，the_content() 輸出文章內容，the_permalink() 攞文章連結。
主題功能同自訂
所有主題功能增強嘅代碼，都應該集中管理，而唔係散落喺唔同模板檔案度。最佳做法係喺主題嘅根目錄度創建一個叫做 functions.php 嘅檔案。呢個檔案喺主題初始化嗰陣會自動載入，等同於你主題嘅「插件」。
點樣註冊導航菜單同埋側邊欄
自訂導航菜單同側邊欄（小工具區域）係主題嘅基本功能。你需要喺 functions.php 入面用特定嘅函數嚟註冊佢哋，然後先至可以喺後台嘅「外觀」菜單下邊進行管理。
使用 register_nav_menus() 函數嚟註冊菜單位置。例如，註冊一個「主菜單」同一個「頁尾菜單」。
function my_awesome_theme_setup() {
register_nav_menus(
array(
'primary' => esc_html__( 'Primary Menu', 'my-awesome-theme' ),
'footer' => esc_html__( 'Footer Menu', 'my-awesome-theme' ),
)
);
}
add_action( 'after_setup_theme', 'my_awesome_theme_setup' );註冊小工具區域（側邊欄）就需要用到 register_sidebar() 函數。你可以定義側邊欄嘅名稱、ID、描述同埋前後包裝嘅HTML標籤。
點樣為文章加入特色圖像支援
特色圖像（文章縮略圖）係現代內容網站嘅標準配備。WordPress預設唔開啟呢個功能，需要主題明確聲明支援。
你可以喺上面提到嘅 my_awesome_theme_setup() 函數中，使用 add_theme_support() 個函數用嚟啟動佢。呢個函數用嚟啟用各種WordPress核心同主題功能。
function my_awesome_theme_setup() {
// ... 之前的菜单注册代码 ...
add_theme_support( 'post-thumbnails' ); // 为“文章”和“页面”启用特色图像
// 你还可以设置缩略图尺寸
set_post_thumbnail_size( 800, 450, true ); // 默认特色图像尺寸， true表示裁剪
add_image_size( 'my-theme-blog-list', 400, 250, true ); // 自定义一个图像尺寸
}啟動咗之後，喺文章編輯介面就會出現「特色圖像」元框，容許用戶上傳或者揀選圖片。喺模板度，你可以用 the_post_thumbnail() 函數嚟輸出佢。
樣式、腳本同埋性能優化
正確咁將CSS同JavaScript檔案加入隊列係WordPress開發嘅關鍵實踐。千祈唔好直接喺模板檔案度用 <link> 或 <script> 標籤硬編碼資源，而應該用 wp_enqueue_style() 同埋 wp_enqueue_script() 函數。
點樣正確噉將CSS同JS加入隊列
在 functions.php 入面創建一個新嘅函數，用嚟註冊同排隊你嘅主題資源。然後，將呢個函數掛載到 wp_enqueue_scripts 呢個動作掛鉤上面。
function my_awesome_theme_scripts() {
// 注册并排队主样式表（style.css）
wp_enqueue_style( 'my-awesome-theme-style', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) );
// 注册并排队一个自定义的CSS文件
wp_enqueue_style( 'my-awesome-theme-main-css', get_template_directory_uri() . '/assets/css/main.css', array(), '1.0.0' );
// 注册并排队一个自定义的JavaScript文件
wp_enqueue_script( 'my-awesome-theme-navigation', get_template_directory_uri() . '/assets/js/navigation.js', array(), '1.0.0', true );
// 如果需要在脚本中使用PHP变量（如ajax_url），可以使用wp_localize_script
wp_localize_script( 'my-awesome-theme-navigation', 'myThemeData', array(
'ajaxurl' => admin_url( 'admin-ajax.php' ),
));
}
add_action( 'wp_enqueue_scripts', 'my_awesome_theme_scripts' );注意，最後一個參數係 true 表示腳本喺文檔底部（</body>前）加載，通常能提升頁面渲染效能。
如何實施國際化與本地化
為咗令你嘅主題能夠俾全世界使用，你需要進行國際化（i18n）處理。即係話所有喺模板同PHP代碼中輸出嘅文本字串，都應該俾翻譯函數包住。
最常用嘅函數係 esc_html__()（用於輸出轉義後嘅HTML）同 esc_html_e()（用嚟直接回返轉義後嘅HTML）。佢哋全部都需要喺主題頭資訊度定義好 Text Domain。
// 在文章循环的“没有文章”提示中
<p><?php esc_html_e( 'Sorry, no posts matched your criteria.', 'my-awesome-theme' ); ?></p>
// 在导航菜单注册时
'primary' => esc_html__( 'Primary Menu', 'my-awesome-theme' ),準備好代碼之後，你可以用好似Poedit呢類工具去掃描晒所有翻譯字串，生成 .pot（模板檔案），然後建立對應嘅 .po 同埋 .mo 翻譯檔案，並擺喺主題嘅 /languages 目錄入面。
摘要
呢篇長文有系統咁介紹咗現代WordPress主題開發，由環境搭建到功能完善嘅核心流程。我哋由建立標準化嘅項目結構開始，強調咗 style.css 同埋 theme.json 嘅重要性。跟住，我哋深入探討咗構建模板層級嘅邏輯，特別係透過文章循環動態展示內容。喺功能增強部分，我哋學識咗點樣用 functions.php 嚟擴展主題，註冊菜單、小工具同支援特色圖像。
最後，我哋集中講前端資源管理同代碼質量，強調咗透過WordPress標準方法加入樣式同腳本、進行國際化準備嘅重要性。跟住呢啲最佳實踐，唔單止可以開發出結構清晰、易於維護嘅主題，仲可以確保佢嘅兼容性、安全性同可擴展性，為構建更複雜嘅項目打下堅實基礎。
常見問題
主題同插件有咩分別？功能代碼應該放喺邊度？
主題負責控制網站內容嘅視覺呈現同佈局（即係「外觀」），而插件就用嚟為網站添加獨立嘅功能（例如聯絡表格、SEO優化、電子商務）。一個簡單嘅原則係：如果代碼係改變網站外觀嘅，佢屬於主題；如果佢係添加新功能嘅，就應該考慮做成插件。長遠嚟睇，將功能性代碼做成插件可以令你喺更換主題時保留呢啲功能。
必須使用 theme.json 檔案嗎？佢有咩好處？
對於面向未來嘅現代主題開發，強烈推薦使用 theme.json。佢唔再係可選嘅高級功能，而係WordPress全站編輯器架構嘅核心。佢嘅好處在於：能夠集中管理全局樣式同設定（顏色、字體、間距），為區塊編輯器提供更一致嘅體驗，減少內聯樣式，並簡化響應式設計同深色模式嘅實現。從WordPress 5.8開始，佢已成為主題開發嘅重要部分。
點樣自訂 WordPress 嘅預設小工具輸出？
WordPress 核心小工具（例如分類目錄、最新文章列表）嘅輸出 HTML 通常包含好多你唔需要嘅嵌套 div 同類名。你可以透過過濾器（Filter）嚟自訂佢哋。例如，用 widget_categories_args 過濾器修改分類目錄小工具嘅查詢參數，或者再徹底啲，透過 widget_categories_output 等過濾器直接修改其生成嘅HTML。另一種更現代、更靈活嘅方法係創建自己嘅自定義區塊嚟替代傳統小工具。
乜嘢係模板層級，點樣利用佢？
模板層級係WordPress決定用邊個模板檔案顯示當前頁面嘅決策系統。佢跟從「最具體」到「最通用」嘅原則。例如，對於一篇ID為123嘅文章，WordPress會依次搵：single-post-123.php -> single-post.php -> single.php -> singular.php -> 最後先係 index.php。你可以通過創建更具體嘅模板檔案（例如 category-news.php 嚟單獨設計「新聞」分類頁）去精確控制唔同頁面嘅外觀，咁樣比起喺單個檔案度寫大量條件判斷語句要清晰得多。
開發主題嗰陣點樣進行調試同埋錯誤排查？
首要步驟係喺 wp-config.php 文件入面開啟WordPress調試模式。將 WP_DEBUG 常數設定為 true。呢個做法會令所有PHP錯誤、警告同通知顯示喺頁面上。同時，建議設定 WP_DEBUG_LOG 为 true，將錯誤記錄到 /wp-content/debug.log 喺文件入面，要避免將錯誤訊息直接顯示俾訪客睇。另外，用瀏覽器開發者工具（Console同Network標籤）檢查JavaScript錯誤同資源載入問題，都係前端調試必備嘅技能。
下一步應該點做?
延伸閱讀及實用知識
以下內容與本文主題相關,適合進一步閱讀。一般而言,最好由與你目前問題最緊密相關的文章開始,然後逐步擴展到周邊主題。