被问tsconfig.json 和 tsconfig.node.json 有什么作用，我懵了……

背景

事情是这样的，前几天在项目例会上，领导随口问了我我一个看似简单的问题：

“我们项目里有tsconfig.json 和 tsconfig.node.json ，它们有什么作用？”

活久见，我从来没注意过这个细节，我内心无语，问这种问题对项目有什么用！但机智的我还是回答上来了：不都是typescript的配置文件么。

领导肯定了我的回答，又继续问，那为什么项目中有两个配置文件呢？我机智的说，我理解的不深，领导您讲讲吧，我学习一下。

tsconfig.json 是干嘛的？

说白了，tsconfig.json 就是 告诉 TypeScript：我要用哪些规则来“看懂”和“检查”我写的代码。

你可以把它想象成 TypeScript 的“眼镜”，没有它，TS 编译器就会“看不清楚”你的项目到底该怎么理解、怎么校验。

• 
  
• 影响代码能不能被正确编译
  

如果我们用了某些新语法（比如 optional chaining、import type），却没有在 tsconfig 里声明 "target": "ESNext"，那 TypeScript 就会报错：看不懂！

• 
  
• 影响编辑器的智能提示
  

如果我们用了路径别名 @/utils/index.ts，但没有配置：

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

    }

  }

}

那 VS Code 就会一直红线报错：“找不到模块”。

• 
  
• 影响类型检查的严格程度
  

比如 "strict": true 会让我们代码写得更规范，少写 any，避免“空值未处理”这类隐患；而关闭了就“宽松模式”，你可能一不小心就放过了 bug。

• 
  
• 影响团队代码规范一致性
  

当多个成员一起开发时，统一 tsconfig.json 能让大家都用一样的校验标准，避免“我这边没问题你那边报错”的尴尬。

tsconfig.json文件的一个典型配置如下：

{
"compilerOptions": {
// ECMAScript 的目标版本（决定生成的代码是 ES5 还是 ES6 等）
"target": "ESNext",

// 模块系统，这里用 ESNext 是为了支持 Vite 的现代打包机制
"module": "ESNext",

// 模块解析策略，Node 方式支持从 node_modules 中解析模块
"moduleResolution": "Node",

// 启用源映射，便于调试（ts -> js 映射）
"sourceMap": true,

// 启用 JSX 支持（如用于 Vue 的 TSX/JSX 语法）
"jsx": "preserve",

// 编译结果是否使用 ES 模块的导出语法（import/export）
"esModuleInterop": true,

// 允许默认导入非 ESModule 模块（兼容 CommonJS）
"allowSyntheticDefaultImports": true,

// 生成声明文件（一般用于库开发，可选）
"declaration": false,

// 设置项目根路径，配合 paths 使用
"baseUrl": ".",

// 路径别名配置，@ 代表 src 目录，方便引入模块
"paths": {
"@/*": ["src/*"]

    },

// 开启严格模式（类型检查更严格，建议开启）
"strict": true,

// 不检查未使用的局部变量
"noUnusedLocals": true,

// 不检查未使用的函数参数
"noUnusedParameters": true,

// 禁止隐式的 any 类型（没有类型声明时报错）
"noImplicitAny": true,

// 禁止将 this 用在不合法的位置
"noImplicitThis": true,

// 允许在 JS 文件中使用 TypeScript（一般不建议）
"allowJs": false,

// 允许编译 JS 文件（如需使用 legacy 代码可开启）
"checkJs": false,

// 指定输出目录（Vite 会忽略它，一般不用）
"outDir": "./dist",

// 开启增量编译（提升大型项目编译效率）
"incremental": true,

// 类型定义自动引入的库（默认会包含 dom、esnext 等）
"lib": ["ESNext", "DOM"]

  },
// 指定编译包含的文件（推荐指定为 src）
"include": ["src/**/*"],

// 排除 node_modules 和构建输出目录
"exclude": ["node_modules", "dist"]

}

Vite 项目中，一般 tsconfig.json 会被自动加载，所以只需要按需修改上述配置即可。

tsconfig.node.json 又是干嘛的？

tsconfig.node.json 并不是 TypeScript 官方强制的命名，而是一种 社区约定俗成 的分离配置方式。它用于配置运行在 Node.js 环境下的 TypeScript 代码，例如：

• 
  
• vite.config.ts（构建配置）
  
• scripts/*.ts（一些本地开发脚本）
  
• server/*.ts（如果你有 Node 后端）
  

tsconfig.node.json的一大作用就是针对业务代码和项目中的node代码做区分，划分职责。

如果不写tsconfig.node.json，会出现以下问题：

比如你写了一个脚本：scripts/generate-sitemap.ts，其中用到了 fs、path、url 等 Node 原生模块，但主 tsconfig.json 是为浏览器服务的：

• 
  
• 设置了 "module": "ESNext"，TypeScript 编译器可能不会生成符合 Node 环境要求的代码。
  
• 缺少 moduleResolution: "node" 会导致路径解析失败。
  

常见配置内容：

{
"compilerOptions": {
// 使用最新的 ECMAScript 特性
"target": "ESNext",

// 使用 CommonJS 模块系统，兼容 Node.js（也可根据项目设置为 ESNext）
"module": "CommonJS",

// 模块解析方式设置为 Node（支持 node_modules 和路径别名）
"moduleResolution": "Node",

// 启用严格模式，增加类型安全
"strict": true,

// 允许默认导入非 ESModule 的模块（如 import fs from 'fs'）
"esModuleInterop": true,

// 支持 import type 等语法
"allowSyntheticDefaultImports": true,

// 添加 Node.js 类型定义
"types": ["node"],

// 源码映射（可选）
"sourceMap": true,

// 启用增量编译（加快重编译速度）
"incremental": true

  },
// 指定哪些文件纳入编译，通常包含 Node 环境下的脚本或配置文件
"include": [
"vite.config.ts",
"scripts/**/*",
"build/**/*"

  ],
// 排除构建产物和依赖
"exclude": [
"node_modules",
"dist"

  ]

}

两者区别