Skip to content
Lv1TypeScript进度 12 / 14

第 12 章:声明文件与第三方类型 ​

真实项目不可能所有类型都自己写。你用的 lodash、express、某个只有 JS 版本的老库,都得先有"类型说明书"。这一章讲这份说明书怎么写。


学习目标 ​

  • 知道一个包的类型是从哪来的,遇到"找不到声明"知道去哪找
  • 会读 .d.ts,理解 declare 系列语句在做什么
  • 会给一个没有类型的 JS 库写最小声明文件
  • 会用模块扩充给第三方类型补字段
  • 知道怎么治理项目里的 any 泄漏

12.1 .d.ts 是什么 ​

声明文件只描述类型,不包含任何实现:

typescript
// math.d.ts
export function add(a: number, b: number): number
export function multiply(a: number, b: number): number

它不生成 JS,也不做任何事,作用只有一个:告诉编译器"有这么个东西,它的类型长这样"。

为什么需要它?因为很多库是用 JS 写的,或者虽然用 TS 写但发布时没带类型。编译器看到 import lodash from 'lodash' 时,需要一份"说明书"才能检查你的用法。


12.2 类型的三个来源 ​

按优先级从高到低:

来源位置说明
包自带类型包内 index.d.ts,package.json 的 types / typings 字段作者自己维护,最准
@types/xxxnode_modules/@types/xxxDefinitelyTyped 社区维护,覆盖几万个包
自己写项目内 *.d.ts前两者都没有,或需要扩充

装类型的命令 ​

bash
npm install -D @types/node
npm install -D @types/lodash

注意 @types 包永远装成开发依赖,它们只在编译时需要。

判断一个包有没有类型 ​

bash
npm view some-package types
npm view some-package typings

有输出就说明自带类型。没有的话先搜 @types/some-package 是否存在:

bash
npm view @types/some-package version

都没有,就得自己写(12.5 节)。

编辑器里悬停在一个导入的模块上,看到 Could not find a declaration file for module 'xxx',就是这三条路都走不通。


12.3 declare 系列语句 ​

declare const / declare function / declare class ​

描述一个"运行时已经存在,只是 TS 不知道"的值:

typescript
// global.d.ts
declare const APP_VERSION: string
declare function trackEvent(name: string, payload?: Record<string, unknown>): void
declare class LegacyPlayer {
  play(url: string): void
  stop(): void
}

这些声明不生成任何代码。如果运行时没有对应的东西,代码会在运行时崩——声明只是"承诺"。

典型用途:<script> 注入的全局变量、构建时通过 define 替换的常量(如 Vite 的 __APP_VERSION__)。

declare module ​

声明一个模块:

typescript
// types/some-lib.d.ts
declare module 'some-lib' {
  export function doSomething(input: string): number
  export interface Options {
    debug?: boolean
  }
  const version: string
  export default version
}

这样 import { doSomething } from 'some-lib' 就有类型了,不再报"找不到声明"。

如果只想"先让它能用",可以写一个兜底的宽松声明:

typescript
declare module 'some-lib'

这等于把它整个标成 any,能编译通过,但没有任何类型保护。这是临时手段,别长期留着——项目里每多一条这样的声明,就多一块"类型盲区"。

declare global ​

在模块文件里扩展全局作用域:

typescript
// types/global.d.ts
export {}

declare global {
  interface Window {
    __APP_CONFIG__: {
      apiBase: string
      env: 'dev' | 'prod'
    }
  }
}

两个细节:

  1. 文件里必须有 export {}(或任意 import/export),否则它会被当成全局脚本而不是模块;
  2. declare global 只在模块内可用,作用是"往全局里加东西"。

这样 window.__APP_CONFIG__ 就有类型了。

export as namespace ​

声明 UMD 库在全局暴露的名字:

typescript
export as namespace MyLib
export function init(): void

配合 <script> 直接引入时可以用 MyLib.init()。


12.4 模块扩充:给别人的类型加字段 ​

这是最常用的声明技巧。比如用 express 时,想在 req 上挂一个 user:

typescript
// types/express.d.ts
import type { User } from './user'

declare module 'express-serve-static-core' {
  interface Request {
    user?: User
  }
}

为什么是 express-serve-static-core 而不是 express?因为 express 的 Request 接口实际定义在那个内部包里,express 只是重新导出。扩充时要改"接口真正定义的地方"。

一个更通用的例子:给第三方库的配置对象加字段。

typescript
// 假设某库导出了 Config 接口
declare module 'some-lib' {
  interface Config {
    customField?: string
  }
}

要点:

  • 用 interface 而不是 type,因为接口支持声明合并;
  • 扩充只影响类型,不会改变库的运行时行为;
  • 扩充不要写成"重写整个接口",只加你需要的那几个字段。

12.5 给纯 JS 库写最小声明 ​

假设有一个老库 legacy-chart,用法是:

javascript
const chart = legacyChart.create('#app', { type: 'line' })
chart.setData([1, 2, 3])
chart.destroy()

它没有类型。写一份最小声明:

typescript
// types/legacy-chart.d.ts
declare module 'legacy-chart' {
  export interface ChartOptions {
    type: 'line' | 'bar' | 'pie'
    width?: number
    height?: number
  }

  export interface Chart {
    setData(data: number[]): void
    destroy(): void
  }

  export function create(selector: string, options: ChartOptions): Chart
}

原则:

做法说明
只声明你真正用到的 API不必覆盖库的全部能力,用到再加
参数用联合类型收窄'line' | 'bar' 比 string 有用得多
返回值给具体接口后续调用有补全
拿不准的地方标 unknown不要标 any,否则等于没写
文件名放 types/ 并确保被 include否则编译器根本读不到

先跑起来再补:第一次写声明时不用求全,把当前报错的调用补上,后面遇到新的再加。声明文件是可以渐进生长的。

用 JSDoc 作为替代方案 ​

如果库是项目内部的 JS 文件,也可以不写 .d.ts,直接在 JS 里加 JSDoc:

javascript
/**
 * @param {number} amount
 * @returns {string}
 */
export function formatPrice(amount) {
  return `¥${amount.toFixed(2)}`
}

配 tsconfig 的 allowJs: true + checkJs: true,TS 就能从 JSDoc 里推断类型。这适合"老项目慢慢迁"的阶段。


12.6 治理 any 泄漏 ​

any 最麻烦的地方是会传播:

typescript
const data = JSON.parse(text)   // any
const user = data.user          // any
const name = user.name          // any
name.toUpperCase()              // 不检查,运行时可能崩

一个 any 进来,下游几十行全都失去保护。治理分四步:

第一步:打开 noImplicitAny ​

json
{ "compilerOptions": { "strict": true } }

strict 里已经包含它。这一项能拦住"悄悄变成 any"的情况,但拦不住你手写的 : any。

第二步:Lint 规则限制显式 any ​

json
// .eslintrc 片段(使用 @typescript-eslint)
{
  "rules": {
    "@typescript-eslint/no-explicit-any": "error"
  }
}

如果项目太大改不动,先设成 warn,统计数量,逐步清零。

第三步:把 any 收在边界这一处 ​

外部数据进来时,用一个统一的解析函数收口:

typescript
// 所有外部数据都从这里过
function parseJson(text: string): unknown {
  return JSON.parse(text)
}

// 用类型守卫判断
function isUser(v: unknown): v is User {
  return typeof v === 'object' && v !== null && 'id' in v
}

const raw = parseJson(responseText)
if (isUser(raw)) {
  console.log(raw.name)   // 这里已收窄,没有 any
}

第四步:用运行时校验库替代断言 ​

typescript
import { z } from 'zod'

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

type User = z.infer<typeof UserSchema>

const user = UserSchema.parse(responseJson)   // 校验失败会抛错

zod 这类库的价值是:一份 schema 同时产出"运行时校验"和"编译期类型",两者永远不会漂移。第 14 章会再讲怎么把它放在项目边界。


12.7 常见误区 ​

误区一:写个 declare module 'xxx' 就完事了。 → 那是把模块标成 any,只是让红线消失。要用的话至少补上你调用的函数签名。

误区二:declare 会生成运行时代码。 → 不会。它只是类型声明,运行时没有对应实现就会崩。

误区三:模块扩充可以用 type 定义。 → 扩充依赖"声明合并",只有 interface 支持。

误区四:@types 包装成生产依赖。 → 只在编译时需要,装成 -D。

误区五:skipLibCheck: true 等于不检查类型。 → 它只跳过第三方 .d.ts 内部的检查,你自己的代码照常检查。

误区六:把 any 换成 unknown 就万事大吉。 → unknown 安全,但你必须在使用前收窄。如果到处 as any 绕过去,等于没改。


本章小结 ​

要点说明
.d.ts只有类型没有实现,不生成 JS
三个来源包自带 types 字段 → @types/xxx → 自己写
declare const/function/class声明运行时就存在的值
declare module给模块写声明;空的等于全 any,只作临时方案
declare global模块内扩展全局,文件需有 export {}
模块扩充declare module + interface,改接口真正定义的地方
最小声明只写用到的 API,参数用字面量联合,返回值给接口
any 治理noImplicitAny + lint + 边界收口 + 运行时校验
zod一份 schema 同时产出运行时校验和类型

下一章预告 ​

类型知识到这里已经够用了。下一章换个视角:给你一个从没见过的 TS 仓库,你该按什么顺序读、用什么工具读、遇到报错怎么定位。这一章是全书的"实战总装"。

👉 第 13 章:真实项目阅读实战

本文阅读--次|全站访问--次|访客--人