`functions.php`文件嘅定義同核心作用
喺WordPress主題入面，functions.php係一個特殊而強大嘅文件。佢本質上係一個主題專用嘅插件文件，隨住主題嘅激活而載入，隨住主題嘅停用而失效。呢個文件嘅主要作用係為主題添加自訂功能同修改WordPress核心行為，而唔使修改核心文件或者創建獨立插件。呢個意味住開發者可以集中管理主題嘅所有定制邏輯，由簡單嘅功能啟用，好似特色圖像，到複雜嘅自訂文章類型註冊、主題選項面板嘅構建同埋鉤子同過濾器嘅運用。
理解functions.php嘅作用範圍至關重要。佢只對其所屬嘅主題有效，咁樣確保咗功能嘅可移植性同主題嘅完整性。透過喺呢個文件入面編寫代碼，你可以安全咁為你嘅網站添加幾乎任何功能，同時保持未來更新同主題遷移嘅靈活性。對於初學者同資深開發者嚟講，深入研究並熟練掌握呢個文件，係由基礎主題修改走向高級主題開發嘅必經之路。
主題功能嘅初始配置同常用函數
主題支援功能嘅啟用
每個現代WordPress主題都應該聲明佢支援邊啲核心功能，呢個需要透過add_theme_support()函數嚟實現。呢個函數話畀WordPress知你嘅主題能夠處理同呈現邊啲特性，例如文章縮圖、自訂Logo、HTML5標記支援等等。
推薦閱讀 WordPress主題開發進階指南：由零建立專業級響應式主題。
if ( ! function_exists( 'mytheme_setup' ) ) {
function mytheme_setup() {
// 支持文章和评论的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,
) );
// 对文章格式和页面标题的HTML5标记支持
add_theme_support( 'html5', array( 'search-form', 'comment-form', 'comment-list', 'gallery', 'caption' ) );
add_theme_support( 'title-tag' );
}
}
add_action( 'after_setup_theme', 'mytheme_setup' );將配置代碼包喺after_setup_theme鉤子入面，確保佢哋喺主題初始化嗰陣被正確執行。
導航菜單同側邊欄嘅註冊
一個完整嘅主題通常包含可自訂嘅導航菜單同小工具區域（側邊欄）。呢度需要用register_nav_menus()同埋register_sidebar()函數。
// 注册主题菜单位置
function mytheme_register_menus() {
register_nav_menus( array(
'primary' => __( '主导航菜单', 'mytheme' ),
'footer' => __( '底部菜单', 'mytheme' ),
) );
}
add_action( 'after_setup_theme', 'mytheme_register_menus' );
// 注册一个小工具区域
function mytheme_widgets_init() {
register_sidebar( array(
'name' => __( '主侧边栏', 'mytheme' ),
'id' => 'sidebar-1',
'description' => __( '在此添加主侧边栏的小工具。', 'mytheme' ),
'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', 'mytheme_widgets_init' );腳本同樣式嘅隊列化管理
為咗跟從WordPress開發嘅最佳實踐同埋避免衝突，所有JavaScript同CSS檔案都應該透過wp_enqueue_scripts掛鉤嚟加載。WordPress提供咗wp_enqueue_style()同埋wp_enqueue_script()函數嚟實現呢個目的。
function mytheme_scripts() {
// 引入主题的主样式表
wp_enqueue_style( 'mytheme-style', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) );
// 引入Google Fonts
wp_enqueue_style( 'mytheme-google-fonts', 'https://fonts.example.com/family=Open+Sans&display=swap', array(), null );
// 引入自定义JavaScript文件，并依赖jQuery
wp_enqueue_script( 'mytheme-navigation', get_template_directory_uri() . '/js/navigation.js', array( 'jquery' ), wp_get_theme()->get( 'Version' ), true );
// 为脚本局部化数据，将PHP变量安全传递到JavaScript
wp_localize_script( 'mytheme-navigation', 'mythemeScreenReaderText', array(
'expand' => __( '展开子菜单', 'mytheme' ),
'collapse' => __( '收起子菜单', 'mytheme' ),
) );
}
add_action( 'wp_enqueue_scripts', 'mytheme_scripts' );呢個方法確保咗依賴關係（例如jQuery）能夠正確處理，同埋可以方便咁控制腳本嘅加載位置（頁頭或者頁腳）。對於管理後台嘅樣式同腳本，應該用admin_enqueue_scripts鉤子。
利用鉤子同過濾器深度自訂
理解動作同過濾器
WordPress嘅核心擴展性好大程度上依賴佢嘅插件架構，即係鉤子（Hooks）。鉤子分為兩類：動作（Action）同過濾器（Filter）。動作容許你喺特定時刻執行自訂代碼，過濾器容許你修改喺運行過程中傳遞嘅數據。functions.php係用呢啲鈎嘅絕佳地方。
推薦閱讀 從零到一：WordPress主題開發全流程實戰指南。
例如，你可以用wp_head喺頁面部分加自訂代碼，或者用the_content過濾器改文章內容嘅輸出。
整自訂文章類型
為咗建立超越預設「文章」同「頁面」嘅內容類型，你需要註冊自訂文章類型。通常會擺喺init掛鉤度執行。
function mytheme_register_portfolio() {
$labels = array(
'name' => _x( '作品集', '作品集通用名称', 'mytheme' ),
'singular_name' => _x( '作品', '作品单数名称', 'mytheme' ),
'menu_name' => __( '作品集', 'mytheme' ),
);
$args = array(
'labels' => $labels,
'public' => true,
'publicly_queryable' => true,
'show_ui' => true,
'show_in_menu' => true,
'query_var' => true,
'rewrite' => array( 'slug' => 'portfolio' ),
'capability_type' => 'post',
'has_archive' => true,
'hierarchical' => false,
'menu_position' => 5,
'supports' => array( 'title', 'editor', 'thumbnail', 'excerpt', 'comments' ),
);
register_post_type( 'portfolio', $args );
}
add_action( 'init', 'mytheme_register_portfolio' );修改預設查詢同輸出
過濾器可以用嚟精細控制網站嘅各種輸出。例如，如果你想喺歸檔頁面只顯示某個分類嘅文章，或者修改摘要嘅長度。
// 修改主页查询，排除特定分类
function mytheme_exclude_category_home( $query ) {
if ( $query->is_home() && $query->is_main_query() ) {
$query->set( 'cat', '-5, -9' ); // 排除ID为5和9的分类
}
}
add_action( 'pre_get_posts', 'mytheme_exclude_category_home' );
// 修改摘录长度
function mytheme_excerpt_length( $length ) {
return 30; // 将默认的55词改为30词
}
add_filter( 'excerpt_length', 'mytheme_excerpt_length' );安全、效能同維護最佳實踐
一個健壯嘅functions.php檔案唔單止要實現功能，更加要關注安全性、性能同可維護性。
首先，要對所有用戶輸入進行轉義同驗證。WordPress提供咗豐富嘅安全函數，例如esc_html()、esc_url()同埋sanitize_text_field()。確保喺輸出任何動態數據到前端嗰陣，都要用合適嘅轉義函數。
其次，注意代碼組織。一個超過數百行嘅functions.php檔案會變得難以維護。最佳方案係將其作為「加載器」，將唔同功能嘅代碼分割到主題目錄下嘅獨立PHP檔案中，然後喺functions.php入面，經由require_once引入。
推薦閱讀 快速掌握 WordPress 主題開發：從入門到實戰嘅完整指南。
// 在functions.php中组织代码
require_once get_template_directory() . '/inc/theme-setup.php';
require_once get_template_directory() . '/inc/enqueue-scripts.php';
require_once get_template_directory() . '/inc/custom-post-types.php';
require_once get_template_directory() . '/inc/custom-functions.php';對於效能，應避免喺functions.php中直接進行耗時嘅數據庫查詢或檔案操作，尤其係喺每個頁面加載時都執行嘅代碼中。使用緩存、合理利用掛鉤執行嘅時機，並對唔使用嘅功能及時移除其掛鉤。
最後，為你嘅自訂函數同掛鈎加返清晰嘅中文註解，同埋用主題文字域（好似上面mytheme）為所有輸出俾用戶嘅字串做好國際化準備，咁樣會好方便之後嘅協作同主題嘅本地化。
摘要
functions.php文件係 WordPress 主題開發嘅心臟同中樞神經系統。由最初嘅主題功能支援、選單同側邊欄註冊，到腳本樣式嘅標準化引入，再透過動作同過濾器實現深入、無侵入式嘅定制，呢個文件俾咗開發者塑造 WordPress 行為嘅強大能力。跟返安全編碼、效能優化同模組化組織嘅現代開發實踐，會令你嘅functions.php文件唔單止強大，而且穩健、易於維護同擴展。掌握佢，就意味住你掌握咗由預設主題使用者轉變為真正主題創造者嘅關鍵。
常見問題
子主題點樣安全噉修改functions.php檔案
創建子主題係而家最安全、最推薦嘅方法去修改同擴展父主題功能。你可以喺子主題目錄下創建自己嘅functions.php檔案。呢個檔案唔會俾父主題嘅更新所覆蓋，而且佢會先過父主題嘅functions.php檔案被加載。喺子主題嘅呢個檔案入面，你可以直接加新函數，亦都可以透過掛勾覆蓋父主題嘅函數。例如，如果你淨係想修改父主題嘅樣式加載方式，可以喺子主題嘅functions.php中解除父主题嘅樣式隊列掛鈎，然後重新排隊你自己嘅樣式。
點解我加嘅代碼冇生效
代碼冇生效有幾個常見原因。首先，檢查語法錯誤，一個微小嘅PHP語法錯誤可能導致成個functions.php檔案執行失敗。你可以通過啟用WP_DEBUG模式睇下有冇錯誤信息。其次，確認代碼係咪加咗喺正確嘅位置（例如，函數係咪定義咗喺掛鈎內部，而該掛鈎冇被觸發）。第三，檢查函數名或者掛鈎名有冇衝突，最好為自訂函數加上獨特嘅前綴。最後，確保你嘅修改確實已經保存，並且喺睇頁面時清空咗瀏覽器同WordPress嘅緩存。
點樣喺functions.php度加自訂短代碼
在functions.php度加短代碼係非常普遍嘅需求。用add_shortcode()函數就可以輕鬆實現。首先，你需要定義一個回調函數來生成短代碼嘅輸出內容，然後用add_shortcode()將佢註冊。
// 定义短代码回调函数
function mytheme_contact_button_shortcode( $atts ) {
// 解析短代码属性
$atts = shortcode_atts( array(
'text' => '联系我们',
'url' => '/contact',
), $atts, 'contact_button' );
// 返回安全的HTML输出
return '<a href="/yue/' . esc_url( $atts['url'] ) . '/" class="contact-button">' . esc_html( $atts['text'] ) . '</a>';
}
// 註冊短代碼
add_shortcode( 'contact_button', 'mytheme_contact_button_shortcode' );之後，你就可以喺文章、頁面或者小工具度用[contact_button text="点击联系" url="/contact-us"]嚟調用呢個短代碼喇。
同獨立插件相比，喺functions.php度加功能有咩優劣
在functions.php中加入功能嘅最大好處係緊密整合同埋方便。所有代碼都同主題綁埋一齊，方便管理同分發，尤其當呢啲功能係主題外觀同體驗嘅核心組成部分時。其缺點在於，呢啲功能同主題生命週期綁定，一旦轉換主題，功能就會消失，可能導致網站內容或功能嘅缺失。而獨立外掛就提供咗功能同外觀嘅分離，無論轉換咩主題，功能都保持不變，對於通用性功能（例如SEO、表單、緩存）嚟講係更好嘅選擇。最佳實踐係：當功能純粹係表現層（例如特定嘅版面控制、主題獨有嘅樣式擴展），放喺functions.php中；當功能係數據層或通用邏輯（例如自定義文章類型、用戶管理增強），尤其係希望喺唔同主題之間保持時，應該創建獨立外掛。
下一步應該點做?
延伸閱讀及實用知識
以下內容與本文主題相關,適合進一步閱讀。一般而言,最好由與你目前問題最緊密相關的文章開始,然後逐步擴展到周邊主題。