Loading

Next.js路由段配置選項筆記

前言

大家好，我是曦遠。

本來是想發昨晚寫好的 starblog 管理后臺重構文章的

結果打開 blog 才發現忘記提交了??

所以寫一篇新的吧

正好最近正在大量使用 Next.js

我發現部署后的首次渲染很慢，才意識到「預熱」這個問題

當然這是后話了

這個框架里有大量的官方約定

這些在官方文檔里都有的，就是比較分散，本文主要是概括一下這些約定

Next.js框架更新得很快，不一樣的地方以官方文檔為主。

緩存和渲染相關

// 控制頁面重新驗證的時間間隔（秒）
export const revalidate = 60; // 60秒后重新驗證
export const revalidate = 0;  // 禁用緩存
export const revalidate = false; // 永久緩存

// 控制頁面的渲染模式
export const dynamic = 'auto';          // 默認，自動選擇
export const dynamic = 'force-dynamic'; // 強制動態渲染
export const dynamic = 'force-static';  // 強制靜態渲染
export const dynamic = 'error';         // 如果使用動態函數則報錯

// 控制動態段的行為
export const dynamicParams = true;  // 允許動態參數（默認）
export const dynamicParams = false; // 不允許動態參數

運行時配置

// 指定運行時環境
export const runtime = 'nodejs';    // Node.js 運行時（默認）
export const runtime = 'edge';      // Edge 運行時

// 設置最大執行時間（秒）
export const maxDuration = 30; // 最多執行30秒

獲取數據相關

// 控制 fetch 請求的緩存行為
export const fetchCache = 'auto';           // 默認緩存行為
export const fetchCache = 'default-cache';  // 默認緩存
export const fetchCache = 'only-cache';     // 只使用緩存
export const fetchCache = 'force-cache';    // 強制緩存
export const fetchCache = 'default-no-store'; // 默認不緩存
export const fetchCache = 'only-no-store';  // 只允許不緩存
export const fetchCache = 'force-no-store'; // 強制不緩存

元數據和SEO

元數據

動態生成元數據

import type { Metadata } from 'next'

export async function generateMetadata({ params }: { params: { slug: string } }): Promise<Metadata> {
  // 根據動態參數獲取數據
  const post = await getPost(params.slug)
  
  return {
    title: post.title,
    description: post.description,
    openGraph: {
      title: post.title,
      description: post.description,
      images: [post.image],
    },
  }
}

定義靜態元數據

// 靜態元數據
export const metadata: Metadata = {
  title: 'My Page',
  description: 'This is my page description',
  keywords: ['next.js', 'react', 'typescript'],
  openGraph: {
    title: 'My Page',
    description: 'This is my page description',
  },
}

使用場景

靜態 Metadata 適用于：

內容固定的頁面（如關于我們、聯系我們）
不需要根據路由參數變化的頁面
簡單的靜態頁面

動態 Metadata 適用于：

博客文章詳情頁（根據文章 slug 獲取標題、描述）
產品詳情頁（根據產品 ID 獲取信息）
用戶個人資料頁（根據用戶 ID 獲取信息）
任何需要根據路由參數或外部數據動態生成 metadata 的頁面

靜態參數

// 生成靜態參數（用于動態路由）
export async function generateStaticParams() {
  return [
    { slug: 'post-1' },
    { slug: 'post-2' },
  ];
}

常用組合示例

完全靜態頁面

export const dynamic = 'force-static';
export const revalidate = false;

實時動態頁面

export const dynamic = 'force-dynamic';
export const revalidate = 0;

定時更新頁面

export const revalidate = 3600; // 每小時更新一次

Edge 運行時優化

export const runtime = 'edge';
export const dynamic = 'force-dynamic';

API 路由配置

// 在 API 路由中也可以使用
export const runtime = 'edge';
export const maxDuration = 10;

使用場景建議

配置	適用場景
revalidate = 0	實時數據展示，如股票價格、聊天應用
revalidate = 60	定期更新的內容，如新聞、博客
dynamic = 'force-static'	完全靜態的頁面，如關于我們
dynamic = 'force-dynamic'	個性化內容，如用戶儀表板
runtime = 'edge'	需要低延遲的全球分發
fetchCache = 'force-no-store'	敏感數據，不允許緩存

注意事項

只能在頁面或布局文件中使用：這些配置只在 page.tsx 、 layout.tsx 或 route.ts 文件中有效
這些配置選項只能在 Server Component Pages、Layouts 或 Route Handlers 中使用
必須是具名導出：必須使用 export const 語法
配置值必須是靜態可分析的（例如 revalidate = 600 有效，但 revalidate = 60 * 10 無效）
類型安全：TypeScript 會檢查這些配置的類型
優先級：子路由的配置會覆蓋父路由的配置

這些配置選項讓 Next.js 能夠精確控制每個頁面的渲染和緩存行為，是 App Router 架構的核心特性之一

官方文檔

Route Segment Config（路由段配置）

最新版本： https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config
Next.js 14 版本： https://nextjs.org/docs/14/app/api-reference/file-conventions/route-segment-config