Next.js TypeScript 配置进阶：tsconfig 优化与类型安全实践

凌晨三点，我盯着测试报告上那行刺眼的红字：“Production Error: Cannot read property ‘id’ of undefined”。用户反馈说点击个人中心页面直接白屏了。回头翻代码——路由写成了 /users/profile 而不是 /user/profile，多了个 s。TypeScript 毫无提示，IDE 也没报错,就这么堂而皇之上线了。

你可能会想,这不就是个低级错误吗？确实。但说实话,这种”低级错误”在我维护的项目里出现的频率高得让人心累。路由拼写错误、环境变量名打错、函数参数类型全是 any… TypeScript 明明号称”类型安全”,结果用起来感觉跟 JavaScript 也没什么区别。

后来我才发现,不是 TypeScript 不行,是我的配置太烂了。tsconfig.json 里一堆选项,不知道该开哪个关哪个;网上教程说法不一,有人说严格模式会增加开发负担,有人又说不开严格模式等于白用。搞了快一年 Next.js + TypeScript,项目里的 any 还是满天飞。

阿里云 - 开发者上云首选，轻量服务器专享 8.5 折优惠，助力项目快速上线

领取 8.5 折优惠 →推广

这篇文章,我想聊聊这一年踩坑后总结的经验。从 tsconfig 的优化配置,到类型安全路由的实现,再到环境变量的类型定义,一步步把 TypeScript 从”绊脚石”变成”守护神”。不是高深理论,就是实打实能用上的东西。

tsconfig 优化配置 - 打好基础

理解 strict 模式的真正含义

很多人（包括以前的我）以为 strict: true 就是个开关，打开它 TypeScript 就会变严格。其实不是。

翻开 TypeScript 官方文档你会发现，strict 其实是 7 个编译选项的快捷方式：

{
  "compilerOptions": {
    "strict": true,
    // 等同于下面这 7 个全部为 true
    "strictNullChecks": true,        // 严格空值检查
    "strictFunctionTypes": true,     // 严格函数类型检查
    "strictBindCallApply": true,     // 严格 bind/call/apply 检查
    "strictPropertyInitialization": true, // 严格属性初始化
    "noImplicitAny": true,          // 禁止隐式 any
    "noImplicitThis": true,         // 禁止隐式 this
    "alwaysStrict": true            // 始终以严格模式解析
  }
}

最有用的是前三个。先说 strictNullChecks——这个开启后，TypeScript 会把 null 和 undefined 当成独立的类型，而不是”任何类型的合法值”。

举个例子。假设你从数据库查用户信息：

// 没开 strictNullChecks
const user = await db.user.findOne({ id: userId })
console.log(user.name) // TypeScript 不报错，但 user 可能是 null

// 开启后
const user = await db.user.findOne({ id: userId })
console.log(user.name) // ❌ TypeScript 报错：对象可能为 null

// 必须这样写
if (user) {
  console.log(user.name) // ✅ 通过
}

当时我第一次在老项目里开启这个选项，IDE 里瞬间爆出 200 多个红色波浪线。整个人都慌了，差点想关回去。但静下心来看，这些”错误”其实都是潜在的 bug——那些没做空值判断的地方，线上真的会炸。

noImplicitAny 也很关键。它禁止函数参数或变量”隐式地”变成 any 类型：

// 没开 noImplicitAny
function handleData(data) {  // data 自动变成 any
  return data.value  // 任何操作都不报错
}

// 开启后
function handleData(data) {  // ❌ 报错：参数隐式具有 any 类型
  return data.value
}

// 必须显式标注
function handleData(data: { value: string }) {  // ✅
  return data.value
}

老实讲，刚开始会觉得麻烦。以前随手写个函数就行，现在还得定义类型。但用了一段时间后，你会发现 IDE 的提示变聪明了——输入 data. 的瞬间，所有属性都蹦出来了，再也不用跑去翻文档。

Next.js 特有的 TypeScript 配置

Next.js 项目的 tsconfig.json 有些特殊配置，直接贴一份我现在用的最佳实践版本：

{
  "compilerOptions": {
    // 基础配置
    "target": "ES2020",
    "lib": ["dom", "dom.iterable", "esnext"],
    "jsx": "preserve",
    "module": "esnext",
    "moduleResolution": "bundler",

    // Next.js 必需
    "allowJs": true,
    "noEmit": true,
    "esModuleInterop": true,
    "isolatedModules": true,
    "resolveJsonModule": true,

    // 严格模式（核心）
    "strict": true,
    "skipLibCheck": true,

    // 性能优化
    "incremental": true,

    // Next.js 插件
    "plugins": [
      {
        "name": "next"
      }
    ],

    // 路径别名
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/styles/*": ["./src/styles/*"]
    }
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts"
  ],
  "exclude": ["node_modules"]
}

重点讲几个容易忽略的：

1. incremental：增量编译

这个选项能大幅加快大型项目的编译速度。开启后，TypeScript 会缓存上次编译的信息，下次只编译改动的文件。我在一个 300+ 组件的项目里测过，编译时间从 45 秒降到 18 秒左右，效果挺明显。

2. paths：路径别名

以前写导入路径是这样的：

import Button from '../../../components/ui/Button'
import { formatDate } from '../../../../lib/utils'

数不清有几个 ..，稍微调整下文件夹结构就全报错。

配置别名后：

import Button from '@/components/ui/Button'
import { formatDate } from '@/lib/utils'

清爽多了。而且 TypeScript 会正确推断类型，IDE 的跳转功能也能用。

3. plugins：Next.js 插件

这个 "plugins": [{ "name": "next" }] 别看简单，它能让 TypeScript 理解 Next.js 特有的东西——比如 app 目录下的 layout.tsx、page.tsx 这些特殊文件的类型，还有服务端组件和客户端组件的区分。

不加这个插件，你写服务端组件的时候 TypeScript 可能会给你乱报类型错误。

渐进式启用严格模式

如果你的项目已经跑了一阵子，代码量不小，直接开启 strict: true 确实会很痛苦。我的建议是：别硬刚。

策略一：新代码严格，旧代码慢慢改

在 tsconfig.json 里保持 strict: true，但对于暂时改不完的旧文件，可以在文件顶部加：

// @ts-nocheck  // 跳过整个文件的类型检查

或者针对具体某行：

// @ts-ignore  // 忽略下一行的类型错误

不过要注意，@ts-ignore 和 @ts-expect-error 有区别：

// @ts-ignore
const x = 1 as any  // 即使下一行没错误也不报错

// @ts-expect-error
const y = 1  // 如果下一行没错误，TypeScript 会警告你"不必要的注释"

我更推荐用 @ts-expect-error，它能防止你”忘记删除注释”——bug 修复后，TypeScript 会提醒你这个注释已经没必要了。

策略二：按功能模块逐步开启

比如先把 components 目录下的文件改干净，其他目录暂时保持宽松。可以这样配置：

// tsconfig.strict.json（严格模式）
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "strict": true
  },
  "include": ["src/components/**/*"]
}

平时开发用正常的 tsconfig.json，重构某个模块时切换到 strict 版本。

话说回来，严格模式真不是为了折腾人。我有次在重构一个老组件时，开启 strictNullChecks 后发现 5 处空值判断缺失，其中 3 处在生产环境已经报过错了，只是被 try-catch 吞掉了没暴露出来。那一刻突然觉得，这些红色波浪线挺可爱的。

类型安全路由实现 - 告别拼写错误

Next.js 内置的 Typed Routes

还记得文章开头提到的那个线上 bug 吗？路由多打了个 s，结果页面 404。这种错误其实完全可以避免。

Next.js 13 引入了一个实验性功能：typedRoutes。开启后，TypeScript 会为你的所有路由生成类型定义。

怎么开启？

在 next.config.ts 里加一行：

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

const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,  // 开启类型安全路由
  },
}

export default nextConfig

然后重启开发服务器（npm run dev），Next.js 会自动扫描你的 app 目录，在 .next/types 文件夹里生成路由类型定义。

效果长什么样？

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

假设你的项目结构是这样：

app/
├── page.tsx           // 首页
├── blog/
│   ├── page.tsx      // 博客列表
│   └── [slug]/
│       └── page.tsx  // 博客详情
└── user/
    └── [id]/
        └── profile/
            └── page.tsx  // 用户个人中心

启用 typedRoutes 后，在 Link 组件和 useRouter 里写路由，IDE 会给你自动补全：

import Link from 'next/link'

export default function Nav() {
  return (
    <nav>
      <Link href="/">首页</Link>
      <Link href="/blog">博客</Link>
      <Link href="/blog/hello-world">文章详情</Link>
      <Link href="/user/123/profile">个人中心</Link>

      {/* ❌ TypeScript 报错：路由不存在 */}
      <Link href="/users/123/profile" />  // 注意这里是 users 不是 user
    </nav>
  )
}

你输入 href="/ 的时候，IDE 会弹出所有可用的路由。写错了会立刻报红。

不骗你，第一次体验到这个功能的时候，我心里只有两个字：真香。

局限性

不过这个功能目前还有些限制：

1. 仅支持 App Router：如果你的项目还在用 pages 目录，这个功能用不了
2. 动态路由参数需要手动传：比如 /blog/[slug]，你还是得自己拼接 slug 值
3. 查询参数不做检查：/user?tab=settings 里的 tab 参数不会被类型检查

说白了，它能保证路径本身不会拼错，但参数值还是得靠你自己注意。

第三方库：nextjs-routes

如果你还在用 pages 目录，或者想要更完整的路由类型安全（包括查询参数），可以试试 nextjs-routes 这个库。

安装和配置：

npm install nextjs-routes

然后在 next.config.ts 里加上：

const nextRoutes = require('nextjs-routes/config')

const nextConfig = nextRoutes({
  // 你原来的 Next.js 配置
})

export default nextConfig

使用方式：

这个库会生成一个 route 函数，让你用对象的方式定义路由：

import { route } from 'nextjs-routes'

// 类型安全的路由对象
const profileRoute = route({
  pathname: '/user/[id]/profile',
  query: {
    id: '123',
    tab: 'settings',  // 查询参数也有类型检查
  }
})

router.push(profileRoute)  // 完全类型安全

// 如果路径写错了
const wrongRoute = route({
  pathname: '/users/[id]/profile',  // ❌ TypeScript 报错：路径不存在
})

对比 Next.js 内置方案，nextjs-routes 的优势是：

• 支持 pages 目录
• 查询参数有类型检查
• 可以用对象方式定义路由，不用手动拼接字符串

缺点是需要额外安装依赖，而且每次修改路由结构都需要重新生成类型文件（不过这个是自动的）。

路由参数的类型推断

动态路由的参数怎么办？比如 app/blog/[slug]/page.tsx，这个 slug 参数的类型是啥？

Next.js 会自动为你生成 params 的类型：

// app/blog/[slug]/page.tsx
export default function BlogPost({
  params,
}: {
  params: { slug: string }
}) {
  return <h1>文章：{params.slug}</h1>
}

但这样的问题是：slug 只是 string 类型，任何字符串都能传进来。如果你想更严格一点——比如只允许特定格式的 slug，可以用 zod 做运行时验证：

import { z } from 'zod'

const slugSchema = z.string().regex(/^[a-z0-9-]+$/)

export default function BlogPost({
  params,
}: {
  params: { slug: string }
}) {
  // 验证 slug 格式
  const validatedSlug = slugSchema.parse(params.slug)

  return <h1>文章：{validatedSlug}</h1>
}

如果 slug 不符合格式（比如包含大写字母或特殊字符），zod 会抛错。

这招在处理 API 路由时特别有用。毕竟用户传什么你控制不了，提前验证总比线上爆炸好。

环境变量类型定义 - 彻底消除 any

问题的根源

环境变量这块，TypeScript 默认的支持真的挺差的。

你肯定写过这样的代码：

const apiKey = process.env.API_KEY

鼠标移到 apiKey 上，类型是 string | undefined。好吧，至少还知道可能是 undefined。

但更常见的情况是这样：

const apiUrl = process.env.NEXT_PUBLIC_API_URL
console.log(apiUrl.toUpperCase())  // 运行时爆炸：apiUrl is undefined

TypeScript 不报错，运行的时候才发现环境变量根本没配置。

而且环境变量名拼错了，TypeScript 也不知道：

const key = process.env.API_SECRE  // 少打了个 T
// TypeScript：没问题，我就是个 string | undefined

这就很尴尬了。明明用了 TypeScript，结果还是靠肉眼检查变量名，跟写 JavaScript 有啥区别？

使用 T3 Env 方案（推荐）

解决这个问题，目前社区最认可的方案是 T3 Env。它能同时提供类型检查和运行时验证，两手抓两手都要硬。

安装：

Railway - 现代化的部署平台，告别繁琐运维，让代码分钟级上线

立即开始 →推广

npm install @t3-oss/env-nextjs zod

配置：

在项目根目录创建 env.mjs（或 env.ts）：

import { createEnv } from "@t3-oss/env-nextjs"
import { z } from "zod"

export const env = createEnv({
  // 服务端环境变量（不能在客户端访问）
  server: {
    DATABASE_URL: z.string().url(),
    API_SECRET: z.string().min(32),
    SMTP_HOST: z.string().min(1),
  },

  // 客户端环境变量（必须以 NEXT_PUBLIC_ 开头）
  client: {
    NEXT_PUBLIC_APP_URL: z.string().url(),
    NEXT_PUBLIC_ANALYTICS_ID: z.string().optional(),
  },

  // 运行时环境变量映射
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    API_SECRET: process.env.API_SECRET,
    SMTP_HOST: process.env.SMTP_HOST,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
    NEXT_PUBLIC_ANALYTICS_ID: process.env.NEXT_PUBLIC_ANALYTICS_ID,
  },
})

使用：

import { env } from './env.mjs'

// ✅ 完全类型安全，自动补全
const dbUrl = env.DATABASE_URL  // string
const appUrl = env.NEXT_PUBLIC_APP_URL  // string

// ❌ TypeScript 报错：拼写错误
const wrong = env.DATABASE_UR

// ❌ TypeScript 报错：客户端不能访问服务端变量
// 在客户端组件里
'use client'
const secret = env.API_SECRET  // 编译报错

最爽的地方：

1. 启动时验证：如果环境变量缺失或格式不对，应用启动时就会报错，而不是等到运行时
2. 类型推断：所有环境变量都有准确的类型，不再是 string | undefined
3. 防泄露：客户端代码访问服务端变量会直接编译报错

我在用 T3 Env 之前，测试环境经常因为忘记配置某个环境变量导致服务起不来，每次都要查日志才知道少了哪个。现在启动时就能发现，省了不少时间。

自定义类型声明文件方案

如果你不想引入 T3 Env，或者项目规模比较小，也可以手动扩展 ProcessEnv 的类型：

// env.d.ts
namespace NodeJS {
  interface ProcessEnv {
    // 服务端变量
    DATABASE_URL: string
    API_SECRET: string
    SMTP_HOST: string

    // 客户端变量
    NEXT_PUBLIC_APP_URL: string
    NEXT_PUBLIC_ANALYTICS_ID?: string  // 可选变量用 ?
  }
}

这样 TypeScript 就知道这些变量的类型了：

const dbUrl = process.env.DATABASE_URL  // string
const apiSecret = process.env.API_SECRET  // string

// ❌ TypeScript 报错
const wrong = process.env.DATABASE_UR  // Property 'DATABASE_UR' does not exist

缺点：

• 没有运行时验证，环境变量缺失只能等运行时才发现
• 不能防止客户端访问服务端变量
• 需要手动维护类型定义

适合小项目或者对类型安全要求不那么高的场景。但说实话，都用 TypeScript 了，还是推荐用 T3 Env 一步到位。

TypeScript 严格模式应用 - 实战技巧

处理第三方库的类型问题

有时候不是你的代码有问题，而是第三方库没提供类型定义，或者类型定义有 bug。

情况一：库完全没有类型定义

比如你用了个老旧的 npm 包，import 进来全是 any：

import oldLib from 'some-old-lib'  // any

先去 npm 搜一下有没有 @types/some-old-lib：

npm install -D @types/some-old-lib

如果没有，就得自己写了。创建 types/some-old-lib.d.ts：

declare module 'some-old-lib' {
  export function doSomething(param: string): number
  export default someOldLib
}

这样 TypeScript 就知道这个库的类型了。

情况二：类型定义有问题

有时候 @types 包的类型定义跟实际 API 对不上（特别是一些快速迭代的库）。这时候可以用”类型断言”临时处理：

import { someFunction } from 'buggy-lib'

// 类型定义说返回 string，但实际返回 number
const result = someFunction() as number

不过这只是临时方案，最好去库的 GitHub 提个 issue 或 PR。

skipLibCheck 该不该开？

tsconfig 里有个 skipLibCheck 选项，开启后 TypeScript 会跳过 node_modules 里的类型检查。

我的建议是：开启。

为什么？node_modules 里的类型错误你改不了，而且会拖慢编译速度。与其让 TypeScript 检查一堆第三方库的类型问题，不如专注于自己的代码。

阿里云 - 开发者上云首选，轻量服务器专享 8.5 折优惠，助力项目快速上线

领取 8.5 折优惠 →推广

常见的 any 逃逸场景及解决方案

即使开了严格模式，还是有些地方容易”逃逸”成 any 类型。

场景一：事件处理函数

// ❌ 不好的做法
const handleSubmit = (e: any) => {
  e.preventDefault()
}

// ✅ 正确的做法
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
  e.preventDefault()
  // e.currentTarget 有完整的类型提示
}

常用的事件类型：

• React.MouseEvent<HTMLButtonElement>
• React.ChangeEvent<HTMLInputElement>
• React.KeyboardEvent<HTMLDivElement>

场景二：API 响应数据

// ❌ 不好的做法
const res = await fetch('/api/user')
const data = await res.json()  // any

// ✅ 方案一：手动定义接口
interface User {
  id: string
  name: string
  email: string
}

const data: User = await res.json()

// ✅ 方案二：用 zod 验证（推荐）
import { z } from 'zod'

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
})

const data = UserSchema.parse(await res.json())  // 自动推断类型

用 zod 的好处是既有类型检查，又有运行时验证。万一后端返回的数据结构变了，立刻就能发现。

场景三：动态导入

// ❌ 不好的做法
const module = await import('./utils')  // any

// ✅ 正确的做法
const module = await import('./utils') as typeof import('./utils')

或者直接用具体的导入：

const { formatDate } = await import('./utils')  // 自动推断类型

利用 TypeScript 工具类型提升开发效率

TypeScript 内置了一堆工具类型，用好了能省不少代码。

Pick：提取部分属性

interface User {
  id: string
  name: string
  email: string
  password: string
  createdAt: Date
}

// 只需要用户的公开信息
type PublicUser = Pick<User, 'id' | 'name' | 'email'>
// { id: string; name: string; email: string }

Omit：排除某些属性

// 创建用户时不需要 id 和 createdAt
type CreateUserInput = Omit<User, 'id' | 'createdAt'>

Partial：所有属性变可选

// 更新用户时，所有字段都是可选的
type UpdateUserInput = Partial<User>

Required：所有属性变必选

type RequiredUser = Required<Partial<User>>  // 反向操作

自定义工具类型

如果内置的不够用，可以自己写：

// 把所有字符串属性变成可选
type PartialString<T> = {
  [K in keyof T]: T[K] extends string ? T[K] | undefined : T[K]
}

说实话，这些工具类型刚开始看起来有点吓人，但用习惯了会发现真的很香——尤其是处理复杂对象类型的时候，能省掉一大堆重复代码。

结论

写到这，回想文章开头那个凌晨三点的 bug。

如果当时我开启了 Next.js 的 typedRoutes，路由拼写错误根本不可能上线；如果用了 T3 Env，环境变量缺失启动时就会报错；如果严格模式配好了，那些隐式 any 早就被 TypeScript 揪出来了。

TypeScript 的类型安全不是为了折腾人，而是把 bug 从”运行时”提前到”编写时”。与其等着用户在生产环境遇到白屏，不如让 IDE 在你敲代码的时候就报红。

最后总结一下这篇文章的核心要点：

1. tsconfig 优化：开启 strict 模式，配置 incremental 和 paths，使用 Next.js 插件
2. 类型安全路由：Next.js 13+ 开启 typedRoutes，或者用 nextjs-routes 库
3. 环境变量类型：用 T3 Env 实现类型检查 + 运行时验证
4. 严格模式实践：渐进式开启，处理第三方库类型问题，消灭常见的 any 逃逸场景

刚开始可能会觉得配置麻烦、类型标注繁琐，但当你习惯了 IDE 的精准提示、习惯了改代码时立刻发现潜在问题，你就再也回不去”裸奔”的 JavaScript 时代了。

现在就打开你的 tsconfig.json，把 strict 改成 true 吧。红色波浪线越多，说明你发现的潜在 bug 越多——这是好事。

13 分钟阅读 · 发布于: 2026年1月6日 · 修改于: 2026年1月22日

Easton

技术开发