WordPress 自定義字段完全指南：get_post_meta 函數深度解析

WordPress 自定義字段與 get_post_meta 函數深度解析

WordPress 的自定義字段（Custom Fields）是擴展文章、頁面等內容類型元數據的關鍵機制。其底層採用 wp_posts 主表配合 wp_postmeta 元數據表的 EAV（Entity-Attribute-Value）設計，以 post_id、meta_key、meta_value 三欄儲存靈活的鍵值對。

get_post_meta 函數詳解

該函數定義於 wp-includes/post.php，用於檢索指定文章的自定義字段值。

函數簽名

get_post_meta( int $post_id, string $key = '', bool $single = false ): mixed

參數說明

• $post_id（必填）：文章 ID。
• $key（選填）：自定義字段鍵名。留空則返回該文章所有字段的關聯陣列。
• $single（選填）：true 返回單一字串值；false（預設）返回陣列。

返回值

• 指定 $key 且 $single=true：返回字串（不存在則返回空字串）。
• 指定 $key 且 $single=false：返回陣列（不存在則返回空陣列）。
• 未指定 $key：返回所有字段的多維陣列。

實戰應用範例

範例 1：取得單一字段值（如文章瀏覽數）

$views = get_post_meta(get_the_ID(), 'views', true);
echo '瀏覽次數：' . ($views ? $views : 0);

範例 2：一次取得所有自定義字段

$all_meta = get_post_meta(get_the_ID());
foreach ($all_meta as $key => $values) {
    echo "$key: " . implode(', ', $values) . "
";
}

範例 3：搭配 WP_Query 篩選含特定字段的文章

$args = [
    'post_type'  => 'post',
    'meta_key'   => 'featured',
    'meta_value' => 'yes',
];
$featured_posts = new WP_Query($args);

進階技巧與注意事項

• 序列化資料： 儲存陣列/物件時 WordPress 會自動序列化，取出時自動反序列化，直接使用即可。
• 效能優化： 避免在迴圈中重複呼叫；善用 get_post_meta() 的快取機制（內部呼叫 get_metadata() 並透過 wp_cache_get()）。
• 欄位名稱衝突： 建議加上前綴（如 myplugin_）避免與主題/外掛衝突。
• REST API 支援： 使用 register_meta() 註冊 show_in_rest => true 即可在區塊編輯器與 REST API 中直接讀寫。

參考資源： WordPress 官方文檔 | 原文出處