The Concise TypeScript Book：TypeScript 入门实战指南——安装、tsconfig.json 配置与渐进式迁移

• 文档
• 教程

本文是开源项目 The Concise TypeScript Book（仓库根目录下多语言版本文档）中「Getting Started With TypeScript」章节的中文技术指南，围绕 TypeScript 编译器的安装方式、tsc命令行用法、tsconfig.json核心配置项以及大型项目渐进式迁移策略展开。读完本文，你将掌握一套可立即复用的 TypeScript 项目初始化与配置流程，并能参考仓库内真实运行的tsconfig.json与编译脚本，理解每个配置项在实际工程中的落地效果。

安装 TypeScript 编译器

Visual Studio Code 为 TypeScript 提供了出色的语言支持（包括智能补全、跳转定义、重构等），但它并不内置 TypeScript 编译器。要获得编译能力，需要借助包管理器（如 npm 或 yarn）显式安装。

使用 npm 安装到当前项目（推荐）：

npm install typescript --save-dev

使用 yarn 安装：

yarn add typescript --dev

务必提交生成的 lockfile（如package-lock.json或yarn.lock），这样才能保证团队每个成员使用完全相同的 TypeScript 版本，避免“本地能编译、CI 报错”的版本漂移问题。

安装完成后，运行编译器的方式同样与包管理器对应：

npx tsc

或：

yarn tsc

按项目安装 vs 全局安装

官方建议按项目安装 TypeScript 而非全局安装，因为：

• 每个项目可以锁定自己需要的 TypeScript 版本，互不干扰；
• 构建过程更可预测，CI/CD 环境无需依赖开发者机器上的全局环境。

对于偶尔的一次性使用（例如临时编译一个脚本），可以直接用npx tsc调用（npx 会自动查找并使用项目本地安装的 tsc）；也可以全局安装：

npm install -g typescript

其他环境的安装方式

如果使用 Microsoft Visual Studio（非 VS Code），可以通过 NuGet 以 MSBuild 项目包的形式获取 TypeScript。在 NuGet 包管理器控制台（Package Manager Console）中执行：

Install-Package Microsoft.TypeScript.MSBuild

安装产物：tsc 与 tsserver

安装 TypeScript 后，会得到两个可执行文件：

• tsc：TypeScript 编译器，负责把.ts/.tsx源码编译为 JavaScript；
• tsserver：TypeScript 独立服务器（standalone server），内含编译器与语言服务（Language Service），编辑器与 IDE 正是通过它实现智能代码补全、悬停提示、诊断报错等特性。

此外，还有一批与 TypeScript 兼容的转译器（transpiler），例如通过插件使用Babel或使用swc。它们可以把 TypeScript 代码转换为其他目标语言或目标版本，适用于不依赖完整类型检查的快速编译场景。

TypeScript 7.0：Go 原生实现的性能特性

值得关注的是，TypeScript 7.0 已用Go重写，是编译器和语言服务的原生实现。它利用共享内存多线程及其他优化手段，显著加快完整构建（full build）与编辑器功能的响应速度，从而缩短开发期间的反馈时间。

TypeScript 7.0 的部分性能特性可以按需调优：

• --checkers：允许类型检查在并行 worker 中运行；worker 数量越多，大型项目编译越快，但内存占用也更高；
• --watch：重建后的 watch 模式改进了跨平台的文件监听（file watching）能力。

注意一个兼容性事实：截至 2026 年 7 月，TypeScript 7.0尚未提供编译器 API（compiler API）。因此，仍依赖 TypeScript 6.0 API 的工具可以通过@typescript/typescript6或 npm 别名（npm aliases）与 TypeScript 7.0并行运行，实现平滑过渡。

配置 TypeScript：CLI 选项与 tsconfig.json

TypeScript 的配置有两条路径：

1. tsc的 CLI 选项：适合临时性、一次性编译；
2. tsconfig.json配置文件：放在项目根目录，是正式工程的推荐方式。

生成推荐配置

执行下面的命令，会生成一份预填了推荐设置的tsconfig.json：

tsc --init

之后在项目本地执行tsc时，TypeScript 会自动向上查找最近的tsconfig.json，并按照其中的配置编译整个项目。

tsc 命令行示例

以下命令使用默认设置运行，覆盖了几种常见场景：

tsc main.ts // 将特定文件 main.ts 编译为 JavaScript tsc src/*.ts // 将 src 目录下所有 .ts 文件编译为 JavaScript tsc app.ts util.ts --outfile index.js // 将 app.ts 与 util.ts 编译合并为单个文件 index.js

tsconfig.json：TypeScript 的配置文件

tsconfig.json用于配置 TypeScript 编译器（tsc），通常与package.json一起放在项目根目录。

两条使用须知：

• tsconfig.json虽然是 JSON 格式，但允许包含注释（//与/* */），方便团队维护时补充说明；
• 建议优先使用配置文件而非命令行选项，这样配置可以随代码入库、统一管理。

完整的配置项文档与 JSON Schema 可在 TypeScript 官方 tsconfig 参考页面查阅（本文不再列出外部链接，直接介绍仓库实践中最常用、最有价值的配置项）。

target

target指定 TypeScript 代码要输出到哪个 ECMAScript 版本。对于现代浏览器，ES6是不错的选择。

注意版本演进：ES5 支持已在 TypeScript 6.0 中弃用，并在 TypeScript 7.0 中不再支持。如果你的配置中仍出现target: es5，在 7.0 中会直接报错。

lib

lib指定编译时要包含哪些标准库类型定义。TypeScript 会根据target自动包含对应功能的 API，但允许按需裁剪或补充。

典型场景：做服务端（Node.js）项目时，可以排除只在浏览器环境有意义的DOM库，避免引入不必要的全局类型。

strict

strict通过启用更严格的类型检查提升类型安全。从 TypeScript 6.0 开始默认开启；在更早版本中需要显式设置true。

启用strict后，TypeScript 会：

• 为每个源文件生成"use strict"指令；
• 在类型检查过程中考虑null与undefined（即开启严格空检查strictNullChecks）；
• 在没有类型注解时，禁止隐式使用any类型（即开启noImplicitAny）；
• 在this表达式的类型会隐式推断为any时报错。

module

module设置编译后代码使用的模块系统。运行时，模块加载器（module loader）会根据指定的模块系统来查找和执行依赖。

JavaScript 生态中最常见的模块加载器组合是：

• Node.js 的 CommonJS：面向服务端应用；
• RequireJS（AMD）：面向基于浏览器的 Web 应用。

TypeScript 可以为多种模块系统生成代码，包括 UMD、System、ESNext、ES2015/ES6 和 ES2020。模块系统的选择应基于目标运行环境及其可用的模块加载机制。

注意：旧版模块系统（AMD、UMD、SystemJS）的支持已在 TypeScript 6.0 中弃用，并在 TypeScript 7.0 中不再支持。

moduleResolution

moduleResolution指定模块解析策略：

• 现代 TypeScript 代码应使用nodenext或bundler；
• classic策略仅适用于 TypeScript 1.6 之前的远古版本，如今已无使用价值。

esModuleInterop

esModuleInterop允许从没有使用default导出的 CommonJS 模块中进行默认导入。它会在生成的 JavaScript 中注入 shim，保证互操作兼容。

启用后，可以这样写：

import MyLibrary from "my-library";

而无需写成：

import * as MyLibrary from "my-library";

背景说明：esModuleInterop最初是 opt-in 选项，以避免引入破坏性变更，但长期以来一直是社区推荐的默认配置。禁用它会导致使用 CommonJS 与 ESM 混用时出现不易察觉的运行时问题。从 TypeScript 6.0 开始，这种更安全的互操作行为始终启用。

6.0 弃用、7.0 硬错误清单

在 TypeScript 6.0 中，一批较老的配置选项与语法形式被标记弃用或经历了旧行为的过渡；到 TypeScript 7.0，它们变成了硬错误（hard errors）或无操作行为（no-op）。完整清单如下：

• target: es5
• downlevelIteration
• moduleResolution: node/node10
• module: amd/umd/systemjs/none
• baseUrl
• moduleResolution: classic
• 禁用esModuleInterop或allowSyntheticDefaultImports
• 禁用alwaysStrict
• 命名空间声明中的module关键字
• 导入上的asserts
• 在skipDefaultLibCheck下使用/// <reference no-default-lib />
• CLI 文件路径与本地tsconfig.json冲突时（除非使用--ignoreConfig）

如果你的项目还在使用这些配置，升级到 TypeScript 7.0 前应提前清理。

jsx

jsx仅适用于 ReactJS 中的.tsx文件，控制 JSX 构造如何被编译为 JavaScript。常用选项preserve会输出.jsx文件并保持 JSX 原样，便于交给 Babel 等工具做进一步转换。

skipLibCheck

skipLibCheck跳过对导入的第三方包整体类型定义的检查。这能显著减少项目编译时间；TypeScript 仍会用这些包提供的类型定义来检查你自己的代码。

files

files列出必须始终包含在编译程序中的文件，适用于文件数量少且明确的场景。

include

include指定希望包含的文件列表，支持 glob 模式：

• **：匹配任意子目录；
• *：匹配任意文件名；
• ?：匹配单个可选字符。

exclude

exclude指定不应参与编译的文件列表，典型如node_modules、测试文件等。

importHelpers：压缩输出体积

TypeScript 在为某些高级或降级（down-leveled）的 JavaScript 特性生成代码时，会注入辅助函数（helper）。默认情况下，这些 helper 会复制到每个使用它们的文件里，造成输出冗余。

启用importHelpers后，helper 改为从tslib模块统一导入，JavaScript 输出更加精简、高效。代价是运行时多了一个tslib依赖，因此该选项在输出体量大、重复多的项目中收益最明显。

迁移到 TypeScript 的实战建议

对于大型项目，官方建议采用渐进式过渡：让 TypeScript 与 JavaScript 代码先共存，再逐模块迁移。只有小型项目才适合一次性整体迁移。

第一步：把 TypeScript 引入构建链

使用allowJs编译选项，允许.ts/.tsx文件与既有 JavaScript 文件共存。

注意：TypeScript 无法从 JavaScript 文件推断类型时，变量会回退为any。因此在迁移初期，建议禁用noImplicitAny，避免海量报错阻塞迁移进度。

第二步：让测试与 TypeScript 并行工作

确保现有 JavaScript 测试与 TypeScript 文件能一起运行，这样可以在转换每个模块的同时持续回归测试。如果使用 Jest，可考虑ts-jest，它允许用 Jest 直接测试 TypeScript 项目。

第三步：补齐第三方库类型声明

为第三方库引入类型声明。声明可能由库本身内置（bundled），也可能托管在 DefinitelyTyped 社区。查找并安装的方式（DefinitelyTyped 的搜索入口见 TypeScript 官方站点）：

npm install --save-dev @types/package-name

或：

yarn add --dev @types/package-name

第四步：自底向上逐模块迁移

遵循依赖关系图（Dependency Graph），从叶子节点开始：优先转换不依赖其他模块的模块。可视化依赖图可以使用madge工具。

理想的首批迁移候选是：

• 工具函数（utility functions）；
• 与外部 API 或规范相关的代码。

这些模块可以从Swagger 契约、GraphQL Schema 或 JSON Schema自动生成 TypeScript 类型定义并纳入项目。当没有官方规范或 schema 时，也可以从服务器返回的原始 JSON 等数据生成类型；但从规范生成类型优于从数据生成，后者容易丢失边界情况（edge cases）。

迁移期间的原则：避免顺手重构代码，只专注为模块添加类型，减少迁移的变量。

第五步：启用 noImplicitAny

待类型基本补齐后，启用noImplicitAny，强制所有类型都是已知且明确定义的，从而获得完整的 TypeScript 类型检查体验。

辅助手段：@ts-check 与 JSDoc

迁移过程中，可以在 JavaScript 文件中使用@ts-check指令，为单个 JS 文件启用 TypeScript 类型检查。它提供了一种宽松版本的检查，可用来初步定位 JavaScript 文件中的问题。

当文件包含@ts-check时，TypeScript 会尝试通过JSDoc 风格的注释推断定义。不过，建议只在迁移的极早期阶段使用 JSDoc 注解，后期应转为正式的类型声明。

保留 noEmitOnError: false

建议让tsconfig.json中的noEmitOnError保持默认值false。这样即使编译报告了类型错误，也仍然输出 JavaScript 源码，保证迁移过程中构建产物不会中断、业务不阻塞。

仓库实践：这些配置在本项目中的真实落地

The Concise TypeScript Book 仓库本身就是上述配置与流程的最佳实践样本，可以在源码中直接找到佐证。

书籍工具链的 tsconfig.json

仓库的书籍生成工具目录下的 tools/tsconfig.json 是一份完整的、可直接对照学习的现代配置：

{ "compilerOptions": { "target": "es2022", "module": "commonjs", "noImplicitAny": true, "esModuleInterop": true, "noEmitOnError": true, "moduleDetection": "force", "noUnusedLocals": false, "forceConsistentCasingInFileNames": true, "strict": true, "skipLibCheck": true, "lib": ["es2022", "esnext.disposable", "esnext.decorators", "dom"] } }

对照上文可以观察到：strict: true、esModuleInterop: true、skipLibCheck: true正是文档推荐的现代组合；lib按需显式声明（服务端工具链依然保留了dom，因为部分工具会处理与浏览器相关的内容）；target: es2022也符合“面向现代运行时、放弃 ES5”的趋势。

网站构建链的配置继承

网站部分的 website/tsconfig.json 只写了一行：

{ "extends": "astro/tsconfigs/strict" }

它通过extends继承 Astro 提供的 strict 基线配置，体现了“集中维护配置、子项目继承”的工程实践。

编译脚本：strict 检查的实际应用

仓库的 tools/compile.ts 使用 TypeScript 编译器 API 对所有 Markdown 文档中的typescript代码块做真实编译校验，其运行参数与文档建议高度一致：

compileAndReport({ noEmitOnError: true, noImplicitAny: true, target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.CommonJS, moduleDetection: ts.ModuleDetectionKind.Force, noUnusedLocals: false, strict: true })

这意味着文档中的每个 TypeScript 示例都必须通过严格模式编译才能通过 tools/Makefile 中make check（对应 tools/package.json 的npm run check）的质量门禁。noImplicitAny与strict的启用，正是文档「第五步：启用 noImplicitAny」的落地实例。

此外，tools/lint.ts 配合 tools/config.ts 中定义的CODE_BLOCK_TS_REGEX，用 Prettier 对所有 Markdown 内 TypeScript 代码块做格式化检查；而 tools/README.md 详细记录了npm run format、npm run compile、npm run lint:md、npm run check等命令的用途——其中npm run compile即为上述编译校验流程的入口。

依赖版本

仓库两个子项目的 TypeScript 依赖版本也能印证“按项目锁定版本”的实践：tools/package.json 使用typescript ^5.4.5，website/package.json 使用typescript ^5.9.3，各子项目互不干扰、独立演进。

小结

从安装、tsc --init初始化、核心配置项逐项解析，到大型项目五步渐进式迁移路线，本文完整覆盖了 TypeScript 项目从零起步的完整链路。其中strict、esModuleInterop、skipLibCheck、moduleResolution: nodenext|bundler等现代组合已在本仓库的 tools/tsconfig.json 与编译脚本中得到真实验证；noEmitOnError: false、allowJs、@ts-check等迁移技巧则适合直接套用到你的存量 JavaScript 项目中。对照仓库源码阅读本指南，可以同时获得“文档的实操步骤”与“源码级的落地证据”双重收益。

• 文档
• 教程