TypeScript

Next.js 內建 TypeScript 支援，當您使用 create-next-app 建立新專案時，會自動安裝必要的套件並配置適當的設定。

若要將 TypeScript 添加到現有專案，請將檔案重新命名為 .ts / .tsx。執行 next dev 和 next build 會自動安裝必要的依賴項，並添加一個包含推薦配置選項的 tsconfig.json 檔案。

小知識：如果您已經有 jsconfig.json 檔案，請將 paths 編譯器選項從舊的 jsconfig.json 複製到新的 tsconfig.json 檔案中，並刪除舊的 jsconfig.json 檔案。

IDE 插件

Next.js 包含一個自訂的 TypeScript 插件和類型檢查器，VSCode 和其他程式碼編輯器可以使用它來進行進階類型檢查和自動完成。

您可以通過以下方式在 VS Code 中啟用插件：

1. 打開命令面板 (Ctrl/⌘ + Shift + P)
2. 搜尋「TypeScript: Select TypeScript Version」
3. 選擇「Use Workspace Version」

現在，在編輯檔案時，自訂插件將被啟用。執行 next build 時，將使用自訂類型檢查器。

TypeScript 插件可以幫助：

• 當傳遞了無效的 路由段配置選項 值時發出警告
• 顯示可用選項和上下文文件
• 確保 'use client' 指令正確使用
• 確保客戶端鉤子（如 useState）僅在客戶端元件中使用

🎥 觀看：了解內建的 TypeScript 插件 → YouTube (3 分鐘)

端到端類型安全

Next.js 應用程式路由器具有 增強類型安全。這包括：

1. 在獲取函數和頁面之間無需序列化數據：您可以直接在伺服器上的元件、佈局和頁面中 fetch。這些數據 不需要 序列化（轉換為字串）即可傳遞到客戶端供 React 使用。相反，由於 app 預設使用伺服器元件，我們可以直接使用 Date、Map、Set 等值，無需任何額外步驟。以前，您需要使用 Next.js 特定的類型手動標記伺服器和客戶端之間的邊界。
2. 元件之間的數據流簡化：隨著 _app 被根佈局取代，現在更容易可視化元件和頁面之間的數據流。以前，個別 pages 和 _app 之間的數據流難以標記類型，並可能引入令人困惑的錯誤。通過應用程式路由器中的 同位置數據獲取，這不再是問題。

Next.js 中的數據獲取 現在提供了盡可能接近端到端類型安全的體驗，而無需對您的數據庫或內容提供者選擇進行規定。

我們能夠像您對普通 TypeScript 的期望那樣標記響應數據的類型。例如：

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // 返回值 *不會* 被序列化
  // 您可以返回 Date、Map、Set 等
  return res.json()
}

export default async function Page() {
  const name = await getData()

  return '...'
}

對於 完整的 端到端類型安全，這還需要您的數據庫或內容提供者支援 TypeScript。這可以通過使用 ORM 或類型安全的查詢建構器來實現。

範例

類型檢查 next.config.ts

您可以在 Next.js 配置中使用 TypeScript 並導入類型，方法是使用 next.config.ts。

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* 配置選項在這裡 */
}

export default nextConfig

小知識：next.config.ts 中的模組解析目前僅限於 CommonJS。這可能導致與僅支援 ESM 的套件在 next.config.ts 中載入時不相容。

當使用 next.config.js 檔案時，您可以使用 JSDoc 在 IDE 中添加一些類型檢查，如下所示：

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 配置選項在這裡 */
}

module.exports = nextConfig

靜態類型連結

Next.js 可以靜態類型化連結，以防止在使用 next/link 時出現拼寫錯誤和其他錯誤，從而提高頁面間導航的類型安全性。

要選擇啟用此功能，需要啟用 experimental.typedRoutes 並且專案需要使用 TypeScript。

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

export default nextConfig

Next.js 將在 .next/types 中生成一個連結定義，其中包含有關應用程式中所有現有路由的資訊，TypeScript 可以使用這些資訊在編輯器中提供有關無效連結的反饋。

目前，實驗性支援包括任何字串字面量，包括動態段。對於非字面量字串，您目前需要手動將 href 轉換為 as Route：

import type { Route } from 'next';
import Link from 'next/link'

// 如果 href 是有效路由，則不會出現 TypeScript 錯誤
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />

// 如果 href 不是有效路由，則會出現 TypeScript 錯誤
<Link href="/aboot" />

要在自訂元件中接受 href 並包裝 next/link，請使用泛型：

import type { Route } from 'next'
import Link from 'next/link'

function Card<T extends string>({ href }: { href: Route<T> | URL }) {
  return (
    <Link href={href}>
      <div>我的卡片</div>
    </Link>
  )
}

它是如何工作的？

當執行 next dev 或 next build 時，Next.js 會在 .next 內部生成一個隱藏的 .d.ts 檔案，其中包含有關應用程式中所有現有路由的資訊（所有有效路由作為 Link 的 href 類型）。此 .d.ts 檔案包含在 tsconfig.json 中，TypeScript 編譯器將檢查該 .d.ts 並在編輯器中提供有關無效連結的反饋。

使用非同步伺服器元件

要將 async 伺服器元件與 TypeScript 一起使用，請確保您使用的是 TypeScript 5.1.3 或更高版本以及 @types/react 18.2.8 或更高版本。

如果您使用的是舊版本的 TypeScript，您可能會看到 'Promise<Element>' is not a valid JSX element 類型錯誤。更新到最新版本的 TypeScript 和 @types/react 應該可以解決此問題。

增量類型檢查

自 v10.2.1 起，Next.js 支援 增量類型檢查，當在您的 tsconfig.json 中啟用時，這可以幫助加速大型應用程式中的類型檢查。

在生產環境中禁用 TypeScript 錯誤

當您的專案中存在 TypeScript 錯誤時，Next.js 會使您的 生產構建 (next build) 失敗。

如果您希望 Next.js 即使在應用程式存在錯誤時也能危險地生成生產程式碼，您可以禁用內建的類型檢查步驟。

如果禁用，請確保在構建或部署過程中運行類型檢查，否則這可能非常危險。

打開 next.config.ts 並在 typescript 配置中啟用 ignoreBuildErrors 選項：

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  typescript: {
    // !! 警告 !!
    // 危險地允許生產構建即使您的專案存在類型錯誤也能成功完成
    // !! 警告 !!
    ignoreBuildErrors: true,
  },
}

export default nextConfig

小知識：您可以執行 tsc --noEmit 來在構建前自行檢查 TypeScript 錯誤。這對於您希望在部署前檢查 TypeScript 錯誤的 CI/CD 流程非常有用。

自訂類型聲明

當您需要聲明自訂類型時，您可能會想要修改 next-env.d.ts。但是，此檔案是自動生成的，因此您所做的任何更改都將被覆蓋。相反，您應該創建一個新檔案，讓我們稱之為 new-types.d.ts，並在您的 tsconfig.json 中引用它：

{
  "compilerOptions": {
    "skipLibCheck": true
    //...省略...
  },
  "include": [
    "new-types.d.ts",
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": ["node_modules"]
}

版本變更