项目tsconfig.json配置

项目tsconfig.json配置

认识tsconfig.json

TypeScript 配置文件（tsconfig.json）是用于配置 TypeScript 项目的重要文件。允许开发者自定义 TypeScript 编译器的行为，指定编译选项、文件包含与排除规则、输出目录等。合理配置 tsconfig.json，我们可以根据项目需求进行灵活的 TypeScript 编译设置。

配置文件命名

配置文件名字tsconfig.json

vue帮我们默认生成了三个配置文件(tsconfig.json ,tsconfig.node.json ,tsconfig.app.json)

tsconfig.json    // 主文件

tsconfig.node.json   // Node.js 环境配置

tsconfig.app.json  //应用代码配置


tsconfig.node.json  专门用来配置vite.config.ts文件的编译规则
tsconfig.app.json   用来定义项目中其他文件的ts编译规则
后面两个文件最终会被引入到tsconfig.json中

tsconfig.json 介绍

TypeScript 的主配置文件，用于控制项目中全局的 TypeScript 编译选项

tsconfig.node.json介绍

tsconfig.app.json介绍

@路径别名

🍎配置tsconfig.json

项目运行的时候提示我一个信息

找不到模块"e/store/modules/user"或其相应的类型声明。

但是实际上我是有这个文件的 ，这里其实是需要我们去tsconfig.json文件下进行配置

出现找不到模块的错误通常是由 TypeScript 编译器无法正确解析这些别名导致的,接下来就在我们的 TypeScript 配置文件 tsconfig.json 中配置路径别名

在 compilerOptions 下的 paths 中添加别名的映射：

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

配置后，TypeScript 将能够正确地解析 @/stores/xxx 到 src/stores/xxx

🍎vite.config.ts 配置处理path

接下来我们还要配置 Vite 构建工具的路径别名

使用commonjs语法

import path from 'path'
defineConfig({
  resolve: {
    alias: {
        '@': path.resolve(__dirname, 'src')
      }
  },
})

使用esmodule模块语法import.meta.url(现代写法-采用)

旧的配置提示我们

Cannot find name '__dirname'.
13 '@': path.resolve(__dirname, 'src')

旧的配置如下,__dirname 只在 CommonJS 中可用,我们使用的是ES 模块（"type": "module"）

__dirname 只在 CommonJS 中可用

使用import.meta.url

import { fileURLToPath, URL } from 'node:url'
resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },

同时需要注意添加我们的语法类型插件

yarn add @types/node

使用process.cwd()

resolve: {
  alias: {
    '@': path.resolve(process.cwd(), 'src')
  }
}

使用 __dirname 兼容写法

import * as path from 'path'
 
// 兼容 ES 模块的 __dirname
const __dirname = path.dirname(fileURLToPath(import.meta.url))

resolve: {
  alias: {
    '@': path.resolve(__dirname, 'src')
  }
},

使用相对路径（最简单）

resolve: {
  alias: {
    '@': path.resolve('./src')
  }
},

这种方法的缺陷就是

CI/CD 环境问题，在持续集成环境中，工作目录可能不确定，会导致构建失败

关于Eslint警告的处理

方法1单独处理Eslint

在代码中添加注释来禁用规则

// 屏蔽警告的代码行的上方添加如下注释：

// eslint-disable-next-line comma-dangle
这将在下一行代码上禁用comma-dangle规则。

方法2 eslint 注释块

使用/* eslint-disable _/和/_ eslint-enable */注释块

如果你希望在一个代码块中禁用警告，你可以使用/* eslint-disable _/和/_ eslint-enable */注释块包裹该代码块：

/* eslint-disable comma-dangle */  
// 这里是你希望禁用警告的代码块  
/* eslint-enable comma-dangle */

这样做将只在指定的代码块中禁用comma-dangle规则。

请注意，禁用警告应谨慎使用，因为警告通常是用来指出潜在问题的。确保你理解为什么收到这个警告，并确认禁用它是合适的选择。

方法3 关闭ESLint检测（建议）

在整个项目中禁用该规则，可以在ESLint的配置文件（如.eslintrc.js）中进行设置。找到rules部分，然后添加或修改comma-dangle规则的设置

将'comma-dangle'设置为'off'将禁用该规则

module.exports = {  
  // ...  
  rules: {  
    // ...  
    'comma-dangle': 'off',  
    // ...  
  },  
  // ...  
};

严格类型检查选项（关闭）

在 tsconfig.json 配置文件中，修改以下配置：

strict意思就是是否启用所有严格类型检查选项，这里我们直接选择否即可

"strict": false, // 启用所有严格类型检查选项

未使用函数或变量配置（vscode取消未使用变量的提示（爆红））

目前项目正在使用ts（TypeScript），可以在 tsconfig.json 文件中调整编译选项

在你的项目中找到并打开 tsconfig.json 文件，将noUnusedLocals和noUnusedParameters设置为false，关闭vscode重新打开项目即可

{
  "compilerOptions": {
    // 其他编译选项
    "noUnusedLocals": false,
    "noUnusedParameters": false
  }
}

未使用TSl类型警告

去除VScode之中的Eslint警告，可以按照以下步骤操作

设置=>工作区设置=>搜索Eslint

然后我们可以看到以下部分的配置

我们看看相关的详细配置

"eslint.enable"：设置是否启用ESLint代码检查工具。如果要禁用ESLint的检查功能，将其设置为false。

属性参考

{
  "compilerOptions": {
    /* Basic Options */
    "target": "es5" 
    /* target用于指定编译之后的版本目标: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019' or 'ESNEXT'. */,
    "module": "commonjs" 
    /* 用来指定要使用的模块标准: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */,
    "lib": ["es6", "dom"],
    /* lib用于指定要包含在编译中的库文件 */
    "allowJs": true,                       
    /* allowJs设置的值为true或false，用来指定是否允许编译js文件，默认是false，即不编译js文件 */
    "checkJs": true,                       /* checkJs的值为true或false，用来指定是否检查和报告js文件中的错误，默认是false */
    "jsx": "preserve",                     /* 指定jsx代码用于的开发环境: 'preserve', 'react-native', or 'react'. */
    "declaration": true,                   /* declaration的值为true或false，用来指定是否在编译的时候生成相应的".d.ts"声明文件。如果设为true，编译每个ts文件之后会生成一个js文件和一个声明文件。但是declaration和allowJs不能同时设为true */
    "declarationMap": true,                /* 值为true或false，指定是否为声明文件.d.ts生成map文件 */
    "sourceMap": true,                     /* sourceMap的值为true或false，用来指定编译时是否生成.map文件 */
    "outFile": "./",                       /* outFile用于指定将输出文件合并为一个文件，它的值为一个文件路径名。比如设置为"./dist/main.js"，则输出的文件为一个main.js文件。但是要注意，只有设置module的值为amd和system模块时才支持这个配置 */
    "outDir": "./",                        /* outDir用来指定输出文件夹，值为一个文件夹路径字符串，输出的文件都将放置在这个文件夹 */
    "rootDir": "./",                       /* 用来指定编译文件的根目录，编译器会在根目录查找入口文件，如果编译器发现以rootDir的值作为根目录查找入口文件并不会把所有文件加载进去的话会报错，但是不会停止编译 */
    "composite": true,                     /* 是否编译构建引用项目  */
    "incremental": true,                   /* 是否启用增量编译*/
    "tsBuildInfoFile": "./",               /* 指定文件用来存储增量编译信息 */
    "removeComments": true,                /* removeComments的值为true或false，用于指定是否将编译后的文件中的注释删掉，设为true的话即删掉注释，默认为false */
    "noEmit": true,                        /* 不生成编译文件，这个一般比较少用 */
    "importHelpers": true,                 /* importHelpers的值为true或false，指定是否引入tslib里的辅助工具函数，默认为false */
    "downlevelIteration": true,            /* 当target为'ES5' or 'ES3'时，为'for-of', spread, and destructuring'中的迭代器提供完全支持 */
    "isolatedModules": true,               /* isolatedModules的值为true或false，指定是否将每个文件作为单独的模块，默认为true，它不可以和declaration同时设定 */
    /* Strict Type-Checking Options */
    "strict": true /* strict的值为true或false，用于指定是否启动所有类型检查，如果设为true则会同时开启下面这几个严格类型检查，默认为false */,
    "noImplicitAny": true,                 /* noImplicitAny的值为true或false，如果我们没有为一些值设置明确的类型，编译器会默认认为这个值为any，如果noImplicitAny的值为true的话。则没有明确的类型会报错。默认值为false */
    "strictNullChecks": true,              /* strictNullChecks为true时，null和undefined值不能赋给非这两种类型的值，别的类型也不能赋给他们，除了any类型。还有个例外就是undefined可以赋值给void类型 */
    "strictFunctionTypes": true,           /* strictFunctionTypes的值为true或false，用于指定是否使用函数参数双向协变检查 */
    "strictBindCallApply": true,           /* 设为true后会对bind、call和apply绑定的方法的参数的检测是严格检测的 */
    "strictPropertyInitialization": true,  /* 设为true后会检查类的非undefined属性是否已经在构造函数里初始化，如果要开启这项，需要同时开启strictNullChecks，默认为false */
   "noImplicitThis": true,                /* 当this表达式的值为any类型的时候，生成一个错误 */
    "alwaysStrict": true,                  /* alwaysStrict的值为true或false，指定始终以严格模式检查每个模块，并且在编译之后的js文件中加入"use strict"字符串，用来告诉浏览器该js为严格模式 */
    /* Additional Checks */
    "noUnusedLocals": true,                /* 用于检查是否有定义了但是没有使用的变量，对于这一点的检测，使用eslint可以在你书写代码的时候做提示，你可以配合使用。它的默认值为false */
    "noUnusedParameters": true,            /* 用于检查是否有在函数体中没有使用的参数，这个也可以配合eslint来做检查，默认为false */
    "noImplicitReturns": true,             /* 用于检查函数是否有返回值，设为true后，如果函数没有返回值则会提示，默认为false */
    "noFallthroughCasesInSwitch": true,    /* 用于检查switch中是否有case没有使用break跳出switch，默认为false */
    /* Module Resolution Options */
    "moduleResolution": "node",            /* 用于选择模块解析策略，有'node'和'classic'两种类型' */
    "baseUrl": "./",                       /* baseUrl用于设置解析非相对模块名称的基本目录，相对模块不会受baseUrl的影响 */
    "paths": {},                           /* 用于设置模块名称到基于baseUrl的路径映射 */
    "rootDirs": [],                        /* rootDirs可以指定一个路径列表，在构建时编译器会将这个路径列表中的路径的内容都放到一个文件夹中 */
    "typeRoots": [],                       /* typeRoots用来指定声明文件或文件夹的路径列表，如果指定了此项，则只有在这里列出的声明文件才会被加载 */
    "types": [],                           /* types用来指定需要包含的模块，只有在这里列出的模块的声明文件才会被加载进来 */
    "allowSyntheticDefaultImports": true,  /* 用来指定允许从没有默认导出的模块中默认导入 */
    "esModuleInterop": true /* 通过为导入内容创建命名空间，实现CommonJS和ES模块之间的互操作性 */,
    "preserveSymlinks": true,              /* 不把符号链接解析为其真实路径，具体可以了解下webpack和nodejs的symlink相关知识 */
 
    /* Source Map Options */
    "sourceRoot": "",                      /* sourceRoot用于指定调试器应该找到TypeScript文件而不是源文件位置，这个值会被写进.map文件里 */
    "mapRoot": "",                         /* mapRoot用于指定调试器找到映射文件而非生成文件的位置，指定map文件的根路径，该选项会影响.map文件中的sources属性 */
    "inlineSourceMap": true,               /* 指定是否将map文件的内容和js文件编译在同一个js文件中，如果设为true，则map的内容会以//# sourceMappingURL=然后拼接base64字符串的形式插入在js文件底部 */
    "inlineSources": true,                 /* 用于指定是否进一步将.ts文件的内容也包含到输入文件中 */
 
    /* Experimental Options */
    "experimentalDecorators": true /* 用于指定是否启用实验性的装饰器特性 */
    "emitDecoratorMetadata": true,         /* 用于指定是否为装饰器提供元数据支持，关于元数据，也是ES6的新标准，可以通过Reflect提供的静态方法获取元数据，如果需要使用Reflect的一些方法，需要引入ES2015.Reflect这个库 */
  }
  "files": [], // files可以配置一个数组列表，里面包含指定文件的相对或绝对路径，编译器在编译的时候只会编译包含在files中列出的文件，如果不指定，则取决于有没有设置include选项，如果没有include选项，则默认会编译根目录以及所有子目录中的文件。这里列出的路径必须是指定文件，而不是某个文件夹，而且不能使用* ? **/ 等通配符
  "include": [],  // include也可以指定要编译的路径列表，但是和files的区别在于，这里的路径可以是文件夹，也可以是文件，可以使用相对和绝对路径，而且可以使用通配符，比如"./src"即表示要编译src文件夹下的所有文件以及子文件夹的文件
  "exclude": [],  // exclude表示要排除的、不编译的文件，它也可以指定一个列表，规则和include一样，可以是文件或文件夹，可以是相对路径或绝对路径，可以使用通配符
  "extends": "",   // extends可以通过指定一个其他的tsconfig.json文件路径，来继承这个配置文件里的配置，继承来的文件的配置会覆盖当前文件定义的配置。TS在3.2版本开始，支持继承一个来自Node.js包的tsconfig.json配置文件
  "compileOnSave": true,  // compileOnSave的值是true或false，如果设为true，在我们编辑了项目中的文件保存的时候，编辑器会根据tsconfig.json中的配置重新生成文件，不过这个要编辑器支持
  "references": [],  // 一个对象数组，指定要引用的项目
}

完整配置

Node版本（v22.16.0 更新于 2025-07 ）

🍎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"]
}

🍎tsconfig.node.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
    "composite": true, // 启用复合项目
    "lib": ["ES2023"], // ["ESNext"],
  },
  "include": ["vite.config.ts"],
}

🍎tsconfig.app.json

{
  // "extends": "@vue/tsconfig/tsconfig.dom.json",
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "composite": true, // 启用复合项目
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}