03.3.1.5 工程实践与声明文件
所属:全栈开发面试题库 / 03 前端基础与 Web 开发 / 03.3 TypeScript / 03.3.1 类型系统与工程实践
03.3.1.5-001 .d.ts 声明文件有什么作用?
一句话结论
.d.ts 只包含类型声明、不包含运行时实现,用于描述已有 JavaScript 库、全局变量与模块的类型形状,供编译器检查与编辑器提示。
概念解释
- 声明文件编译后不生成对应 JS。
- 可手写描述第三方无类型包,也可由 TS 编译自动生成。
- 项目内类型约定可放在
types/目录并被 tsconfig 包含。
原理流程
- 为模块/全局对象写类型声明。
- 编译器在解析导入与全局引用时读取声明。
- 匹配调用处类型并报错或提示。
代码 / 示例
// global.d.ts
declare const APP_VERSION: string;
declare module "legacy-lib" {
export function format(input: string): string;
}
常见误区
- 误区:
.d.ts里可以写运行时逻辑;正解:它只放类型与声明,实现必须在 JS/TS 源码中。 - 误区:声明文件会被打包进产物;正解:类型声明在编译期擦除,不进入运行时包。
追问
- Q:库发布时如何让消费者拿到类型? A:开启
declaration编译生成.d.ts,并在 package.json 的types字段指向入口声明。 - Q:项目内全局类型放哪里? A:放被 tsconfig 包含的
.d.ts文件,避免在每个文件重复声明。
03.3.1.5-002 declare module 如何描述与扩展模块?
一句话结论
declare module "包名" 为没有类型的第三方包写整体类型声明;在已存在模块声明内追加成员则属于模块扩展(增强),需遵循对应模块系统规则。
概念解释
- 缺失类型包用 declare module 兜底,避免导入报错。
- 扩展现有库类型(如给 window 加字段)用声明合并或模块增强。
- 模块声明放在被 tsconfig 包含的 d.ts 中。
原理流程
- 定位导入的模块名。
- 用 declare module 导出函数/对象/类型签名。
- 调用处按声明获得类型提示。
代码 / 示例
declare module "legacy-utils" {
export function debounce<T extends (...args: any[]) => any>(
fn: T, wait: number
): T;
export const version: string;
}
常见误区
- 误区:declare module 能补全运行时缺失的导出;正解:它只描述类型,运行时不存在的导出仍会报错。
- 误区:在模块文件里随便写 declare module 就能增强全局;正解:全局增强与模块增强写法和位置不同,需按模块系统确认。
追问
- Q:包自带类型与本地声明冲突怎么办? A:本地声明不应覆盖官方类型,优先修复类型缺口或提交类型包。
- Q:类型声明里能引用项目类型吗? A:可以 import 项目类型,但需注意声明文件的模块隔离边界。
03.3.1.5-003 三斜线指令 /// <reference> 用于什么?
一句话结论
三斜线指令用于在声明文件中引用其他类型文件、类型包或 lib 类型,是声明之间显式依赖的方式;现代工程更多用 import type 替代大部分场景。
概念解释
<reference path="...">引用本地声明文件。<reference types="...">引用@types包。- 指令必须出现在文件顶部、其他语句之前。
原理流程
- 在 d.ts 顶部写三斜线引用。
- 编译器加载被引用的类型声明。
- 当前声明可使用其中导出的类型。
代码 / 示例
/// <reference types="node" />
/// <reference path="./models.d.ts" />
declare namespace App {
const env: NodeJS.ProcessEnv;
}
常见误区
- 误区:三斜线可以放在文件任意位置;正解:必须位于所有语句之前,否则不生效。
- 误区:普通业务文件应大量使用三斜线;正解:模块内依赖优先用 import/import type,三斜线主要用于声明文件。
追问
- Q:
types与path引用区别? A:types 指向类型包,path 指向本地声明文件路径。 - Q:skipLibCheck 与三斜线有关系吗? A:无关,skipLibCheck 跳过对声明文件内部的类型检查。
03.3.1.5-004 import type、export type 与隔离模块有什么关系?
一句话结论
import type/export type 只导入导出类型、编译后擦除;开启 isolatedModules 后,文件转译时无法跨文件判断导入是否为类型,必须显式区分类型导入与值导入。
概念解释
- 普通 import 可同时带值与类型;type 限定符只保留类型用途。
- isolatedModules 要求每个文件能独立转译,避免类型被误当运行时值移除。
- re-export 类型需用
export type。
原理流程
- 区分导入是值、类型还是二者兼有。
- 类型依赖用
import type,避免打包残留。 - 隔离模块下编译器强制显式标注类型导入。
代码 / 示例
import type { User } from "./user";
import { createUser } from "./user";
export type { User };
export { createUser };
常见误区
- 误区:isolatedModules 下普通 import 类型也能正常擦除;正解:转译器看不到跨文件类型信息,需
import type显式标注。 - 误区:
export type与普通 export 完全等价;正解:隔离模块下 re-export 类型必须用export type,否则可能被当作值导出。
追问
- Q:esModuleInterop 与类型导入有关吗? A:无关,它处理 CJS/ESM 默认导入互操作,类型导入管的是编译期擦除。
- Q:Vite/esbuild 等转译器对 isolatedModules 的要求? A:默认按单文件转译,行为属工具版本相关,需对照当前构建配置确认。
03.3.1.5-005 tsconfig 有哪些决定类型行为的关键选项?
一句话结论
strict 控制检查严格度,target/module/moduleResolution 控制产物语法与模块解析,esModuleInterop 控制 CJS 互操作,skipLibCheck 跳过声明文件内部检查,noEmitOnError 控制报错是否阻断产物。
概念解释
strict是一组严格检查总开关。moduleResolution决定如何按模块说明找文件(bundler/node16/classic 等)。- 选项组合需与运行环境(浏览器/Node/打包工具)匹配。
原理流程
- 按目标环境设置 target 与 module。
- 开启 strict 收紧类型检查。
- 配置模块解析与互操作选项,消除导入类型偏差。
代码 / 示例
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "Bundler",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"noEmit": true
}
}
常见误区
- 误区:strict 只影响空值检查;正解:它包含一组检查项,见 03.3.1.1-011。
- 误区:moduleResolution 选什么都一样;正解:解析规则不同会影响类型能否找到,需与 module 和打包工具匹配。
追问
- Q:
noEmit: true下类型检查怎么做? A:tsc --noEmit只做类型检查不产 JS,适合 CI 与编辑器校验。 - Q:如何确认某个选项在所用 TS 版本中的行为? A:对照官方文档对应版本,版本新增选项需实测确认。
03.3.1.5-006 第三方类型包 @types 如何组织与引用?
一句话结论
DefinitelyTyped 维护的类型包以 @types/包名 发布,TS 默认自动包含;项目也可用 types 字段限定加载哪些类型包,或在本地写声明兜底。
概念解释
- 包自带类型时优先使用包内
types/typings字段。 - 无类型包安装对应
@types/包名。 types编译选项可限制自动加载的全局类型包。
原理流程
- 检查依赖包是否自带类型。
- 缺失时安装 @types 包或本地 declare module。
- 编译器自动解析导入的类型声明。
代码 / 示例
npm i -D @types/lodash
{ "compilerOptions": { "types": ["node", "jest"] } }
常见误区
- 误区:所有第三方包都有 @types;正解:部分包无类型,需本地声明或换有类型替代。
- 误区:在 types 里列出所有 @types;正解:列出后未列出的全局类型包不会自动加载,按需取舍。
追问
- Q:包自带类型与 @types 冲突时以谁为准? A:包内声明优先,具体解析规则按 moduleResolution 版本行为确认。
- Q:本地声明文件会被打包进发布物吗? A:库发布需通过 declaration 配置生成类型,本地兜底声明不应替代正式类型产物。
03.3.1.5-007 全局环境类型(window、document、process)从哪里来?
一句话结论
浏览器全局类型来自 TS 内置 DOM lib;Node 全局类型来自 @types/node;项目自定义全局变量在 d.ts 中用 declare const/interface 声明并确保被包含。
概念解释
- lib 选项决定内置类型集合(DOM、ES 版本、WebWorker 等)。
process不是浏览器内置,需 Node 类型包。- 扩展
window接口用声明合并追加字段。
原理流程
- tsconfig lib 加载 DOM/ES 类型。
- 安装并引用 Node 类型包获得 process。
- 自定义全局在 d.ts 中声明,编译器纳入作用域。
代码 / 示例
// env.d.ts
interface Window {
myApp: { version: string };
}
declare const process: NodeJS.Process;
常见误区
- 误区:浏览器里直接用
process有类型;正解:process 是 Node 类型,浏览器环境需类型隔离与环境判断。 - 误区:给 window 加字段直接赋值即可有类型;正解:需先在接口合并中声明该字段。
追问
- Q:lib 与 @types 区别? A:lib 是 TS 内置基础类型(DOM/ES),@types 是第三方社区类型包。
- Q:多端环境类型冲突怎么处理? A:按工程拆分 tsconfig,分别加载对应 lib 与类型包。
03.3.1.5-008 类型约定与运行时校验的边界在哪里?
一句话结论
TypeScript 类型只在编译期约束约定,运行时不拦截非法值;跨边界输入(接口响应、表单、存储、消息)必须做运行时校验,可用手写守卫或 schema 库把类型与校验规则关联。
概念解释
- 编译期类型被擦除,运行时对象形状不受类型保护。
- 可信内部代码可依赖类型,不可信外部输入必须校验。
- schema 库可从校验规则推导类型,减少重复标注。
原理流程
- 划定可信边界:内部函数、模块间调用。
- 不可信输入进入时执行守卫/schema 校验。
- 校验通过后类型收窄到约定类型再使用。
代码 / 示例
function parseUser(json: string): User | null {
const raw = JSON.parse(json) as unknown;
if (typeof raw === "object" && raw !== null && "id" in raw) {
return raw as User; // 复杂校验应交给 schema 库
}
return null;
}
常见误区
- 误区:标注了
User接口,接口返回什么都安全;正解:运行时响应形状可能与类型不符,需校验。 - 误区:类型断言能替代校验;正解:断言不产生运行时判断,错误会延迟到使用时暴露。
追问
- Q:schema 库如何做到类型与校验一致? A:解析校验定义推导 TS 类型,运行时按同一套规则校验,避免两边手写漂移。
- Q:哪些场景最容易漏校验? A:URL 参数、localStorage 读取、postMessage、第三方回调数据。
03.3.1.5-009 库项目如何发布类型声明?
一句话结论
开启 declaration(必要时 declarationMap)编译生成 .d.ts 与 source map,package.json 的 types/typings 指向入口声明文件,消费者导入即可获得类型。
概念解释
- declaration 为每个源文件生成对应声明文件。
- declarationMap 支持跳转到原始源码。
- 类型产物需与 JS 产物一起发布到包目录。
原理流程
- 配置 declaration 输出。
- 编译生成 JS 与 d.ts。
- package.json 声明 types 入口,消费者解析类型。
代码 / 示例
{
"compilerOptions": { "declaration": true, "declarationMap": true, "outDir": "dist" }
}
{ "types": "dist/index.d.ts" }
常见误区
- 误区:只发布 JS 消费者也能拿到类型;正解:缺 d.ts 时导入会提示无类型,需 any 兜底。
- 误区:声明文件随源码打包进运行时包;正解:d.ts 不进入浏览器/Node 运行时,仅供工具链读取。
追问
- Q:
emitDeclarationOnly用于什么? A:只生成声明文件不产 JS,适合类型产物单独发布场景。 - Q:内部类型需要导出吗? A:公共 API 用到的类型应导出,私有实现类型可不暴露。
03.3.1.5-010 枚举、as const 与常量对象的类型如何选择?
一句话结论
有限且需要运行时可遍历的取值集合可用枚举;纯类型层面的固定取值用字面量联合;不希望字面量被拓宽、属性保持只读的对象用 as const。
概念解释
- 枚举编译为运行时对象,有反向映射与开销。
- 字面量联合是纯类型,无运行时代码。
as const收紧推断但不冻结运行时对象。
原理流程
- 判断是否需要运行时遍历该集合。
- 需要运行时对象用枚举,只约束类型用联合。
- 固定配置对象用
as const收紧字面量与只读。
代码 / 示例
type Role = "admin" | "guest"; // 纯类型
enum Status { Todo = "TODO", Done = "DONE" } // 运行时对象
const routes = { home: "/", admin: "/admin" } as const;
type Route = typeof routes[keyof typeof routes];
常见误区
- 误区:
as const会在运行时冻结对象;正解:只改类型,冻结需Object.freeze。 - 误区:枚举比字面量联合更安全;正解:二者都约束取值,枚举额外带来运行时对象与双向映射。
追问
- Q:数字枚举反向映射是什么? A:编译后同时存键→值与值→键,字符串枚举无反向映射。
- Q:
const enum跨文件使用注意什么? A:内联行为受 isolatedModules 等配置影响,细节按版本确认。
03.3.1.5-011 如何在 CI 中做类型检查?
一句话结论
用 tsc --noEmit(或构建工具的类型检查模式)在流水线单独跑类型检查,类型错误即阻断合并;不依赖打包工具隐式转译来发现类型问题。
概念解释
--noEmit只检查不产 JS,速度适合 CI。- 项目已有构建流程时可在脚本中先跑类型检查再打包。
- 编辑器类型提示不能替代流水线门禁。
原理流程
- 脚本定义
type-check: tsc --noEmit。 - CI 拉取依赖后执行类型检查。
- 出现 error 非零退出,阻断后续部署。
代码 / 示例
{
"scripts": {
"type-check": "tsc --noEmit",
"build": "npm run type-check && vite build"
}
}
常见误区
- 误区:打包成功就代表类型没问题;正解:esbuild/vite 转译默认不做完整类型检查。
- 误区:CI 类型检查可以跳过历史报错;正解:应清零错误或按子项目拆分渐进修复。
追问
- Q:大型项目类型检查慢怎么办? A:按项目引用拆分 tsconfig、增量构建,或限制检查范围,具体方案按工具版本确认。
- Q:类型检查报错与 lint 报错如何分工? A:tsc 管类型正确性,lint 管代码风格与可疑模式。
03.3.1.5-012 存量 JS 项目如何渐进迁移到 TS?
一句话结论
先开 allowJs 让混合共存,用 checkJs 与 JSDoc 标注给关键文件补类型,再逐个改名 .ts;不要求一次性全量转换,迁移文件按风险与价值排序。
概念解释
allowJs允许 TS 工程包含 JS 文件。checkJs对 JS 文件也做类型推断检查。- JSDoc 注解可在不改文件后缀的情况下提供类型信息。
原理流程
- 开启 allowJs,工程可同时识别 JS/TS。
- 核心模块先补 JSDoc 或迁移 .ts。
- 逐步打开 checkJs 收紧 JS 文件检查。
代码 / 示例
{
"compilerOptions": {
"allowJs": true,
"checkJs": false,
"jsx": "react-jsx"
}
}
/** @param {string} name @returns {User} */
function create(name) { return { name }; }
常见误区
- 误区:迁移必须把所有文件改成 .ts;正解:可长期混合存在,按优先级逐文件推进。
- 误区:checkJs 一开就能发现所有问题;正解:JS 推断能力有限,关键类型仍需 JSDoc 或迁移后标注。
追问
- Q:JS 文件里 import TS 类型可行吗? A:需 JSDoc
@type或 allowJs 配合,跨文件类型引用按配置确认。 - Q:迁移中 any 如何控制? A:记录 any 位置与替换计划,逐步收窄到 unknown 与具体类型。
03.3.1.5-013 类、接口与抽象类在工程中如何约定使用?
一句话结论
接口定义对象结构契约,类负责实现与实例逻辑,抽象类约束子类共同行为与模板方法;implements 检查类是否满足接口结构,不影响运行时继承关系。
概念解释
- 接口只描述形状,可被类 implements。
- 抽象类不能实例化,可含实现与抽象方法。
- 工程中优先用接口定义跨模块契约,降低耦合。
原理流程
- 跨模块约定用接口描述入参与返回结构。
- 实现类 implements 接口保证结构匹配。
- 共用行为与模板步骤用抽象类抽取。
代码 / 示例
interface Repository<T> {
find(id: string): Promise<T | null>;
}
class UserRepository implements Repository<User> {
async find(id: string) { return null; }
}
abstract class BaseRepo<T> {
abstract find(id: string): Promise<T | null>;
}
常见误区
- 误区:implements 建立运行时继承;正解:它只做编译期结构检查,原型链关系由 extends 决定。
- 误区:接口可以写实现方法;正解:纯接口无实现,复用逻辑放抽象类或工具函数。
追问
- Q:接口与抽象类怎么选? A:行为多继承视角用接口,需要共享实现模板用抽象类。
- Q:类实现接口时缺方法会怎样? A:编译报错,提示缺少接口成员实现。
03.3.1.5-014 类型与模块、命名空间如何组织?
一句话结论
业务类型按模块目录就近放置,公共共享类型抽至 types/ 或共享包;现代模块系统下少用 namespace 组织代码,避免类型与运行时模块混淆。
概念解释
- 类型随功能模块内聚,降低跨目录依赖。
- 共享类型集中导出,避免多处重复定义。
- namespace 主要用于声明文件组织,业务代码优先 ES 模块。
原理流程
- 识别类型使用范围:模块内、跨模块、全局。
- 模块内类型放就近文件并导出。
- 公共类型汇总到共享类型入口统一导出。
代码 / 示例
src/
users/
types.ts # 模块内类型
shared/
types/ # 跨模块公共类型
api.ts
常见误区
- 误区:所有类型都放一个全局 d.ts;正解:就近内聚,仅全局/环境声明放 d.ts。
- 误区:namespace 可替代 ES 模块;正解:namespace 是 TS 早期组织方式,现代工程优先 import/export。
追问
- Q:循环引用类型依赖如何避免? A:调整类型归属方向,公共抽取到第三处,打破模块环。
- Q:类型文件需要运行时导出吗? A:纯类型用
export type,避免被当作运行时值打包。
03.3.1.5-015 高频类型报错分别是什么原因?
一句话结论
常见报错:类型不兼容(来源无法赋值给目标)、属性不存在(键不在类型上)、参数数量/类型不符、隐式 this(未标注 this 被推断为 any)、找不到模块(缺类型包或声明)。
概念解释
- 赋值兼容按结构可赋值性判断。
- 属性不存在多为类型过宽或字段名拼写错误。
- 函数参数不匹配检查参数数量与类型方向。
原理流程
- 定位报错指向的类型位置。
- 对照来源与目标类型结构差异。
- 收窄类型、补声明或修正字段名后消除报错。
代码 / 示例
interface User { name: string }
const u: User = { name: 1 }; // 类型不兼容:number 不能赋给 string
u.age = 1; // 属性不存在
function f(a: string): void {}
f(1); // 参数类型不符
常见误区
- 误区:报错就加
as压掉;正解:先判断是类型建模问题还是实现问题,断言只在确有把握时使用。 - 误区:属性不存在是运行时问题;正解:先检查类型定义是否遗漏该字段。
追问
- Q:找不到模块但代码能跑怎么办? A:缺类型声明,补
@types或本地 declare module。 - Q:
this隐式报错如何修复? A:在函数首个伪参数标注this: T,或调整调用绑定方式。
03.3.1.5-016 如何安全地扩展第三方库类型?
一句话结论
通过声明合并扩展全局对象接口,通过模块增强在已有模块上追加导出;扩展前确认官方类型是否已支持,避免本地声明与上游类型漂移冲突。
概念解释
- 全局接口(如 Window)同名合并追加字段。
- 模块增强在模块作用域内
declare module追加成员。 - 扩展内容应记录来源与撤销时机。
原理流程
- 阅读上游类型定义确定扩展点。
- 用声明合并或模块增强追加类型。
- 升级依赖后回归检查扩展是否仍需要。
代码 / 示例
// 全局接口合并
interface Window {
__INITIAL_STATE__: Record<string, unknown>;
}
常见误区
- 误区:本地扩展类型会随依赖自动更新;正解:上游改名或移除字段时本地声明可能过期,需升级后核对。
- 误区:给第三方模块加类型可以直接改 node_modules;正解:应在项目 d.ts 中声明,node_modules 不纳入版本管理。
追问
- Q:扩展类型与官方类型冲突时谁优先? A:按模块解析与声明合并规则,冲突需以官方为准并移除本地覆盖。
- Q:模块增强需要导入原模块吗? A:增强写法依赖模块系统上下文,具体形式按 TS 版本与模块类型确认。
03.3.1.5-017 代码中的 any 如何管理与收敛?
一句话结论
any 是类型系统逃逸舱:临时桥接处可有限使用,但应登记位置与替换计划,优先用 unknown + 守卫收窄,逐步消除历史 any。
概念解释
- any 关闭该位置全部检查,错误不会在编译期暴露。
- 第三方无类型边界、迁移过渡期是主要 any 来源。
- 可用 lint 规则限制 any 出现位置与注释豁免。
原理流程
- 扫描 any 出现位置并分类:边界桥接、历史遗留、缺失类型。
- 边界处先用 unknown 替代 any,配合守卫收窄。
- 缺失类型补声明或类型包,逐步清零。
代码 / 示例
// 临时:待补类型
/* eslint-disable @typescript-eslint/no-explicit-any */
const data: any = legacyClient.fetch();
// 收敛方向
const raw: unknown = legacyClient.fetch();
if (typeof raw === "object" && raw !== null) { /* 收窄 */ }
常见误区
- 误区:unknown 比 any 麻烦,直接用 any 更快;正解:unknown 强制边界判断,长期维护成本更低。
- 误区:函数参数 any 可以靠返回值推断补全;正解:参数 any 不会自动收窄,需显式标注或补类型。
追问
- Q:lint 如何限制 any? A:开启 no-explicit-any 规则,必要处用注释豁免并说明原因。
- Q:泛型能替代 any 封装吗? A:可复用场景用泛型保留类型信息,避免值与返回退化为 any。
03.3.1.5-018 版本相关的 TS 能力如何标注与验证?
一句话结论
对随 TS 版本演进的语法与选项(新内置工具类型、模块解析模式、类型推断行为),在文档中标注“待确认”并写明验证点:对照所用 TS 版本文档、在最小样例中编译观察结果,不凭记忆编造版本行为。
概念解释
- 类型体操与编译器行为跨版本可能有差异。
- 不确定时保留验证步骤,而非写死结论。
- 工程应记录 TS 版本,便于复现类型行为。
原理流程
- 识别依赖版本的语法/选项/推断规则。
- 用最小样例在当前版本编译验证。
- 文档标注待确认项与验证方式,升级版本后回归。
代码 / 示例
待确认:某内置字符串工具类型在当前 TS 版本是否可用
验证点:查看 typescript 版本号,对照官方 lib 文档,
写最小类型样例在编辑器悬停查看展开结果
常见误区
- 误区:记住的版本行为可以直接写进题库;正解:版本相关结论必须标注验证点,避免过期信息误导。
- 误区:示例代码在一个版本能跑就通用;正解:类型推断与报错提示可能随版本变化,需记录环境版本。
追问
- Q:如何在项目里固定 TS 版本? A:package.json 锁定 typescript 版本,CI 按 lock 文件安装。
- Q:发现版本行为与文档描述不符怎么办? A:以最小样例实测结果为准,记录差异并核对版本号与配置选项。