工程化

1$ npm view typescript version
27.0.2

1$ npx ts-node@10 run.ts
2TypeError: Cannot read properties of undefined (reading 'fileExists')
3    at readConfig (.../ts-node/dist/configuration.js:91:33)

1npx tsc --init

 1{
 2  "compilerOptions": {
 3    "module": "nodenext",
 4    "target": "esnext",
 5    "types": [],
 6    "sourceMap": true,
 7    "declaration": true,
 8    "declarationMap": true,
 9    "noUncheckedIndexedAccess": true,
10    "exactOptionalPropertyTypes": true,
11    "strict": true,
12    "jsx": "react-jsx",
13    "verbatimModuleSyntax": true,
14    "isolatedModules": true,
15    "noUncheckedSideEffectImports": true,
16    "moduleDetection": "force",
17    "skipLibCheck": true
18  }
19}

1{
2  "include": ["content/typescript/src/**/*.ts"],
3  "exclude": ["node_modules", "**/*.test.ts"]
4}

1const unused = 1;                  // TS6133（需要 noUnusedLocals）
2function f(x) { return x; }        // TS7006（strict 已覆盖）
3const s: string = arr[0];          // TS2322（需要 noUncheckedIndexedAccess）
4switch (n) { case 1: console.log(); case 2: return; }  // TS7029（需要 noFallthroughCasesInSwitch）

1$ npx tsc -p .
2$ ls dist/
3index.d.ts  index.js  index.js.map
4$ cat dist/index.d.ts
5export declare function add(a: number, b: number): number;

1import { SomeType } from "./other";
2// error TS1484: 'SomeType' is a type and must be imported using a type-only
3// import when 'verbatimModuleSyntax' is enabled.
4
5import type { SomeType } from "./other";   // 正确写法

1# 一个终端持续类型检查
2npx tsc --noEmit --watch
3
4# 另一个终端直接跑（Node 原生，零依赖）
5node --watch src/index.ts

 1// 这些语法 Node 原生 type stripping 无法执行，
 2// 每个都会报 ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX。
 3//
 4// 用注释形式列出，避免这个文件本身跑不起来。
 5
 6// 1. enum（非 const）
 7//    enum E { A, B }
 8//    error: TypeScript enum is not supported in strip-only mode
 9
10// 2. const enum
11//    const enum E { A = 1 }
12
13// 3. namespace（带成员）
14//    namespace N { export const a = 1 }
15
16// 4. 构造函数参数属性
17//    class C { constructor(public x: number) {} }
18
19// 5. 装饰器（连解析都失败）
20//    class C { @d m() {} }
21//    error: SyntaxError: Invalid or unexpected token
22
23// 6. import x = require("...")
24//    import fs = require("fs")
25
26// 可擦除的（Node 原生能跑）：
27// - 类型注解、interface、type
28// - 泛型参数与泛型调用
29// - 类型断言 as
30// - implements / declare
31// - import type / export type
32// - 可选参数、readonly、可见性修饰符（不带参数属性）
33
34// 这个文件本身是可擦除的，能跑
35const note = "见文件注释里的不可擦除语法列表";
36console.log(note);

1见文件注释里的不可擦除语法列表

 1// 纯可擦除语法：Node 原生可以直接运行
 2//   node content/typescript/src/engineering/erasable.ts
 3
 4interface User {
 5  name: string;
 6  age: number;
 7}
 8
 9type ID = string | number;
10
11type Mapper<T> = (item: T) => string;
12
13class Greeter {
14  // 注意：这里不能用参数属性（constructor(public name: string)），那是不可擦除的
15  name: string;
16  constructor(name: string) {
17    this.name = name;
18  }
19  greet(): string {
20    return `hi ${this.name}`;
21  }
22}
23
24const u: User = { name: "rainboy", age: 18 };
25const id: ID = 1;
26const mapper: Mapper<User> = (x) => x.name;
27
28// 类型断言、泛型调用都是可擦除的
29const asUser = u as User;
30const list: Array<number> = [1, 2, 3];
31
32console.log(new Greeter(u.name).greet(), mapper(asUser), id, list.length);

1hi rainboy rainboy 1 3

1$ npx tsx src/index.ts

1npx tsc          # 按 tsconfig 输出到 outDir
2node dist/index.js

1npx tsc --noEmit && npx esbuild src/index.ts --bundle --outfile=dist/index.js

 1{
 2  "version": "0.2.0",
 3  "configurations": [
 4    {
 5      "type": "node",
 6      "request": "launch",
 7      "name": "Debug TS (Node native)",
 8      "program": "${file}",
 9      "runtimeArgs": ["--experimental-strip-types"],
10      "console": "integratedTerminal",
11      "skipFiles": ["<node_internals>/**"]
12    }
13  ]
14}

1{
2  "compilerOptions": {
3    "sourceMap": true,
4    "inlineSources": true
5  }
6}

 1// 环境声明文件：只有类型，没有实现
 2// 这类文件不需要 import/export，是"全局脚本"文件
 3
 4// 1. 声明一个全局常量（运行时由构建工具注入）
 5declare const __APP_VERSION__: string;
 6
 7// 2. 声明一个全局函数
 8declare function parseAmount(text: string): number;
 9
10// 3. 给不存在的模块补类型
11declare module "virtual-lib" {
12  export function helper(): string;
13}
14
15// 4. 声明一个通配模块（用于 import "./style.css" 这类）
16declare module "*.css" {
17  const classes: Record<string, string>;
18  export default classes;
19}

 1// .d.ts 与 declare：只提供类型，不提供运行时实现
 2//
 3// 这个文件演示的是"类型层面成立、运行时不存在"的情况，
 4// 所以它不能直接运行（会报 Cannot find module 'virtual-lib'）。
 5// 它的作用是让 tsc --noEmit 验证 ambient.d.ts 里的声明是有效的。
 6
 7// 1. 全局常量（运行时由构建工具注入，如 vite 的 define）
 8const v: string = __APP_VERSION__;
 9
10// 2. 全局函数（运行时由某个 script 标签提供）
11const n: number = parseAmount("1,234");
12
13// 3. 声明过的模块（运行时需要真实存在这个包）
14import { helper } from "virtual-lib";
15
16// 4. 通配模块：import "./style.css" 能通过类型检查
17import classes from "./style.css";
18
19// 5. 全局接口扩展：给 Array 加方法
20const arr: number[] = [1, 2, 3];
21const last: number | undefined = arr.last();
22
23// 关键：以上全部只保证类型正确。
24// 如果运行时的对应实现不存在，代码会在运行时报错。
25// 这正是"类型擦除"的直接后果 —— 见 type-erasure.md
26
27export const demo = { v, n, helper, classes, last };

 1// 1. 全局常量
 2declare const __APP_VERSION__: string;
 3
 4// 2. 全局函数
 5declare function parseAmount(text: string): number;
 6
 7// 3. 模块声明
 8declare module "virtual-lib" {
 9  export function helper(): string;
10}
11
12// 4. 通配模块
13declare module "*.css" {
14  const classes: Record<string, string>;
15  export default classes;
16}
17
18// 5. 扩展全局接口（必须写在模块文件里）
19export {};
20declare global {
21  interface Array<T> { last(): T | undefined }
22}

1npm view @types/jquery version

1npm install --save-dev @types/jquery

1// types/my-lib.d.ts
2declare module "my-lib" {
3  export function run(config: { debug?: boolean }): void;
4}

1{ "skipLibCheck": true }

1{
2  "compilerOptions": {
3    "allowJs": true,
4    "checkJs": false,
5    "noEmit": true,
6    "strict": false
7  }
8}

1{
2  "compilerOptions": {
3    "strict": true,
4    "noImplicitAny": true,
5    "strictNullChecks": true
6  }
7}

1// eslint
2{ "rules": { "@typescript-eslint/no-explicit-any": "warn" } }

1// JS 里这样写没问题
2const obj = {
3  count: 0,
4  inc() { this.count++; }
5};

1// 老代码
2const fs = require("fs");
3module.exports = { run };
4
5// TS 里
6import fs from "fs";           // 需要 esModuleInterop
7export { run };

1class C {
2  field = 1;
3}

1class Base {
2  set value(v: number) { void v; }
3}
4class Derived extends Base {
5  value = 1;    // 用 defineProperty 定义，不走父类的 setter
6}

1error TS2610: 'value' is defined as an accessor in class 'Base', but is overridden
2here in 'Derived' as an instance property.

 1{
 2  "compilerOptions": {
 3    "target": "esnext",
 4    "module": "nodenext",
 5    "moduleResolution": "nodenext",
 6    "lib": ["esnext"],
 7    "strict": true,
 8    "types": ["node"],
 9    "noEmit": true,
10    "skipLibCheck": true,
11    "forceConsistentCasingInFileNames": true
12  },
13  "include": ["content/typescript/src/**/*.ts"]
14}

 1{
 2  "scripts": {
 3    "check": "tsc --noEmit"
 4  },
 5  "devDependencies": {
 6    "typescript": "^7.0.2",
 7    "tsx": "^4.23.15",
 8    "@types/node": "^26.6.2"
 9  }
10}