第 12 章:声明文件与第三方类型
真实项目不可能所有类型都自己写。你用的
lodash、express、某个只有 JS 版本的老库,都得先有"类型说明书"。这一章讲这份说明书怎么写。
学习目标
- 知道一个包的类型是从哪来的,遇到"找不到声明"知道去哪找
- 会读
.d.ts,理解declare系列语句在做什么 - 会给一个没有类型的 JS 库写最小声明文件
- 会用模块扩充给第三方类型补字段
- 知道怎么治理项目里的
any泄漏
12.1 .d.ts 是什么
声明文件只描述类型,不包含任何实现:
// 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/xxx | node_modules/@types/xxx | DefinitelyTyped 社区维护,覆盖几万个包 |
| 自己写 | 项目内 *.d.ts | 前两者都没有,或需要扩充 |
装类型的命令
npm install -D @types/node
npm install -D @types/lodash注意 @types 包永远装成开发依赖,它们只在编译时需要。
判断一个包有没有类型
npm view some-package types
npm view some-package typings有输出就说明自带类型。没有的话先搜 @types/some-package 是否存在:
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 不知道"的值:
// 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
声明一个模块:
// 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' 就有类型了,不再报"找不到声明"。
如果只想"先让它能用",可以写一个兜底的宽松声明:
declare module 'some-lib'这等于把它整个标成 any,能编译通过,但没有任何类型保护。这是临时手段,别长期留着——项目里每多一条这样的声明,就多一块"类型盲区"。
declare global
在模块文件里扩展全局作用域:
// types/global.d.ts
export {}
declare global {
interface Window {
__APP_CONFIG__: {
apiBase: string
env: 'dev' | 'prod'
}
}
}两个细节:
- 文件里必须有
export {}(或任意import/export),否则它会被当成全局脚本而不是模块; declare global只在模块内可用,作用是"往全局里加东西"。
这样 window.__APP_CONFIG__ 就有类型了。
export as namespace
声明 UMD 库在全局暴露的名字:
export as namespace MyLib
export function init(): void配合 <script> 直接引入时可以用 MyLib.init()。
12.4 模块扩充:给别人的类型加字段
这是最常用的声明技巧。比如用 express 时,想在 req 上挂一个 user:
// 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 只是重新导出。扩充时要改"接口真正定义的地方"。
一个更通用的例子:给第三方库的配置对象加字段。
// 假设某库导出了 Config 接口
declare module 'some-lib' {
interface Config {
customField?: string
}
}要点:
- 用
interface而不是type,因为接口支持声明合并; - 扩充只影响类型,不会改变库的运行时行为;
- 扩充不要写成"重写整个接口",只加你需要的那几个字段。
12.5 给纯 JS 库写最小声明
假设有一个老库 legacy-chart,用法是:
const chart = legacyChart.create('#app', { type: 'line' })
chart.setData([1, 2, 3])
chart.destroy()它没有类型。写一份最小声明:
// 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:
/**
* @param {number} amount
* @returns {string}
*/
export function formatPrice(amount) {
return `¥${amount.toFixed(2)}`
}配 tsconfig 的 allowJs: true + checkJs: true,TS 就能从 JSDoc 里推断类型。这适合"老项目慢慢迁"的阶段。
12.6 治理 any 泄漏
any 最麻烦的地方是会传播:
const data = JSON.parse(text) // any
const user = data.user // any
const name = user.name // any
name.toUpperCase() // 不检查,运行时可能崩一个 any 进来,下游几十行全都失去保护。治理分四步:
第一步:打开 noImplicitAny
{ "compilerOptions": { "strict": true } }strict 里已经包含它。这一项能拦住"悄悄变成 any"的情况,但拦不住你手写的 : any。
第二步:Lint 规则限制显式 any
// .eslintrc 片段(使用 @typescript-eslint)
{
"rules": {
"@typescript-eslint/no-explicit-any": "error"
}
}如果项目太大改不动,先设成 warn,统计数量,逐步清零。
第三步:把 any 收在边界这一处
外部数据进来时,用一个统一的解析函数收口:
// 所有外部数据都从这里过
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
}第四步:用运行时校验库替代断言
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 仓库,你该按什么顺序读、用什么工具读、遇到报错怎么定位。这一章是全书的"实战总装"。