🎥 觀看影片： 瞭解如何逐步採用 App Router → YouTube (16 分鐘) 。
遷移到 App Router 可能會是您第一次使用 Next.js 建立在其之上的 React 功能，例如伺服器元件、Suspense 等等。當與新的 Next.js 功能（例如特殊檔案 和佈局 ）結合使用時，遷移意味著需要學習新的概念、心智模型和行為變化。
我們建議您將遷移分解成更小的步驟，以降低這些更新的綜合複雜性。app 目錄特意設計成可與 pages 目錄同時運作，以便逐頁逐步遷移。
app 目錄支援巢狀路由 *和* 佈局。深入瞭解 。使用巢狀資料夾來定義路由 ，並使用特殊的 page.js 檔案讓路由區段可公開存取。深入瞭解 。
特殊檔案命名慣例 用於為每個路由區段建立 UI。最常見的特殊檔案是 page.js 和 layout.js。
使用 page.js 定義特定路由的 UI。
使用 layout.js 定義跨多個路由共用的 UI。
特殊檔案可以使用 .js、.jsx 或 .tsx 副檔名。
您可以在 app 目錄中共同放置其他檔案，例如元件、樣式、測試等等。深入瞭解 。
像 getServerSideProps 和 getStaticProps 這樣的資料提取函式已被 app 內的新 API 取代。getStaticPaths 已被generateStaticParams
pages/_app.js 和 pages/_document.js 已被單個 app/layout.js 根佈局取代。深入瞭解 。pages/_error.js 已被更精細的 error.js 特殊檔案取代。深入瞭解 。pages/404.js 已被not-found.jspages/api/* API 路由已被route.js
更新至最新版 Next.js（需要 13.4 或更高版本）
然後，在專案的根目錄（或 src/ 目錄）中建立一個新的 app 目錄。
在 app 目錄內建立一個新的 app/layout.tsx 檔案。這是一個根佈局 ，它將套用於 app 內的所有路由。
export default function RootLayout ({ // Layouts must accept a children prop. // This will be populated with nested layouts or pages children , } : { children : React . ReactNode }) { return ( < html lang = "en" > < body >{children}</ body > </ html > ) }
app 目錄**必須**包含一個根佈局。根佈局必須定義 <html> 和 <body> 標籤，因為 Next.js 不會自動建立它們。
根佈局會取代 pages/_app.tsx 和 pages/_document.tsx 檔案。
佈局檔案可以使用 .js、.jsx 或 .tsx 副檔名。
要管理 <head> HTML 元素，您可以使用內建的 SEO 支援 。
import type { Metadata } from 'next'
export const metadata : Metadata = { title : 'Home' , description : 'Welcome to Next.js' , } 如果您現有的專案中有 _app 或 _document 檔案，您可以將其內容（例如：全域樣式）複製到根佈局 (app/layout.tsx)。app/layout.tsx 中的樣式**不會**套用至 pages/*。您應該在遷移過程中保留 _app/_document，以防止 pages/* 路由失效。完成遷移後，您可以安全地刪除它們。
如果您正在使用任何 React Context providers，則需要將它們移至客戶端元件 。
將 getLayout() 模式遷移到佈局（選用） 將屬性添加到頁面元件 以實現每頁佈局。此模式可以替換為 app 目錄中巢狀佈局 的原生支援。
查看前後範例 遷移前
export default function DashboardLayout ({ children }) { return ( < div > < h2 >My Dashboard</ h2 > {children} </ div > ) } import DashboardLayout from '../components/DashboardLayout'
export default function Page () { return < p >My Page</ p > }
Page . getLayout = function getLayout (page) { return < DashboardLayout >{page}</ DashboardLayout > } 遷移後
從 pages/dashboard/index.js 中移除 Page.getLayout 屬性，並按照遷移頁面的步驟 將其移至 app 目錄。
export default function Page () { return < p >My Page</ p > }
將 DashboardLayout 的內容移至新的客戶端元件 以保留 pages 目錄的行為。
'use client' // this directive should be at top of the file, before any imports.
// This is a Client Component export default function DashboardLayout ({ children }) { return ( < div > < h2 >My Dashboard</ h2 > {children} </ div > ) }
將 DashboardLayout 導入 app 目錄內新的 layout.js 檔案。
import DashboardLayout from './DashboardLayout'
// This is a Server Component export default function Layout ({ children }) { return < DashboardLayout >{children}</ DashboardLayout > }
您可以將 DashboardLayout.js（客戶端元件）的非互動部分逐步移至 layout.js（伺服器元件），以減少傳送到客戶端的元件 JavaScript 數量。
在 pages 目錄中，React 元件 next/head 用於管理 <head> HTML 元素，例如 title 和 meta。在 app 目錄中，next/head 已被新的內建 SEO 支援 取代。
遷移前
import Head from 'next/head'
export default function Page () { return ( <> < Head > < title >My page title</ title > </ Head > </> ) } 遷移後
import type { Metadata } from 'next'
export const metadata : Metadata = { title : 'My Page Title' , }
export default function Page () { return '...' } 查看所有中繼資料選項 .
app 目錄伺服器元件 。這與 pages 目錄不同，在 pages 目錄中，頁面是客戶端元件 。app 中的資料擷取 已變更。getServerSideProps、getStaticProps 和 getInitialProps 已被更簡單的 API 取代。app 目錄使用巢狀資料夾來定義路由 ，並使用特殊的 page.js 檔案讓路由區段公開存取。
pages 目錄app 目錄路由 index.jspage.js/about.jsabout/page.js/aboutblog/[slug].jsblog/[slug]/page.js/blog/post-1
我們建議將頁面遷移分成兩個主要步驟
步驟 1：將預設匯出的頁面元件移至新的客戶端元件。
步驟 2：將新的客戶端元件匯入 app 目錄內新的 page.js 檔案。
注意事項 ：這是最簡單的遷移路徑，因為它的行為與 pages 目錄最為相似。
步驟 1：建立新的客戶端元件
在 app 目錄內建立一個新的獨立檔案（例如 app/home-page.tsx 或類似檔案），匯出一個客戶端元件。要定義客戶端元件，請在檔案頂端（任何匯入之前）新增 'use client' 指令。
與 Pages Router 類似，有一個最佳化步驟 可在初始頁面載入時將客戶端元件預渲染為靜態 HTML。
將預設匯出的頁面元件從 pages/index.js 移至 app/home-page.tsx。
'use client'
// This is a Client Component (same as components in the `pages` directory) // It receives data as props, has access to state and effects, and is // prerendered on the server during the initial page load. export default function HomePage ({ recentPosts }) { return ( < div > { recentPosts .map ((post) => ( < div key = { post .id}>{ post .title}</ div > ))} </ div > ) } 步驟 2：建立新的頁面
在 app 目錄內建立一個新的 app/page.tsx 檔案。這預設為伺服器元件。
將 home-page.tsx 客戶端元件匯入頁面。
如果您先前在 pages/index.js 中擷取資料，請使用新的資料擷取 API 將資料擷取邏輯直接移至伺服器元件。詳情請參閱資料擷取升級指南 。
// Import your Client Component import HomePage from './home-page'
async function getPosts () { const res = await fetch ( 'https://...' ) const posts = await res .json () return posts }
export default async function Page () { // Fetch data directly in a Server Component const recentPosts = await getPosts () // Forward fetched data to your Client Component return < HomePage recentPosts = {recentPosts} /> }
如果您先前的頁面使用了 useRouter，則需要更新到新的路由 hook。了解更多 。
啟動您的開發伺服器並瀏覽 https://127.0.0.1:3000
已新增新的路由器以支援 app 目錄中的新行為。
在 app 中，您應該使用從 next/navigation 導入的三個新的 Hook：useRouter()usePathname()useSearchParams()
新的 useRouter Hook 是從 next/navigation 導入的，其行為與從 next/router 導入的 pages 中的 useRouter Hook 不同。
新的 useRouter 不會返回 pathname 字串。請改用單獨的 usePathname Hook。
新的 useRouter 不會返回 query 物件。搜尋參數和動態路由參數現在是分開的。請改用 useSearchParams 和 useParams Hook。
您可以同時使用 useSearchParams 和 usePathname 來監聽頁面變化。詳情請參閱路由器事件 章節。
這些新的 Hook 僅在客戶端元件中受支援。它們不能在伺服器元件中使用。
'use client'
import { useRouter , usePathname , useSearchParams } from 'next/navigation'
export default function ExampleClientComponent () { const router = useRouter () const pathname = usePathname () const searchParams = useSearchParams ()
// ... } 此外，新的 useRouter Hook 還有以下變更：
isFallback 已移除，因為 fallback 已被取代 。locale、locales、defaultLocales、domainLocales 值已被移除，因為內建的 Next.js i18n 功能在 app 目錄中不再需要。深入瞭解 i18n 。basePath 已移除。替代方案不會成為 useRouter 的一部分。它尚未實作。asPath 已移除，因為 as 的概念已從新的路由器中移除。isReady 已移除，因為它不再需要。在靜態渲染 期間，任何使用 useSearchParams()route 已移除。usePathname 或 useSelectedLayoutSegments() 提供了替代方案。
查看 useRouter() API 參考 .
pages 目錄使用 getServerSideProps 和 getStaticProps 來擷取頁面的資料。在 app 目錄中，這些先前的資料擷取函數已被基於 fetch() 和 async React 伺服器組件構建的更簡單的 API 取代。
export default async function Page () { // This request should be cached until manually invalidated. // Similar to `getStaticProps`. // `force-cache` is the default and can be omitted. const staticData = await fetch ( `https://...` , { cache : 'force-cache' })
// This request should be refetched on every request. // Similar to `getServerSideProps`. const dynamicData = await fetch ( `https://...` , { cache : 'no-store' })
// This request should be cached with a lifetime of 10 seconds. // Similar to `getStaticProps` with the `revalidate` option. const revalidatedData = await fetch ( `https://...` , { next : { revalidate : 10 } , })
return < div >...</ div > } 在 pages 目錄中，getServerSideProps 用於在伺服器上擷取資料並將 props 轉送到檔案中預設匯出的 React 組件。頁面的初始 HTML 會從伺服器進行預渲染，然後在瀏覽器中「水合」（使其具有互動性）。
// `pages` directory
export async function getServerSideProps () { const res = await fetch ( `https://...` ) const projects = await res .json ()
return { props : { projects } } }
export default function Dashboard ({ projects }) { return ( < ul > { projects .map ((project) => ( < li key = { project .id}>{ project .name}</ li > ))} </ ul > ) } 在 App Router 中，我們可以使用伺服器組件 在 React 組件內部共同定位資料擷取。這允許我們向客戶端發送更少的 JavaScript，同時維護從伺服器渲染的 HTML。
透過將 cache 選項設定為 no-store，我們可以指示擷取的資料永遠不要被快取 。這類似於 pages 目錄中的 getServerSideProps。
// `app` directory
// This function can be named anything async function getProjects () { const res = await fetch ( `https://...` , { cache : 'no-store' }) const projects = await res .json ()
return projects }
export default async function Dashboard () { const projects = await getProjects ()
return ( < ul > { projects .map ((project) => ( < li key = { project .id}>{ project .name}</ li > ))} </ ul > ) }