TypeScript

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

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

新项目

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 文件。

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

最低 TypeScript 版本

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

在 Next.js 配置中进行类型检查

类型检查 next.config.js

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

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

类型检查 next.config.ts

您可以使用 TypeScript 并通过使用 next.config.ts 在 Next.js 配置中导入类型。

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  /* config options here */
}
 
export default nextConfig

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

静态生成和服务器端渲染

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

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 选项。

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 错误，然后再进行构建。这在 CI/CD 管道中很有用，您可以在部署前检查 TypeScript 错误。

自定义类型声明

当您需要声明自定义类型时，您可能会尝试修改 next-env.d.ts。但是，此文件是自动生成的，因此您所做的任何更改都将被覆盖。相反，您应该创建一个新文件，例如 new-types.d.ts，并在您的 tsconfig.json 中引用它。

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

版本变更