在現代 React 全端框架的演進中,開發團隊在升級或建置專案時,經常面臨 Next.js App Router 與 Pages Router 差異 的架構抉擇。舊版的 Pages Router 採用直覺的檔案基底路由與頁面級資料獲取函式,但在巢狀佈局與元件級效能控制上存在侷限;而新一代的 App Router 則以 React Server Components (RSC) 為核心,透過全新的檔案慣例與資料流設計,徹底改變了全端應用的渲染與傳輸模式。
想了解基礎細節可前往 Next.js PPR 教學:結合 SSG 快取速度與 SSR 即時資料的混合渲染解析 觀看,本文將直接聚焦於這兩種路由架構在檔案配置、渲染邊界與遷移實務上的核心差異。
一、 核心速查與常見瓶頸對照
在實際重構或評估專案架構時,開發者常因混淆兩代 Router 的路由宣告與資料獲取邏輯而遭遇瓶頸。以下先整理兩者的核心機制對照,並提供快速判斷與遷移時的檢視基準。
1. 常見錯誤寫法的工程瓶頸
- 混淆渲染環境:在 App Router 的預設 Server Components 中直接使用
useState或useEffect,next build會直接中止並提示該 API 只能在 Client Components 使用。 - 錯誤的資料獲取方式:在 App Router 檔案中繼續尋找
getServerSideProps或getStaticProps,忽略新版直接使用async/await進行 Fetch 的架構。 - 沿用
_app.js與_document.js:在app/目錄裡找不到這兩個檔案的對應寫法,App Router 改由單一根 layout(app/layout.js)取代兩者。
2. 核心機制規格對照表
| 比較維度 | Pages Router (舊版) | App Router (新版) |
|---|---|---|
| 預設元件類型 | 頁面為 Client Components(伺服器先產生 HTML,再於瀏覽器 Hydration) | layout 與 page 預設為 React Server Components |
| 檔案基底路由 | pages/ 目錄下的檔名即為 URL 路徑 | app/ 目錄下的資料夾結構搭配固定保留檔名 (page.js) |
| 巢狀佈局支援 | 在 _app.js 包單一 Layout,或用各頁的 getLayout 自行組合 | 每層資料夾的 layout.js 自動巢狀,導覽時保留狀態、不重新渲染 |
| 資料獲取方式 | getServerSideProps / getStaticProps | 於 Server Components 中直接使用 async/await |
二、 關鍵機制解析:底層規範與注意事項
深入兩代的底層架構,最顯著的變革在於渲染邊界(Rendering Boundaries)的轉移。
1. 檔案系統與路由宣告的演進
在 Pages Router 中,路由完全對應實體檔案結構(例如 pages/blog/[id].js 對應 /blog/123)。這種模式簡單直覺,但佈局不跟著資料夾走:全站共用的 Layout 要寫在 _app.js,不同頁面要不同佈局時,得在各頁定義 getLayout 再由 _app.js 呼叫組合。
相較之下,App Router 引入了更嚴謹的 App Router 檔案慣例,以資料夾定義路由區段,並透過 layout.js、page.js、loading.js 與 error.js 等保留檔名,讓每個區段的 UI 都能獨立控制載入狀態與錯誤邊界。
2. React Server Components 與 Client Components 渲染邊界
在 App Router 中,layout 與 page 等元件預設皆為 React Server Components。這意味著程式碼在伺服器端執行,可以直接存取資料來源,並減少送到瀏覽器的 JavaScript(Bundle Size)。
然而,當元件需要互動性(如綁定 onClick 事件、使用 Hook 或是操作 DOM)時,必須在檔案最上方明確宣告 'use client' 指令,這正是 Client Components 渲染邊界 的切分點。
- 注意事項:一旦在檔案頂部宣告
'use client',這個檔案 import 的模組與它直接渲染的元件都會進入用戶端 Bundle;以children等 Props 傳入的 Server Components 則不受影響,仍在伺服器端渲染。因此應盡可能將'use client'的宣告下放到葉子元件(Leaf Components),以維持伺服器端渲染的優勢。
三、 實作範本:生產環境完整程式碼
以下提供兩個生產環境中常見的架構範本,分別展示 App Router 的標準頁面配置與客戶端元件邊界處理。
範本一:App Router 巢狀佈局與伺服器端資料獲取 (app/blog/[id]/page.js)
// 預設為 React Server Components,可直接執行非同步資料獲取
import { notFound } from 'next/navigation';
async function getPostData(id) {
const res = await fetch(`https://api.example.com/posts/${id}`, {
next: { revalidate: 3600 }
});
if (!res.ok) return null;
return res.json();
}
export default async function BlogPostPage({ params }) {
const { id } = await params;
const post = await getPostData(id);
if (!post) {
notFound();
}
return (
<article className="max-w-3xl mx-auto p-6">
<h1 className="text-3xl font-bold mb-4">{post.title}</h1>
<p className="text-gray-600 mb-6">發布於:{post.date}</p>
<div className="prose">{post.content}</div>
</article>
);
}
若在 next.config 開啟 cacheComponents,這個頁面在 <Suspense> 外讀取 params 與 fetch,next build 會中止並顯示 Next.js encountered uncached or runtime data during prerendering;在同一資料夾加上 loading.js(或自行包 <Suspense>)提供 fallback 即可通過建置。
範本二:宣告 Client Component 與事件互動處理 (components/LikeButton.js)
'use client';
import { useState } from 'react';
export default function LikeButton({ initialLikes, postId }) {
const [likes, setLikes] = useState(initialLikes);
const [isLoading, setIsLoading] = useState(false);
const handleLike = async () => {
setIsLoading(true);
try {
const res = await fetch(`/api/posts/${postId}/like`, { method: 'POST' });
if (res.ok) {
setLikes((prev) => prev + 1);
}
} catch (error) {
console.error('點擊按鈕發生錯誤:', error);
} finally {
setIsLoading(false);
}
};
return (
<button
onClick={handleLike}
disabled={isLoading}
className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 disabled:opacity-50"
>
{isLoading ? '處理中...' : `喜歡 (${likes})`}
</button>
);
}

範本一以本機模擬 API 取代 api.example.com,範本二由 Server Component 頁面引入;Next.js 16.4.3 next build/next start、Chrome 156 無頭模式、Windows 11 執行畫面
四、 常見問題與排錯(Q&A)
Q1:Next.js App Router 的 layout.js 與 Pages Router 的 _app.js 在巢狀佈局上有何本質上的差異?
- 問題原因:Pages Router 的
_app.js是全域單一入口,佈局要在 JavaScript 裡自行組合:只有一種佈局時在_app.js包住頁面,多種佈局時在各頁定義getLayout。因為元件樹在換頁時被保留,這種寫法同樣能保留佈局內的狀態(例如輸入框的值),但佈局層級和資料夾結構沒有對應關係。 - 解法:App Router 的
layout.js跟著資料夾自動巢狀。當使用者在同一 Layout 下的不同子頁面(page.js)之間導覽時,共用的layout.js會保留狀態、維持可互動,而且不會重新渲染。
Q2:如何在 Next.js App Router 中正確宣告 Client Component 且不破壞伺服器端渲染邊界?
- 問題原因:開發者常誤將整個頁面宣告為 Client Component,整頁的元件程式碼都會送進用戶端 Bundle,失去 Server Components 減少 JavaScript 的好處。
- 解法:保持頁面本身與資料獲取邏輯為預設的 Server Component,僅將需要互動的元件(如按鈕、表單)獨立抽離為單獨檔案,並在該檔案頂部宣告
'use client',再將其引入 Server Component 中使用。
Q3:App Router 取代 getServerSideProps 與 getStaticProps 後,資料獲取機制應如何重構?
- 問題原因:
app/目錄不再使用getServerSideProps、getStaticProps這類頁面級資料獲取函式,改為在 async Server Components 中搭配fetch()取得資料;getStaticPaths則由generateStaticParams取代。 - 解法:直接在 Server Components 內使用
async/await呼叫fetch。設定cache: 'force-cache'類似原先getStaticProps的靜態快取;設定next: { revalidate: 60 }類似getStaticProps搭配revalidate選項(ISR);設定cache: 'no-store'則類似getServerSideProps每次請求都重新取得資料。
Q4:從 Pages Router 遷移至 App Router 時,如何處理動態路由參數與 catch-all 路由的檔案命名?
- 問題原因:兩代路由系統對動態參數的資料夾與檔案命名規則有所調整。
- 解法:Pages Router 的
[id].js在 App Router 中需改為建立資料夾[id]/page.js;而 catch-all 路由則由[...slug].js轉變為[...slug]/page.js。同時,Next.js 15 起 App Router 的params為 Promise 型別,需透過await params取得參數值。
Q5:Next.js App Router 的 loading.js 與 error.js 如何與 React Suspense 機制整合?
- 問題原因:非同步資料獲取容易造成頁面載入空白或錯誤崩潰。
- 解法:
loading.js會自動把同資料夾的page.js與底下的子項包進 React<Suspense>邊界,並以loading.js的內容當作 fallback;error.js則把該路由區段與巢狀子項包在 React Error Boundary 中,發生錯誤時顯示error.js的元件。開發者只需在對應的路由資料夾下放入這兩個檔案,即可無縫享有非同步等待與錯誤攔截機制。
Q6:在混合架構中,Server Components 傳遞資料給 Client Components 必須遵守哪些序列化規範?
- 問題原因:伺服器端與客戶端之間的資料傳輸必須透過網路傳輸層,複雜物件無法直接傳遞。
- 解法:從 Server Component 透過 Props 傳給 Client Component 的值必須可被 React 序列化,範圍比 JSON 寬:string、number、bigint、boolean、undefined、null、以
Symbol.for註冊的 symbol、內容可序列化的 Array/Map/Set/TypedArray/ArrayBuffer、Date、純物件、Promise、JSX 元素與 Server Functions 都可以傳。一般函式(例如在 Server Component 定義的事件處理器)、class、class 實例與 null prototype 物件則不能直接傳遞。
參考資料與延伸閱讀
- Next.js 官方文件 – Layouts and Pages
- Next.js 官方文件 – Server and Client Components
- Next.js 官方文件 – How to migrate from Pages to the App Router
- Next.js 官方文件(Pages Router)- Pages and Layouts
- Next.js 官方文件 – loading.js
- Next.js 官方文件 – error.js
- Next.js 官方文件 – page.js
- Next.js 官方文件 – Dynamic Route Segments
- React 官方文件 – Server Components
- React 官方文件 – 'use client'
- MDN Web Docs – Fetch API 規範
- Next.js Pages Router 載入順序解析:middleware、_app 與 _document 差異與作用
發佈留言