開發環境與項目初始化
進入現代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">
</head>
<body no numeric noise key 1002>
<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="/zh-hk/</?php the_permalink(); ?>"></a></h2>
</header>
<div class="entry-content">
</div>
</article>
<p></p>在這個循環中，你使用了多個模板標籤，如 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></p>
// 在导航菜单注册时
'primary' => esc_html__( 'Primary Menu', 'my-awesome-theme' ),準備好代碼後，你可以使用工具如 Poedit 來掃描所有翻譯字符串，生成 .pot（模板文件），然後創建對應的 .po 以及 .mo 翻譯文件，並放置於主題的 /languages 目錄中。
总结
本篇長文系統地介紹了現代WordPress主題開發從環境搭建到功能完善的核心流程。我們從建立標準化的項目結構開始，強調了 style.css 以及 theme.json 的重要性。隨後，我們深入探討了構建模板層級的邏輯，特別是通過文章循環動態展示內容。在功能增強部分，我們學習瞭如何使用 functions.php 來擴展主題，註冊菜單、小工具並支持特色圖像。
最後，我們聚焦於前端資源管理和代碼質量，強調了通過WordPress標準方法加入樣式腳本、進行國際化準備的重要性。遵循這些最佳實踐，不僅能開發出結構清晰、易於維護的主題，更能確保其兼容性、安全性和可擴展性，為構建更復雜的項目打下堅實基礎。
常见问题解答（FAQ）
主題和插件有什麼區別？功能代碼應該放在哪裏？
主題負責控制網站內容的視覺呈現和佈局（即“外觀”），而插件則用於為網站添加獨立的功能（如聯繫表單、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錯誤和資源加載問題，也是前端調試的必備技能。
接下来，我该怎么做呢？
延伸阅读与实用知识
下方这些内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始看起，然后再逐步扩展到相关主题，这样通常效果会更好。