WordPress主題開發入門指南：從零構建第一個自定義主題

准备工作与环境搭建

在開始編寫程式碼之前，你需要一個合適的開發環境。這通常意味著在你的本地計算機上搭建一個能夠執行 WordPress 的伺服器環境。你可以選擇使用整合的軟體包，如 XAMPP、MAMP（適用於 Mac）或 Local by Flywheel，它們可以一鍵安裝 Apache、MySQL 和 PHP。安裝好本地伺服器後，從 WordPress.org 下載最新的 WordPress 程式並完成安裝。

接下來，你需要找到 WordPress 的主題目錄。它位於 wp-content/themes/在该目录下，为你的新主题创建一个文件夹，例如： my-first-theme。這個資料夾的名稱就是你的主題識別符號，建議使用小寫字母、數字和連字元，避免空格。

一個 WordPress 主題最基礎的檔案只有兩個：style.css 以及 index.php。style.css 不僅是一個樣式表，更是一個主題的“身份證”，它透過檔案頭部的註釋塊來向 WordPress 宣告主題資訊。

推荐阅读入门级WordPress主题开发：从零开始构建自定义主题。

建立主題資訊檔案

style.css 檔案的開頭必須包含一個特定的樣式表頭部資訊。這是 WordPress 識別和載入主題的關鍵。下面是一個最基本的示例：

UltaHost WordPress 主機

30天退款保證，無限頻寬與資料庫，免費的 DDoS 防護，購買3年優惠50%

访问页面

/*
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
License: GNU General Public License v2 or later
Text Domain: my-first-theme
*/

其中,Text Domain 用於主題國際化（翻譯），通常與主題資料夾名稱保持一致。Theme Name 將顯示在 WordPress 後臺的“外觀”->“主題”列表中。

创建核心模板文件

index.php 是你的主題最核心的模板檔案。當 WordPress 找不到更具體的模板檔案（如 single.php 或者 page.php）時，就會使用它作為預設的備用模板。一個最簡單的 index.php 可以只包含獲取網站頭部、主迴圈和網站腳部的函式。

<main>
    <?php
    if ( have_posts() ) :
        while ( have_posts() ) : the_post();
            // 文章内容输出
            the_title( '<h2>', '</h2>' );
            the_content();
        endwhile;
    else :
        echo '<p>没有找到任何文章。</p>';
    endif;
    ?>
</main>

此時，你的主題已經可以被 WordPress 識別並激活了。雖然功能簡陋，但這是構建一切的基礎。

理解模板層級與核心檔案

WordPress 使用一套稱為“模板層級”的智慧系統來決定為當前請求的頁面使用哪個模板檔案。理解這個層級是高效開發的關鍵。其核心原則是：越具體的模板，優先順序越高。

推荐阅读入门级 WordPress 主题开发指南：从零开始搭建你的第一个主题。

文章与页面模板

對於單篇部落格文章，WordPress 會按以下順序尋找模板：single-post-{slug}.php -> single-post-{id}.php -> single-post.php -> single.php -> singular.php -> index.php例如，一篇名为“hello-world”的文章，将优先使用以下标题： single-post-hello-world.php。

對於獨立頁面（Page），順序是：custom template（頁面屬性中指定） -> page-{slug}.php -> page-{id}.php -> page.php -> singular.php -> index.php。

歸檔與首頁模板

部落格文章列表頁（歸檔頁）也有其規則。主部落格首頁：home.php -> index.php分类归档页面：category-{slug}.php -> category-{id}.php -> category.php -> archive.php -> index.php标签、作者、日期归档等都遵循类似的模式。

hostng.com 共享主机

高效能，配备 AMD EPYC CPU、NVMe SSD 存储和 LiteSpeed，全天候 24 小时专业内部支持，先进的安全措施包括 SSL、暴力破解、恶意软件和 DDoS 防护，节省高达 731 TB/月的带宽成本。

访问页面

搜尋頁面使用 search.php用于404错误页面 404.php若这些特定文件不存在，最终都会回退到默认设置。 index.php。

创建常用模板文件

基於以上層級，你應該建立幾個最常用的模板檔案來增強主題功能。首先是 header.php它包含 HTML 文件的元数据，如标题、描述和关键字。元数据用于向搜索引擎提供有关页面的信息，帮助用户更轻松地找到相关内容。 <head> 部分和網站的頁頭區域。

<!DOCTYPE html>
<html no numeric noise key 1008>
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    
</head>
<body no numeric noise key 1005>

<header>
    <h1><a href="/zh-tw/</?php echo esc_url( home_url( '/' ) ); ?>"></a></h1>
    <p></p>
    <nav>
        'primary',
            'container'      =&gt; false,
        ) );
        ?&gt;
    </nav>
</header>

footer.php 包含頁尾內容和指令碼呼叫。

<footer>
    <p>©</p>
</footer>

</body>
</html>

functions.php 是主題的“大腦”，用於新增功能、註冊選單、樣式表和指令碼。

主题功能与样式整合

functions.php 檔案不是必須的，但沒有它，主題的功能將非常有限。這個檔案在主題初始化時自動載入，是掛載功能、過濾器和鉤子的最佳場所。

InterServer 共享主机

虚拟主机的月费为1TB+5TB，价格为2.50美元。首月优惠价为1TB+5TB，价格为0.1美元。优惠码为"tryinterserver"。平台提供461个云应用脚本，一键安装便捷。

访问页面

註冊導航選單與側邊欄

关于 functions.php 在中文中，我们可以用“使用”来表达“use”的意思。比如：“我使用了这个工具。”或者“他使用了那个方法。” register_nav_menus() 函式來宣告主題支援的選單位置。

function my_first_theme_setup() {
    // 注册一个主导航菜单
    register_nav_menus( array(
        'primary' => __( '主导航菜单', 'my-first-theme' ),
    ) );
    // 为文章和评论添加 RSS feed 链接支持
    add_theme_support( 'automatic-feed-links' );
    // 支持文章特色图像
    add_theme_support( 'post-thumbnails' );
    // 支持 HTML5 标记
    add_theme_support( 'html5', array( 'comment-list', 'comment-form', 'search-form', 'gallery', 'caption', 'style', 'script' ) );
    // 支持自定义 logo
    add_theme_support( 'custom-logo' );
}
add_action( 'after_setup_theme', 'my_first_theme_setup' );

使用（注：此处"使用"指的是某种产品或服务的使用情况） register_sidebar() 函式來註冊小工具區域（側邊欄）。

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'  =&gt; '</section>',
        'before_title'  =&gt; '<h2 class="widget-title">',
        'after_title'   =&gt; '</h2>',
    ) );
}
add_action( 'widgets_init', 'my_first_theme_widgets_init' );

动态引入样式和脚本

正確的做法是使用 wp_enqueue_style() 以及 wp_enqueue_script() 函式來將 CSS 和 JavaScript 檔案加入佇列。這確保了依賴關係被正確處理，並且不會重複載入。

function my_first_theme_scripts() {
    // 引入主题的主样式表
    wp_enqueue_style( 'my-first-theme-style', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) );

// 引入一个自定义的 CSS 文件
    wp_enqueue_style( 'my-first-theme-custom', get_template_directory_uri() . '/assets/css/custom.css', array( 'my-first-theme-style' ), '1.0' );

// 引入一个 JavaScript 文件
    wp_enqueue_script( 'my-first-theme-navigation', get_template_directory_uri() . '/assets/js/navigation.js', array(), '1.0', true );

// 为评论回复功能添加脚本（仅在需要时加载）
    if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
        wp_enqueue_script( 'comment-reply' );
    }
}
add_action( 'wp_enqueue_scripts', 'my_first_theme_scripts' );

完善模板與進階概念

隨著主題核心功能的建立，你可以開始細化各個模板檔案，實現更專業的佈局和功能。

構建文章列表迴圈

关于 archive.php 或者 home.php 中，你通常需要以摘要形式展示多篇文章。可以利用 WordPress 提供的模板函式，如 the_excerpt()、the_post_thumbnail()。

<div class="posts-list">
        
            <article id="post-<?php the_ID(); ?>" no numeric noise key 1015>
                
                    <a href="/zh-tw/</?php the_permalink(); ?>">
                        
                    </a>
                
                <h2><a href="/zh-tw/</?php the_permalink(); ?>"></a></h2>
                <div class="entry-meta">
                    |
                </div>
                <div class="entry-summary">
                    
                </div>
                <a href="/zh-tw/</?php the_permalink(); ?>" class="read-more">阅读更多</a>
            </article>
        
    </div>
    

    <p><?php _e( '抱歉，没有找到符合条件的内容。', 'my-first-theme' ); ?></p>

實現評論模板

評論功能是部落格的重要組成部分。WordPress 提供了強大的評論模板函式 comments_template()最佳实践是将评论的显示和表单放在一个单独的文件中，通常是 comments.php然后，再在 single.php 中呼叫它。

关于 single.php 的文章內容輸出後，新增：

<?php
if ( comments_open() || get_comments_number() ) :
    comments_template();
endif;
?>

然後建立 comments.php 檔案來處理評論列表和表單的渲染。你可以從現成的主題（如 Twenty Twenty-One）中複製一個基礎的 comments.php 並進行修改，這是一個複雜但標準化的部分。

新增主题自定义选项

為了讓使用者無需修改程式碼就能調整主題，你可以利用 WordPress 定製器（Customizer）API。透過 WP_Customize_Manager 物件，你可以新增設定、控制元件和區域。

function my_first_theme_customize_register( $wp_customize ) {
    // 添加一个‘颜色’板块
    $wp_customize->add_section( 'theme_colors', array(
        'title'    => __( '主题颜色', 'my-first-theme' ),
        'priority' => 30,
    ) );

// 添加一个‘主色调’设置
    $wp_customize->add_setting( 'primary_color', array(
        'default'           => '#0073aa',
        'sanitize_callback' => 'sanitize_hex_color',
        'transport'         => 'postMessage', // 实时预览
    ) );

// 为该设置添加一个颜色选择器控件
    $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'primary_color', array(
        'label'    => __( '主色调', 'my-first-theme' ),
        'section'  => 'theme_colors',
        'settings' => 'primary_color',
    ) ) );
}
add_action( 'customize_register', 'my_first_theme_customize_register' );

之後，你可以在 style.css 或透過內聯樣式動態輸出這個顏色值。

总结

WordPress 主題開發是一個從結構到樣式，從基礎到細節的漸進過程。透過從最基礎的 style.css 以及 index.php 開始，你建立了主題的基石。理解模板層級讓你能建立針對不同頁面型別的精準模板。functions.php 則是你擴充套件主題功能的強大工具，用於整合導航、小工具、樣式指令碼以及定製器選項。最後，透過完善文章迴圈、評論模板和自定義選項，你的主題將變得既專業又使用者友好。記住，不斷參考官方手冊和現有優質主題的程式碼，是提升開發技能的最佳途徑。

常见问题解答（FAQ）

一個 WordPress 主題最少需要哪些檔案？

一個 WordPress 主題理論上只需要兩個檔案：style.css 以及 index.php。style.css 必須包含正確的主題資訊頭部註釋，以供 WordPress 識別。而 index.php 作為所有頁面的預設備用模板。當然，這樣的主題功能非常有限，但可以啟用並執行。

怎样让我的主题支持多语言（国际化）？

你需要使用 WordPress 的國際化（i18n）功能。在 functions.php 在中文中，我们可以用“使用”来表达“use”的意思。比如：“我使用了这个工具。”或者“他使用了那个方法。” load_theme_textdomain() 函式來載入翻譯檔案。在你的主題程式碼中，將所有面向用戶的字串用 __()（用於回顯）或 _e()（用於直接輸出）等翻譯函式包裹，並指定你在 style.css 请将以下中文简体句子翻译成中文简体，并详细解释其含义： \n中定義的 Text Domain。然後，可以使用如 Poedit 這樣的工具生成 .pot 模板檔案，供翻譯人員建立 .po 和 .mo 翻譯檔案。

為什麼我的自定義樣式或指令碼沒有載入？

最常見的原因是你在 functions.php 中排隊載入樣式或指令碼的鉤子函式沒有正確連線到 WordPress 的動作上。確保你已將包含 wp_enqueue_style() 或者 wp_enqueue_script() 的函式，透過 add_action( ‘wp_enqueue_scripts’, ‘your_function_name’ ) 掛載到 wp_enqueue_scripts 這個動作上。同時，檢查檔案路徑（get_template_directory_uri()）是否正確，以及檔案是否真實存在於該路徑下。

如何為特定頁面建立獨特的模板？

主要有兩種方法。第一種是使用頁面模板：在 PHP 檔案頂部新增一個特定的註釋塊，例如 /* Template Name: 全宽页面 */然后，将其保存到你的主题目录中。在 WordPress 后台编辑页面中，你可以在“页面属性”->“模板”下拉框中选择它。第二种方法是利用模板层级：例如，要为别名为“contact”的页面创建模板，只需创建一个名为的模板即可。 page-contact.php 的檔案，WordPress 會自動優先使用它來渲染該頁面。前者的優勢是可以在後臺自由分配，後者的優勢是命名規則自動生效。

下一步，该怎么做呢？

如果你正在搭建或优化WordPress网站，建议你继续阅读关于性能优化、插件配置和主题定制的相关内容。

延伸阅读与实用知识

下方列出的内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始阅读，然后逐步扩展到相关主题，这样效果通常会更好。

WordPress主題開發入門：從零開始構建你的第一個自定義主題

准备工作与环境搭建

建立主題資訊檔案

创建核心模板文件

理解模板層級與核心檔案

文章与页面模板

歸檔與首頁模板

创建常用模板文件

主题功能与样式整合

註冊導航選單與側邊欄

动态引入样式和脚本

完善模板與進階概念

構建文章列表迴圈

實現評論模板

新增主题自定义选项

总结

常见问题解答（FAQ）

一個 WordPress 主題最少需要哪些檔案？

怎样让我的主题支持多语言（国际化）？

為什麼我的自定義樣式或指令碼沒有載入？

如何為特定頁面建立獨特的模板？

下一步，该怎么做呢？

延伸阅读与实用知识

Cloudways 跨多雲平台的全管理: DigitalOcean, Vultr, Linode, AWS, Google cloud

WordPress主題開發入門：從零開始構建你的第一個自定義主題

准备工作与环境搭建

建立主題資訊檔案

创建核心模板文件

理解模板層級與核心檔案

文章与页面模板

歸檔與首頁模板

创建常用模板文件

主题功能与样式整合

註冊導航選單與側邊欄

动态引入样式和脚本

完善模板與進階概念

構建文章列表迴圈

實現評論模板

新增主题自定义选项

总结

常见问题解答（FAQ）

一個 WordPress 主題最少需要哪些檔案？

怎样让我的主题支持多语言（国际化）？

為什麼我的自定義樣式或指令碼沒有載入？

如何為特定頁面建立獨特的模板？

下一步，该怎么做呢？

延伸阅读与实用知识

相关推荐

WooCommerce 建站終極指南：從零到一打造專業電商網站

WordPress 的意義與價值

WooCommerce 中文完整入門指南：從零開始搭建你的線上商店

為什麼選擇 WooCommerce 構建你的線上商店