TypeScript

Next.js 提供以 TypeScript 為優先的開發體驗，用於構建您的 React 應用程式。

它內建了 TypeScript 支援，可自動安裝必要的套件並配置正確的設定。

以及適用於您編輯器的 TypeScript 插件。

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

新專案

create-next-app 現在預設包含 TypeScript。

終端機

npx create-next-app@latest

現有專案

透過將檔案重新命名為 .ts / .tsx 來將 TypeScript 添加到您的專案中。執行 next dev 和 next build 以自動安裝必要的依賴項，並添加帶有推薦配置選項的 tsconfig.json 檔案。

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

TypeScript 插件

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

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

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

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

插件功能

TypeScript 插件可以幫助：

警告是否傳遞了區段配置選項的無效值。
顯示可用的選項和上下文文件。
確保正確使用 use client 指令。
確保客戶端鉤子 (如 useState) 僅在客戶端元件中使用。

須知：未來將添加更多功能。

最低 TypeScript 版本

強烈建議至少使用 TypeScript v4.5.2 以獲得諸如導入名稱的類型修飾符和性能改進等語法功能。

靜態類型連結

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

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

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = 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" />

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

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 檔案，並在您的編輯器中提供有關無效連結的反饋。

端到端類型安全性

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

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

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

我們能夠像您期望的那樣使用普通的 TypeScript 來鍵入回應資料。例如：

app/page.tsx

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 或類型安全的查詢建構器來實現。

非同步伺服器元件 TypeScript 錯誤

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

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

在伺服器和客戶端元件之間傳遞資料

當透過 props 在伺服器和客戶端元件之間傳遞資料時，資料仍會被序列化 (轉換為字串) 以在瀏覽器中使用。然而，它不需要特殊的類型。它的鍵入方式與在元件之間傳遞任何其他 props 相同。

此外，需要序列化的程式碼更少，因為未渲染的資料不會在伺服器和客戶端之間傳遞 (它保留在伺服器上)。這現在僅透過對伺服器元件的支援才成為可能。

路徑別名和 baseUrl

Next.js 自動支援 tsconfig.json 中的 "paths" 和 "baseUrl" 選項。

您可以在模組路徑別名文件上了解更多關於此功能的資訊。

檢查 next.config.js 的類型

next.config.js 檔案必須是一個 JavaScript 檔案，因為它不會被 Babel 或 TypeScript 解析，但是您可以使用 JSDoc 在您的 IDE 中添加一些類型檢查，如下所示：

// @ts-check

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

module.exports = nextConfig

增量類型檢查

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

忽略 TypeScript 錯誤

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

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

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

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

next.config.js

module.exports = {
  typescript: {
    // !! 警告 !!
    // 危險地允許生產構建成功完成，即使
    // 您的專案存在類型錯誤。
    // !! 警告 !!
    ignoreBuildErrors: true,
  },
}

自訂類型宣告

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

tsconfig.json

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

版本變更

版本	變更
`v13.2.0`	靜態類型連結在測試版中可用。
`v12.0.0`	SWC 現在預設用於編譯 TypeScript 和 TSX 以獲得更快的構建。
`v10.2.1`	當在您的 `tsconfig.json` 中啟用時，添加了增量類型檢查支援。

On this page