TypeScript

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

它带有内置的 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 文件。

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

TypeScript 插件

Next.js 包含一个自定义 TypeScript 插件和类型检查器，VSCode 和其他代码编辑器可以使用它进行高级类型检查和自动完成。

您可以在 VS Code 中通过以下方式启用插件

1. 打开命令面板 (Ctrl/⌘ + Shift + P)
2. 搜索“TypeScript: 选择 TypeScript 版本”
3. 选择“使用工作区版本”

现在，在编辑文件时，自定义插件将被启用。运行 next build 时，将使用自定义类型检查器。

插件功能

TypeScript 插件可以帮助您

• 如果传递了段配置选项的无效值，则会发出警告。
• 显示可用选项和上下文文档。
• 确保use client 指令使用正确。
• 确保客户端钩子（如useState）仅在客户端组件中使用。

注意：将来会添加更多功能。

最低 TypeScript 版本

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

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 的包时出现不兼容问题。

静态类型链接

Next.js 可以静态地为链接添加类型，以防止在使用 next/link 时出现拼写错误和其他错误，从而在页面之间导航时提高类型安全性。

要启用此功能，需要启用 experimental.typedRoutes 并且项目需要使用 TypeScript。

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}
 
export default nextConfig

Next.js 将在 .next/types 中生成一个链接定义，其中包含应用程序中所有现有路由的信息，然后 TypeScript 可以使用这些信息在编辑器中提供有关无效链接的反馈。

目前，实验性支持包括任何字符串字面量，包括动态片段。对于非字面量字符串，您目前需要手动将 href 转换为 Route 类型。

import type { Route } from 'next';
import Link from 'next/link'
 
// No TypeScript errors if href is a valid route
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />
 
// TypeScript errors if href is not a valid route
<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>My Card</div>
    </Link>
  )
}

它是如何工作的？

在运行 next dev 或 next build 时，Next.js 会在 .next 内部生成一个隐藏的 .d.ts 文件，其中包含应用程序中所有现有路由的信息（所有有效路由作为 Link 的 href 类型）。此 .d.ts 文件包含在 tsconfig.json 中，TypeScript 编译器将检查该 .d.ts 并提供有关无效链接的编辑器反馈。

端到端类型安全性

Next.js App Router 具有增强的类型安全性。这包括

1. 在获取函数和页面之间无需序列化数据：您可以在服务器端的组件、布局和页面中直接进行 fetch 操作。这些数据无需序列化（转换为字符串）即可传递到客户端并在 React 中使用。相反，由于 app 默认使用服务器组件，因此我们可以在没有任何额外步骤的情况下使用 Date、Map、Set 等值。以前，您需要使用 Next.js 特定的类型手动为服务器和客户端之间的边界添加类型。
2. 简化的组件之间的数据流：随着 _app 被根布局取代，现在更容易可视化组件和页面之间的数据流。以前，在各个 pages 和 _app 之间流动的数据很难添加类型，并且可能导致令人困惑的错误。使用 App Router 中的与位置相关的数据获取，这个问题不再存在。

Next.js 中的数据获取 现在提供了尽可能接近端到端类型安全性的功能，而不会对您的数据库或内容提供程序选择施加限制。

我们可以像使用普通 TypeScript 一样为响应数据添加类型。例如

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // The return value is *not* serialized
  // You can return Date, Map, Set, etc.
  return res.json()
}
 
export default async function Page() {
  const name = await getData()
 
  return '...'
}

为了实现完全的端到端类型安全性，这也要求您的数据库或内容提供程序支持 TypeScript。这可以通过使用ORM 或类型安全的查询构建器来实现。

异步服务器组件 TypeScript 错误

要将 async 服务器组件与 TypeScript 一起使用，请确保您使用的是 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" 选项。

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

增量类型检查

从 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"]
}

版本变更