TypeScript

Next.js 内置 TypeScript，当你使用 create-next-app 创建新项目时，会自动安装必要的包并配置正确的设置。

要将 TypeScript 添加到现有项目，请将文件重命名为 .ts / .tsx。运行 next dev 和 next build 以自动安装必要的依赖项并添加具有推荐配置选项的 tsconfig.json 文件。

提示：如果你已经有 jsconfig.json 文件，请将 paths 编译器选项从旧的 jsconfig.json 复制到新的 tsconfig.json 文件中，并删除旧的 jsconfig.json 文件。

示例

类型检查 `next.config.ts`

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

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* 配置选项在这里 */
}

export default nextConfig

提示：next.config.ts 中的模块解析目前仅限于 CommonJS。这可能会导致与仅在 ESM 包在 next.config.ts 中加载时的不兼容性。

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

next.config.js
// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 配置选项在这里 */
}

module.exports = nextConfig

静态生成和服务端渲染

对于 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 路由使用内置类型的示例：

pages/api/hello.ts
import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ name: 'John Doe' })
}

你还可以类型化响应数据：

pages/api/hello.ts
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} />
}

增量类型检查

自 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: {
    // !! 警告 !!
    // 危险地允许生产构建成功完成，即使 你的项目有类型错误。
    // !! 警告 !!
    ignoreBuildErrors: true,
  },
}

export default nextConfig

提示：你可以运行 tsc --noEmit 在构建前自己检查 TypeScript 错误。这对于 CI/CD 管道很有用，你希望在部署前检查 TypeScript 错误。

自定义类型声明

当你需要声明自定义类型时，你可能会想要修改 next-env.d.ts。但是，此文件是自动生成的，因此你进行的任何更改都会被覆盖。相反，你应该创建一个新文件，让我们称之为 new-types.d.ts，并在 tsconfig.json 中引用它：

tsconfig.json
{
  "compilerOptions": {
    "skipLibCheck": true
    //...truncated...
  },
  "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 | 静态类型化链接在测试版中可用。 | | v12.0.0 | 现在默认使用 SWC 来编译 TypeScript 和 TSX 以获得更快的构建。 | | v10.2.1 | 在 tsconfig.json 中启用时添加了增量类型检查支持。 |

示例

类型检查 next.config.ts