WordPress get_post 與 get_posts 函數深度解析：單篇與多篇文章獲取的核心差異與最佳實踐

在 WordPress 開發中，get_post() 與 get_posts() 雖名稱相似，但用途、參數、回傳結構截然不同。前者獲取單篇文章物件/陣列，後者獲取多篇文章陣列並支援豐富查詢參數。本文將詳細對比兩者，並提供實戰範例與效能建議。

一、get_post() - 獲取單篇文章

函數語法

get_post( int|WP_Post|null $post = null, string $output = OBJECT, string $filter = 'raw' ): WP_Post|array|null

參數說明

常見用法

// 正確：先指派變數
$post_id = 158;
$post_obj = get_post( $post_id ); // 回傳 WP_Post 物件
$title = $post_obj->post_title;

// 獲取關聯陣列
$post_arr = get_post( $post_id, ARRAY_A );
$content = $post_arr['post_content'];

// 獲取數值陣列（較少用）
$post_num = get_post( $post_id, ARRAY_N );
// $post_num[0] = ID, $post_num[1] = post_author, ... 依資料表欄位順序

適用場景

• 已知文章 ID，需在非主循環中獲取標題、內容、自訂欄位等
• 撰寫短代碼、Widget、REST API 端點時獲取特定文章
• 配合 setup_postdata() 暫時切換全域 $post 變數

二、get_posts() - 獲取多篇文章列表

函數語法

get_posts( array|string $args = array() ): WP_Post[]

完整參數對照表

參數結構與 WP_Query 高度相容，以下為常用參數：

orderby 可用值

'author'       // 作者 ID
'category'     // 分類 ID
'comment_count'// 留言數
'date'         // 發布日期
'ID'           // 文章 ID
'menu_order'   // 選單順序（頁面適用）
'modified'     // 最後修改時間
'name'         // 文章別名
'parent'       // 父文章 ID
'rand'         // 隨機排序
'title'        // 標題
'type'         // 文章類型

常見用法範例

1. 獲取最新 5 篇已發布文章

$latest_posts = get_posts( [
    'numberposts' => 5,
    'post_status' => 'publish',
    'orderby'     => 'date',
    'order'       => 'DESC',
] );

2. 隨機獲取 3 篇文章（側邊欄推薦）

// 字串參數簡寫
$random_posts = get_posts( 'numberposts=3&orderby=rand' );

// 陣列參數完整寫法
$random_posts = get_posts( [
    'numberposts' => 3,
    'orderby'     => 'rand',
    'post_status' => 'publish',
] );

3. 獲取特定分類下的文章

$cat_posts = get_posts( [
    'numberposts' => 10,
    'category'    => 5, // 分類 ID
    // 或 'category_name' => 'news'
] );

4. 依自訂欄位篩選

$featured_posts = get_posts( [
    'meta_key'   => 'is_featured',
    'meta_value' => 'yes',
    'post_type'  => 'post',
] );

5. 獲取附件（圖片）

$images = get_posts( [
    'post_type'      => 'attachment',
    'post_mime_type' => 'image',
    'post_parent'    => $post_id, // 該文章的附件
    'numberposts'    => -1,
    'orderby'        => 'menu_order',
    'order'          => 'ASC',
] );

三、核心差異對比表

四、進階技巧與最佳實踐

1. 配合 setup_postdata() 使用模板標籤

$my_posts = get_posts( ['numberposts' => 3] );
if ( $my_posts ) {
    global $post;
    foreach ( $my_posts as $post ) {
        setup_postdata( $post );
        // 現在可以使用 the_title(), the_permalink(), the_excerpt() 等模板標籤
        echo '<h3><a href="' . get_permalink() . '">' . get_the_title() . '</a></h3>';
        the_excerpt();
    }
    wp_reset_postdata(); // 重要：恢復全域 $post
}

2. 效能優化：避免 N+1 查詢

// ❌ 慢：迴圈中重複查詢自訂欄位
foreach ( $posts as $post ) {
    $meta = get_post_meta( $post->ID, 'key', true );
}

// ✅ 快：使用 meta_query 一次撈取
$posts = get_posts( [
    'meta_key' => 'key',
    // 或 meta_query 更複雜條件
] );

3. 分頁處理

$paged = ( get_query_var( 'paged' ) ) ? get_query_var( 'paged' ) : 1;
$posts = get_posts( [
    'numberposts' => 10,
    'offset'      => ( $paged - 1 ) * 10,
] );

4. 替代方案：WP_Query 物件

當需要更複雜查詢（多重分類、關係查詢、日期範圍、分頁物件）時，建議直接使用 WP_Query：

$query = new WP_Query( [
    'post_type'      => 'product',
    'tax_query'      => [
        'relation' => 'AND',
        ['taxonomy' => 'category', 'field' => 'slug', 'terms' => 'sale'],
        ['taxonomy' => 'pa_color', 'field' => 'slug', 'terms' => ['red', 'blue']],
    ],
    'meta_query'     => [
        ['key' => 'price', 'value' => [100, 500], 'type' => 'NUMERIC', 'compare' => 'BETWEEN'],
    ],
    'posts_per_page' => 12,
    'paged'          => $paged,
] );

五、常見錯誤與除錯

直接傳入字面量 ID：get_post(123)

會觸發 PHP Warning：「Parameter 1 to get_post() expected to be a reference」。解法：$id = 123; get_post($id);

get_posts 回傳空陣列

檢查 post_status 是否正確（預設只抓 'publish'），或 suppress_filters 是否被外掛影響。

隨機排序效能問題

ORDER BY RAND() 在大資料量極慢。替代方案：預先產生隨機 ID 陣列、使用 offset 隨機跳過、或外掛 WP_Random_Posts。

分類參數不生效

確認使用 category (ID) 或 category_name (slug)，不要混用。多個分類用陣列 [1, 2, 3]。

六、原始碼位置

• get_post()：wp-includes/post.php（約第 900 行）
• get_posts()：wp-includes/post.php（約第 2100 行），內部實際呼叫 WP_Query