主页/知识/WordPress/内容详情

全套WordPress主题开发指南：从零到一打造定制主题

3 分钟阅读时间
2026-03-13
2026-06-03
2,290
通过下方链接进行购物时，您无需支付额外费用，我就能获得佣金。.

准备工作与环境搭建

在開始編寫主題程式碼之前，一個穩定且高效的本地開發環境是必不可少的。這不僅能讓你快速預覽修改效果，還能避免對線上網站造成直接影響。建議使用如 Local by Flywheel、XAMPP 或 MAMP 等工具一鍵搭建包含 PHP 和 MySQL 的本地伺服器。

接下來，你需要確定主題的目錄結構。一個標準的 WordPress 主題通常包含以下核心檔案：style.css（主題樣式表和資訊頭）、index.php（主模板檔案）、functions.php（主題功能檔案）以及header.php、footer.php、sidebar.php等模板部分檔案。你可以在 WordPress 安裝目錄的wp-content/themes/下建立一個新的資料夾，例如“my-custom-theme”，並在此資料夾內開始建立這些檔案。

建立主題資訊標頭檔案

主題的“身份證”是style.css檔案。這個檔案不僅定義了主題的樣式，其頂部的註釋塊更是 WordPress 識別主題的關鍵。這個資訊頭必須嚴格遵循指定格式。

推荐阅读 怎样选择和定制适合你的 WordPress 主题？。

/*
Theme Name: My Custom Theme
Theme URI: https://example.com/my-custom-theme
Author: Your Name
Author URI: https://example.com
Description: 这是一个从头开始构建的自定义WordPress主题。
Version: 1.0.0
License: GPL v2 or later
Text Domain: my-custom-theme
*/

其中,Text Domain用於國際化（i18n），必須與主題資料夾名稱保持一致，這是載入翻譯檔案的關鍵標識。編寫完這個檔案後，你的主題就已經可以出現在 WordPress 後臺的“外觀”->“主題”列表中了，儘管它現在還沒有任何實際功能。

UltaHost WordPress 主機
30天退款保證，無限頻寬與資料庫，免費的 DDoS 防護，購買3年優惠50%
UltaHost LOGO 访问页面

构建基础模板文件

WordPress 採用模板層級系統來決定對不同的頁面請求使用哪個模板檔案。建立基礎模板是構建主題的骨架。

首先是index.php，它是所有頁面的最終回退模板。一個最簡單的index.php可以包含對其他模板部分的呼叫。

<?php get_header(); ?>

<main id="primary" class="site-main">
    <?php
    if ( have_posts() ) :
        while ( have_posts() ) :
            the_post();
            // 包含文章内容模板
            get_template_part( 'template-parts/content', get_post_type() );
        endwhile;
        the_posts_navigation();
    else :
        get_template_part( 'template-parts/content', 'none' );
    endif;
    ?>
</main>

<?php get_sidebar(); ?>
<?php get_footer(); ?>

建立頁頭和頁尾模板

header.php 檔案通常包含文件型別宣告、區域以及網站頁頭的公共部分。務必使用wp_head()函式，該鉤子允許外掛和主題在此處注入必要的程式碼（如樣式、指令碼、元標籤）。

<!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 核心功能所必需的。

推荐阅读 頂級WordPress主題開發指南：從零到精通構建與定製。

增強主題功能與自定義

functions.php檔案是你的主題的“控制中心”。它用於新增主題支援功能、註冊選單、側邊欄，以及排入樣式表和指令碼。

新增主題基礎支援

通过add_theme_support()函式，你可以為你的主題宣告支援各種 WordPress 功能。例如，啟用文章縮圖（特色影象）和自定義Logo是現代主題的標配。

function my_custom_theme_setup() {
    // 让主题支持文章和评论的RSS feed链接
    add_theme_support( 'automatic-feed-links' );
    // 启用文章特色图像功能
    add_theme_support( 'post-thumbnails' );
    // 启用自定义Logo功能
    add_theme_support( 'custom-logo', array(
        'height'      => 100,
        'width'       => 400,
        'flex-height' => true,
        'flex-width'  => true,
    ) );
    // 让WordPress生成和管理文档<title>标签
    add_theme_support( 'title-tag' );
}
add_action( 'after_setup_theme', 'my_custom_theme_setup' );

註冊選單與側邊欄

WordPress 選單透過register_nav_menus()函式註冊。你可以定義多個選單位置，例如“主導航”和“頁尾導航”。

hostng.com 共享主机
高效能，配备 AMD EPYC CPU、NVMe SSD 存储和 LiteSpeed，全天候 24 小时专业内部支持，先进的安全措施包括 SSL、暴力破解、恶意软件和 DDoS 防护，节省高达 731 TB/月的带宽成本。
hosting.com标志 访问页面 
function my_custom_theme_menus() {
    register_nav_menus(
        array(
            'menu-1' => esc_html__( 'Primary Menu', 'my-custom-theme' ),
            'menu-2' => esc_html__( 'Footer Menu', 'my-custom-theme' ),
        )
    );
}
add_action( 'init', 'my_custom_theme_menus' );

側邊欄（或稱“小工具區域”）透過register_sidebar()函式註冊。每個側邊欄都需要一個唯一的ID和描述。

function my_custom_theme_widgets_init() {
    register_sidebar(
        array(
            'name'          =&gt; esc_html__( 'Sidebar', 'my-custom-theme' ),
            'id'            =&gt; 'sidebar-1',
            'description'   =&gt; esc_html__( 'Add widgets here.', 'my-custom-theme' ),
            'before_widget' =&gt; '<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_custom_theme_widgets_init' );

樣式、指令碼與模板層級

為了確保主題的樣式和指令碼被正確載入且不會與其他外掛衝突，必須使用 WordPress 提供的排入佇列函式。

正確排入樣式與指令碼

永遠不要直接在模板檔案中使用或標籤引入資源。相反，應使用wp_enqueue_style()以及wp_enqueue_script()函数。

推荐阅读 WordPress主題開發完整指南：從零到上線的實戰教程。

function my_custom_theme_scripts() {
    // 排入主样式表
    wp_enqueue_style( 'my-custom-theme-style', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) );

// 排入自定义JavaScript文件
    wp_enqueue_script( 'my-custom-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_custom_theme_scripts' );

理解並使用模板層級

WordPress 的模板層級是一個強大的系統。例如，當訪問一篇部落格文章時，WordPress 會按以下順序尋找模板：single-post-{slug}.php -> single-post-{id}.php -> single-post.php -> single.php -> singular.php -> index.php。

你可以建立特定的模板檔案來覆蓋預設顯示。例如，建立一個page-about.php檔案，它將專門用於顯示“關於”頁面（前提是頁面的別名是“about”）。另一個強大的工具是front-page.php，它用於定義網站的前端展示頁，優先順序高於home.php（部落格文章索引頁）。

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

总结

本指南系統地介紹了從零開始構建一個 WordPress 自定義主題的核心步驟。從搭建本地環境、建立包含必要資訊頭的style.css，到構建index.php、header.php、footer.php等基礎模板檔案，形成了主題的骨架。透過functions.php檔案，我們增強了主題功能，包括新增主題支援、註冊導航選單和側邊欄。最後，我們強調了使用 WordPress 標準方法排入樣式與指令碼的重要性，並解釋了強大的模板層級系統，它允許開發者為不同的內容型別建立精確的顯示模板。遵循這些最佳實踐，不僅能創建出結構良好、易於維護的主題，還能確保其與 WordPress 核心及外掛的相容性。

常见问题解答（FAQ）

如何為我的主題新增自定義頁面模板？
建立自定義頁面模板，首先需要在你的主題目錄下建立一個新的 PHP 檔案，例如template-fullwidth.php。在該檔案的最頂部，你需要新增一個特定的模板名稱註釋。

<?php
/**
 * Template Name: 全宽页面模板
 * Description: 一个没有侧边栏的全宽页面模板。
 */

然後，你就可以在這個檔案裡編寫你的全寬頁面佈局程式碼了，通常以get_header();開頭。儲存後，在 WordPress 後臺編輯或建立頁面時，你就能在“頁面屬性”->“模板”下拉框中看到並使用“全寬頁面模板”了。

為什麼我的自定義選單沒有顯示出來？

選單未顯示通常有幾個原因。首先，請確保你已經在主題的functions.php通过中介机构register_nav_menus()函式註冊了選單位置。

其次，你需要到 WordPress 後臺的“外觀”->“選單”頁面，建立一個新選單，為其新增選單項（如頁面、文章、自定義連結），並在“選單設定”區域下方，將你建立的這個選單分配給你在主題中註冊的選單位置（例如“主導航”）。

最後，你需要在模板檔案（通常是header.php）中呼叫選單。使用wp_nav_menu()函式並指定正確的“theme_location”引數，例如：wp_nav_menu( array( ‘theme_location’ => ‘menu-1’ ) );。只有完成這三個步驟，選單才會正確顯示。

如何讓我的主題支援翻譯（國際化）？

讓你的主題支援翻譯，也稱為國際化（i18n），主要分為三個步驟。第一步是“準備”：在主題中所有需要翻譯的文字處，使用 WordPress 提供的翻譯函式進行包裹。最常用的是esc_html__( ‘文本’, ‘my-custom-theme’ )（輸出轉義後的HTML）和_e( ‘文本’, ‘my-custom-theme’ )（輸出並轉義）。務必確保第二個引數（文字域）與你在style.css请将以下中文简体句子翻译成中文简体，并详细解释其含义： \n中定義的Text Domain完全一致。

第二步是“生成”：使用諸如 Poedit 這類工具，掃描你的主題 PHP 檔案，生成一個.pot（Portable Object Template）模板檔案。翻譯者可以基於此檔案建立對應語言的.po和编译后的.mo文件。

第三步是“載入”：在你的functions.php文件中的after_setup_theme鉤子函數里，使用load_theme_textdomain( ‘my-custom-theme’, get_template_directory() . ‘/languages’ )來載入翻譯檔案。這樣，當用戶切換網站語言時，你的主題文字也會相應切換。

functions.php 檔案出錯會導致什麼後果？

functions.php檔案中的語法錯誤或致命錯誤將導致你的整個網站出現“白屏宕機”（即顯示一個空白頁面），並可能在後端看到一條致命錯誤資訊。這是因為該檔案在 WordPress 初始化的早期階段就被載入，其中的錯誤會中斷整個 WordPress 的載入程序。

如果遇到這種情況，你有幾種恢復方式。最直接的方法是透過 FTP 或主機提供的檔案管理器，將出錯的functions.php重命名文件（例如，将其改名为）functions.php.bak）或將其內容清空。這樣 WordPress 會將其視為一個空檔案，網站將恢復訪問，但你的主題自定義功能會暫時失效。之後，你可以修正程式碼錯誤，再將檔案恢復。因此，在修改functions.php前進行備份，並在本地開發環境充分測試，是非常好的習慣。

下一步，该怎么做呢？

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

延伸阅读与实用知识

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

标签：