TypeScript

版本歷史
版本更動
v12.0.0SWC is now used by default to compile TypeScript and TSX for faster builds. 是預設作為為了快速建立而用來編譯 TypeScript 和 TSX 的工具
v10.2.1增量 type 檢查 支援將會被加入當 tsconfig.json 被啟用

Next.js 提供包含無額外設定以及為了頁面、API 及更多的內建 types 的 TypeScript 整合體驗。

支援 create-next-app

你可以使用 create-next-app 以及指令 --ts, --typescript 建立一個 TypeScript 專案,如下面所示:

npx create-next-app@latest --ts
# or
yarn create next-app --typescript
# or
pnpm create next-app --ts

既有的專案

既有的專案,請在根目錄資料夾內建立一個 tsconfig.json 檔案:

touch tsconfig.json

Next.js 除了會自動地以預設值來設定檔案;也可以支援帶有自定義的編譯器選項tsconfig.json 檔。

你可以在 next.config.js 檔案內透過設定 typescript.tsconfigPath 屬性,來提供 tsconfig.json 檔一個相對的路徑位置。

版本 v12.0.0,Next.js 為達到快速建置,預設使用 SWC 來編譯 TypeScript 和 TSX。

如果有 .babelrc 檔, Next.js 將會使用 Babel 來處理 TypeScript。但這將會有一些限制和一些編譯器選項處理方式的不同

接著,執行 next (一般來說是 npm run devyarn dev), Next.js 會引導你安裝所需的相關模組直到設定完畢:

npm run dev # 你將會看到相關指引如下: # # Please install TypeScript, @types/react, and @types/node by running: # # yarn add --dev typescript @types/react @types/node # # ...

現在你已經準備好將 .js 檔轉換為 .tsx 並且可以利用 TypeScript 提供的優勢了。

在根目錄下將會有一個名為 next-env.d.ts 的檔案會被建立。這個檔案確保 Next.js types 有被 TypeScript 編譯器接管。它有可能在任何時候被改變,因此千萬不要移除或編輯它,這個檔案不應該被 commit 且需要被版本控制忽略(例如:在你的 gitignore 檔案)。

TypeScript 嚴格模式 預設狀況下是關閉的。當你習慣 TypeScript,我們建議在 tsconfig.json 將它開啟。

與其編輯 next-env.d.ts, 你可以透過建立一個如 additional.d.ts 的檔案來新增額外的 types,並藉由 include 陣列中引用。

預設下,Next.js 會視 type 檢查為 next build 的一個部分。我們建議在開發階段中使用程式碼編輯器做 type 檢查。

如果你不想顯示任何錯誤訊息,可以查看忽略 TypeScript 錯誤訊息 文件。

靜態生成和伺服器端渲染

如果是 getStaticPropsgetStaticPathsgetServerSideProps,你可以分別使用 GetStaticPropsGetStaticPathsGetServerSideProps types :

import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next' export const getStaticProps: GetStaticProps = async (context) => { // ... } export const getStaticPaths: GetStaticPaths = async () => { // ... } export const getServerSideProps: GetServerSideProps = async (context) => { // ... }

如果你是使用 getInitialProps,你可以 跟著這篇指引來看看怎麼做。

API 路由

以下是如何使用 API 路由的內建 type 的例子:

import type { NextApiRequest, NextApiResponse } from 'next' export default (req: NextApiRequest, res: NextApiResponse) => { res.status(200).json({ name: 'John Doe' }) }

你也可以輸入 response 的資料:

import type { NextApiRequest, NextApiResponse } from 'next' type Data = { name: string } export default (req: NextApiRequest, res: NextApiResponse<Data>) => { res.status(200).json({ name: 'John Doe' }) }

自定義 App

如果你有一個 自定義 App,你可以使用內建的 type Appprops 並且更換檔案名稱 ./pages/_app.tsx,例如:

import type { AppProps } from 'next/app' export default function MyApp({ Component, pageProps }: AppProps) { return <Component {...pageProps} /> }

Path aliases 和 baseUrl

Next.js 自動支援 tsconfig.json "paths""baseUrl" 的多種選擇。

你可以點擊 Module Path aliases 文件 來學習更多。

Type 檢查 next.config.js

Next.config.js 若不是 Javascript 檔案的話,將無法被 Babel 或 TypeScript 解析,但你可以使用 JSDoc,加入一些 type 檢查你的 IDE,參考如下:

// @ts-check /** * @type {import('next').NextConfig} **/ const nextConfig = { /* config options here */ } module.exports = nextConfig

增量 type 檢查

自從 v10.2.1 Next.js 支援 增量 type 檢查 當你啟用 tsconfig.json,這可以幫助你針對大型應用程式加速作 type 檢查。

使用此功能的話,強烈建議至少要版本 v4.3.2 的 TypeScript 來體驗最佳效能

忽略 TypeScript 錯誤

當 TypeScript 錯誤訊息存在於你的專案中時,Next.js 會在 生產環境建置 (next build) 階段顯示失敗。

如果你仍舊希望 Next.js 在即使有錯誤訊息的狀況下仍然要執行生產環境的建置,你可以取消內建的 type 檢查階段;如果取消,請確保 type 檢查是建置或部署流程的其中一部分。

打開 next.config.js 和啟用在 typescript 設定內的 ignoreBuildErrors 選項:

module.exports = { typescript: { // !! 警告 !! // 即使存在著 type 錯誤,仍舊執行生產環境的建置是非常危險的。 // !! 警告 !! ignoreBuildErrors: true, }, }
本篇文章由AndreaFan123

AndreaFan123

貢獻翻譯。瞭解如何參與貢獻