被问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，但没有配置：

json 复制代码

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

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

影响类型检查的严格程度

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

影响团队代码规范一致性

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

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

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" 会导致路径解析失败。

常见配置内容：

ruby 复制代码

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

两者区别

对比点	`tsconfig.json`	`tsconfig.node.json`
目标环境	浏览器（前端代码）	Node.js（构建脚本、配置文件）
类型声明支持	浏览器相关，通常不包含 `node`类型	显式包含 `node`类型
使用场景	项目源码、页面组件、前端逻辑	vite.config.ts、开发工具脚本、构建相关逻辑
典型依赖项	Vue 类型（如 `vue`, `@vue/runtime-dom`）	Node 类型（如 `fs`, `path`）
是否必须存在	是，TypeScript 项目基本都要有	否，但推荐拆分使用以清晰职责
是否引用主配置	通常是主配置	可通过 `tsconfig.json`的 `references`引用它