编译配置详解

编译配置详解

TypeScript的编译配置主要通过tsconfig.json文件实现，这个文件定义了编译器如何将TypeScript代码转换为JavaScript。理解这些配置项对于项目构建和代码优化至关重要。

tsconfig.json基础结构

tsconfig.json通常位于项目根目录，基本结构如下：

{
  "compilerOptions": {
    // 编译器选项
  },
  "include": [
    // 包含的文件
  ],
  "exclude": [
    // 排除的文件
  ]
}

核心编译器选项

target与module

target指定编译后的JavaScript版本，module定义模块系统：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS"
  }
}

常见target值：

• ES3/ES5/ES6(ES2015)/ES2020
• ESNext（最新特性）

常见module值：

• CommonJS（Node.js）
• ES2015/ES2020（现代浏览器）
• UMD/AMD（浏览器和Node.js兼容）

strict系列选项

严格类型检查相关配置：

{
  "compilerOptions": {
    "strict": true,  // 开启所有严格检查
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true
  }
}

路径与模块解析

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    },
    "moduleResolution": "node"
  }
}

高级编译配置

类型检查相关

{
  "compilerOptions": {
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

源码映射

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true,
    "declaration": true,
    "declarationMap": true
  }
}

实验性特性

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "useDefineForClassFields": true
  }
}

文件包含与排除

{
  "include": [
    "src/**/*",
    "tests/**/*"
  ],
  "exclude": [
    "node_modules",
    "**/*.spec.ts"
  ]
}

工程引用

大型项目可以使用项目引用：

{
  "references": [
    { "path": "../core" },
    { "path": "../utils" }
  ]
}

自定义转换器

通过编程方式使用自定义转换器：

import * as ts from 'typescript';

function createTransformer(): ts.TransformerFactory<ts.SourceFile> {
  return context => {
    return sourceFile => {
      // 转换逻辑
      return sourceFile;
    };
  };
}

const program = ts.createProgram([...], {
  transformers: {
    before: [createTransformer()]
  }
});

多环境配置

针对不同环境使用不同配置：

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true
  }
}

// tsconfig.node.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "module": "CommonJS"
  }
}

// tsconfig.web.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "lib": ["DOM", "ES2020"]
  }
}

性能优化选项

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./build/.tsbuildinfo",
    "composite": true
  }
}

编译器插件

通过插件扩展编译器功能：

{
  "compilerOptions": {
    "plugins": [
      { "transform": "ts-transformer-keys/transformer" },
      { "transform": "ts-nameof", "type": "raw" }
    ]
  }
}

常见配置组合示例

Node.js项目配置

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

浏览器项目配置

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "ESNext",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "jsx": "react-jsx",
    "strict": true,
    "moduleResolution": "node",
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    },
    "allowJs": true,
    "noEmit": true
  }
}

编译器API集成

通过编程方式使用TypeScript编译器：

import * as ts from 'typescript';

const program = ts.createProgram(['file.ts'], {
  target: ts.ScriptTarget.ES5,
  module: ts.ModuleKind.CommonJS
});

const emitResult = program.emit();

const allDiagnostics = ts
  .getPreEmitDiagnostics(program)
  .concat(emitResult.diagnostics);

allDiagnostics.forEach(diagnostic => {
  if (diagnostic.file) {
    const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(
      diagnostic.start!
    );
    const message = ts.flattenDiagnosticMessageText(
      diagnostic.messageText,
      '\n'
    );
    console.log(
      `${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`
    );
  } else {
    console.log(
      ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')
    );
  }
});

配置调试

使用--showConfig查看最终配置：

tsc --showConfig

配置继承与覆盖

// tsconfig.base.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true
  }
}

// tsconfig.extend.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "noImplicitAny": false  // 覆盖基础配置
  }
}

语言服务配置

影响编辑器体验的配置：

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxFactory": "h",
    "jsxFragmentFactory": "Fragment"
  }
}

输出控制

{
  "compilerOptions": {
    "listFiles": true,
    "listEmittedFiles": true,
    "traceResolution": true,
    "diagnostics": true
  }
}

多线程编译

{
  "compilerOptions": {
    "incremental": true,
    "composite": true
  }
}

自定义类型定义

{
  "compilerOptions": {
    "typeRoots": ["./typings", "./node_modules/@types"],
    "types": ["node", "lodash"]
  }
}