tsconfig.json配置指南

tsconfig.json 是 TypeScript 项目的配置文件，用于指定编译项目所需的根文件和编译器选项。当你运行 TypeScript 编译器（如 `tsc`）时，它会自动查找并读取当前目录下的 `tsconfig.json` 文件，从而应用其中的配置。

在 VSCode 中，`tsconfig.json` 文件会自动被读取和解析 

VSCode 会自动读取项目中的 `tsconfig.json` 文件，并根据其中的配置提供以下功能：

• 智能提示：根据类型信息提供代码补全和建议。
• 类型检查：检测代码中的类型错误并在编辑器中高亮显示。
• 重构支持：提供重命名、提取方法等重构功能。
• 错误提示：即时反馈代码中的语法和类型错误。

要确保 tsconfig.json 在VSCode正常工作，VSCode 需要使用项目内 node_modules 中的 TypeScript，而不是全局或内置版本：

npm install typescript@4.9.5 --save-dev

通过命令面板 (`Ctrl + Shift + P` 或 `Cmd + Shift + P`)，输入并选择 “TypeScript: Select TypeScript Version”，然后选择 “Use Workspace Version”。

也可以在设置中手动配置：

"typescript.tsdk": "./node_modules/typescript/lib"

这个路径指向本地 typescript 的 lib 目录，VSCode 会从此加载语言服务。

完成上面的配置之后，VSCode 会在右下角显示当前使用的 TypeScript 版本，点击也可快速切换。

在修改 tsconfig.json 后，可以使用命令面板（Ctrl + Shift + P）输入 "TypeScript: Restart TS Server" 来强制重新加载 TypeScript 服务器，以应用任何更改。

生成 tsconfig.json 

可以通过以下命令生成默认的 tsconfig.json 文件：

tsc --init

该命令会在项目根目录下生成一个带有大量注释的 tsconfig.json 文件，其中包含了所有可用的编译器选项及其默认值。

{
  "compilerOptions": {
    /* 基础设置 */
    "target": "ES2023", // ESNext
    "module": "ESNext", // ESNext
    "lib": ["ES2023", "DOM", "DOM.Iterable"], // ES2023, DOM, DOM.Iterable
    "skipLibCheck": true,
    
    /* 模块解析 */
    "moduleResolution": "bundler", // 模块解析策略
    "allowImportingTsExtensions": true,  // 允许导入 .ts 扩展名
    "verbatimModuleSyntax": true, // 严格遵循模块语法
    "moduleDetection": "force", // 强制模块检测
    "noEmit": true, // 不生成输出文件
    
    /* 路径映射 */
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },
    
    /* 类型检查 */
    "strict": false, // 严格模式
    "noUnusedLocals": false, // 不允许未使用的局部变量
    "noUnusedParameters": false, // 不允许未使用的参数
    "noFallthroughCasesInSwitch": false, // 不允许 switch 语句的默认分支掉落
    "noUncheckedSideEffectImports": false, // 不允许未检查的副作用导入
    "erasableSyntaxOnly": false, // 允许使用可擦除的语法

    /* 兼容性 */
    "esModuleInterop": true, // 允许从没有设置默认导出的模块中默认导入。这并不影响代码的显示，仅为了兼容性。
    "allowSyntheticDefaultImports": true, // 允许从没有设置默认导出的模块中默认导入。这并不影响代码的显示，仅为了兼容性。
    "forceConsistentCasingInFileNames": true, // 禁止对同一个文件的不一致的引用。
    "resolveJsonModule": true // 允许使用 .json 扩展名导入模块。
  },
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "exclude": ["node_modules", "dist"]
}

常用配置示例

基础配置示例

{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

React项目配置示例

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "lib": ["DOM", "ESNext"],
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Node.js项目配置示例

{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "lib": ["ESNext"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "sourceMap": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

配置继承与分层

借助extends属性，能够继承已有的配置文件，这样有利于在多个项目间共享配置。

首先，创建一个基础配置文件，例如 tsconfig.json：

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

在子项目中使用 extends属性指向基础配置文件：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",  // 覆盖或添加新的编译选项
    "module": "esnext"   // 修改模块系统
  }
}

使用 extends 属性可以极大地提高项目间配置的一致性和可维护性。

如何设置路径别名

以下是如何在 `tsconfig.json`、Vite 和 Webpack 中设置路径别名的示例：

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

vite.config.js

import { defineConfig } from 'vite';
import { resolve } from 'path';
export default defineConfig({
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
    },
  },
});

webpack.config.js

const path = require('path');
module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
};

这样配置后，你就可以在代码中使用 `@/` 来引用 `src` 目录下的文件。