TypeScript

Next.js 为构建 React 应用提供了以 TypeScript 为先的开发体验。

它内置了 TypeScript 支持，可以自动安装必要的包并配置适当的设置。

新项目

create-next-app 现在默认采用 TypeScript。

Terminal

npx create-next-app@latest

现有项目

将文件重命名为 .ts / .tsx 来为你的项目添加 TypeScript。运行 next dev 和 next build 会自动安装必要的依赖并添加一个带有推荐配置选项的 tsconfig.json 文件。

如果你之前有一个 jsconfig.json 文件，请将旧的 jsconfig.json 中的 paths 编译器选项复制到新的 tsconfig.json 文件中，然后删除旧的 jsconfig.json 文件。

我们还建议你使用 next.config.ts 而不是 next.config.js，以获得更好的类型推断。

最低 TypeScript 版本

强烈建议使用至少 v4.5.2 版本的 TypeScript，以获得诸如导入名称的类型修饰符和性能改进等语法功能。

Next.js 配置中的类型检查

对 next.config.js 进行类型检查

当使用 next.config.js 文件时，你可以使用 JSDoc 在 IDE 中添加一些类型检查，如下所示：

next.config.js

// @ts-check
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 在此处添加配置选项 */
};
 
module.exports = nextConfig;

对 next.config.ts 进行类型检查

你可以使用 TypeScript 并在 Next.js 配置中导入类型，方法是使用 next.config.ts。

next.config.ts

import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  /* 在此处添加配置选项 */
};
 
export default nextConfig;

注意：next.config.ts 中的模块解析目前仅限于 CommonJS。这可能会导致在 next.config.ts 中加载仅支持 ESM 的包时出现不兼容问题。

静态生成和服务器端渲染

对于 getStaticProps、getStaticPaths 和 getServerSideProps，你可以分别使用 GetStaticProps、GetStaticPaths 和 GetServerSideProps 类型：

pages/blog/[slug].tsx

import type { GetStaticProps, GetStaticPaths, GetServerSideProps } from "next";
 
export const getStaticProps = (async (context) => {
  // ...
}) satisfies GetStaticProps;
 
export const getStaticPaths = (async () => {
  // ...
}) satisfies GetStaticPaths;
 
export const getServerSideProps = (async (context) => {
  // ...
}) satisfies GetServerSideProps;

小贴士：satisfies 是在 TypeScript 4.9 中添加的。我们建议升级到最新版本的 TypeScript。

API 路由

以下是如何在 API 路由中使用内置类型的示例：

import type { NextApiRequest, NextApiResponse } from "next";
 
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ name: "John Doe" });
}

你还可以为响应数据添加类型：

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

自定义 `App`

如果你有一个自定义 App，你可以使用内置类型 AppProps 并将文件名更改为 ./pages/_app.tsx，如下所示：

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

路径别名和 baseUrl

Next.js 自动支持 tsconfig.json 中的 "paths" 和 "baseUrl" 选项。

你可以在模块路径别名文档中了解更多关于此功能的信息。

增量类型检查

从 v10.2.1 开始，Next.js 支持增量类型检查，当在你的 tsconfig.json 中启用时，这可以帮助加速大型应用程序的类型检查。

忽略 TypeScript 错误

当你的项目中存在 TypeScript 错误时，Next.js 会使你的生产构建 (next build) 失败。

如果你希望 Next.js 在你的应用程序有错误时仍然危险地生成生产代码，你可以禁用内置的类型检查步骤。

如果禁用，请确保你在构建或部署过程中运行类型检查，否则这可能会非常危险。

打开next.config.ts 并在 typescript 配置中启用 ignoreBuildErrors 选项：

next.config.ts

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  typescript: {
    // !! WARN !!
    // Dangerously allow production builds to successfully complete even if
    // your project has type errors.
    // !! WARN !!
    ignoreBuildErrors: true,
  },
}
 
export default nextConfig

值得注意的是：你可以运行 tsc --noEmit 来在构建之前自行检查 TypeScript 错误。这对于想要在部署前检查 TypeScript 错误的 CI/CD 流程来说很有用。

自定义类型声明

当你需要声明自定义类型时，你可能会想要修改 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"]
}

版本变更

版本	变更
`v15.0.0`	为 TypeScript 项目添加了 `next.config.ts` 支持。
`v13.2.0`	静态类型链接在 beta 版中可用。
`v12.0.0`	现在默认使用 SWC 来编译 TypeScript 和 TSX，以实现更快的构建。
`v10.2.1`	当在你的 `tsconfig.json` 中启用时，添加了对增量类型检查的支持。