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 插件可以幫助：

當傳遞了 segment 配置選項的無效值時發出警告。
顯示可用選項和上下文文檔。
確保正確使用 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 13 具有 增強的類型安全性。這包括：

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

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 錯誤

要使用帶有 TypeScript 的 async 伺服器元件，請確保您使用的是 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,
  },
}

版本變更

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

On this page