正文

TypeScript项目从零搭建避坑指南配置tsconfig.json与ESLint集成实战解析

/0 浏览量
0627

写代码就像装修房子，地基打得歪，墙砌得再漂亮早晚也得塌。很多开发者刚上手 TypeScript 时，觉得“随便配一下就能跑”，结果在项目中期遇到类型报错满天飞、Lint 规则互相打架、或者构建速度慢到怀疑人生。今天咱们不聊虚的，直接深入 tsconfig.json 的核心配置陷阱，并手把手教你把 ESLint 和 Prettier 完美嵌入 TypeScript 工作流，让你的项目从一开始就走上正轨。

第一步：别急着写代码，先搞定 tsconfig.json 这个“大脑”

tsconfig.json 是 TypeScript 编译器的配置文件，它决定了你的代码如何被转换成 JavaScript。很多人喜欢直接复制网上的模板，但如果不理解每个选项的含义，后续维护简直是灾难。

1.1 核心选项深度解析

让我们从一个稳健的基础配置开始，我会逐一解释为什么这么选：

{
  "compilerOptions": {
    // 1. 目标环境：你的代码最终要在哪里运行？
    // ES2020 是目前比较平衡的选择，支持 Promise.allSettled 等新特性
    "target": "ES2020",
    
    // 2. 模块系统：Node.js 推荐 commonjs，浏览器/打包工具推荐 esnext 或 es2020
    "module": "esnext",
    
    // 3. 模块解析策略：Node.js 项目必须用 node，否则 import 路径会找不到
    "moduleResolution": "node",
    
    // 4. 严格模式开启：这是 TypeScript 的灵魂！不要为了省事关掉它
    "strict": true,
    
    // 5. 允许从没有类型声明的文件导入：处理老旧库或第三方 JS 库必备
    "allowJs": true,
    
    // 6. 检查 JS 文件中的类型错误：配合 allowJs 使用，提升整体代码质量
    "checkJs": false, 
    
    // 7. 输出目录：编译后的 JS 文件放在哪
    "outDir": "./dist",
    
    // 8. 根目录：源码的根目录
    "rootDir": "./src",
    
    // 9. 是否生成源地图（Source Map）：调试神器，生产环境可关闭
    "sourceMap": true,
    
    // 10. 删除注释：生产构建时清理掉 TS 特有的注释
    "removeComments": true,
    
    // 11. 是否允许编译 JavaScript 文件：通常设为 false，强制使用 TS
    "noEmit": false,
    
    // 12. 忽略声明文件检查：如果不想为每个第三方库写 d.ts，可以设为 false
    "skipLibCheck": true, 
    
    // 13. 启用装饰器实验性功能：如果你用 NestJS 或 Angular，这个必须开
    "experimentalDecorators": true,
    
    // 14. 导出所有命名空间：防止命名冲突
    "esModuleInterop": true,
    
    // 15. 允许未使用的变量：开发阶段方便调试，生产环境建议通过 Lint 控制
    "noUnusedLocals": false,
    "noUnusedParameters": false
  },
  
  // 包含哪些文件，排除哪些文件
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

1.2 常见坑点提醒

  • strict: true 不要随意关闭：很多初学者看到 any 报错就慌了，想关掉严格模式。其实 strict 包含了很多子选项，如 noImplicitAny、strictNullChecks 等。关闭 strict 意味着你放弃了 TypeScript 最重要的类型安全保护。正确的做法是逐个排查并修复类型问题，而不是逃避。
  • moduleResolution 选错导致路径报错：如果你在使用 Node.js 后端项目，务必使用 "node"。如果使用 Webpack/Vite 等现代打包工具，可以考虑 "bundler"（TS 4.7+ 支持），它能更好地模拟打包工具的解析行为。
  • skipLibCheck: true 提升编译速度：如果你的项目依赖了大量第三方库，且这些库的类型定义比较复杂，开启此选项可以显著加快编译速度，因为它跳过对 node_modules 中 .d.ts 文件的检查。

第二步：ESLint 与 TypeScript 的完美共舞

光有编译器检查是不够的，我们还需要静态代码分析工具来捕获运行时可能出现的错误、代码风格问题以及最佳实践。ESLint 是这方面的王者，但它原生并不懂 TypeScript 的语法，所以需要额外的插件。

2.1 安装必要的依赖

你需要安装以下包：

npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-prettier prettier
  • @typescript-eslint/parser：让 ESLint 能解析 TypeScript 代码。
  • @typescript-eslint/eslint-plugin：提供针对 TypeScript 特有的规则集。
  • eslint-config-prettier：禁用所有可能与 Prettier 冲突的 ESLint 规则。
  • prettier：代码格式化工具。

2.2 配置 .eslintrc.js

创建一个 .eslintrc.js 文件，内容如下：

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:@typescript-eslint/recommended-requiring-type-checking',
    'prettier',
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: './tsconfig.json', // 关键！连接 ESLint 和 tsconfig
  },
  plugins: ['@typescript-eslint'],
  rules: {
    // 自定义规则示例
    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    '@typescript-eslint/explicit-function-return-type': 'warn',
    '@typescript-eslint/no-explicit-any': 'error',
    // 其他规则...
  },
};

2.3 关键点解析

  • parserOptions.project：这是最容易出错的地方。你必须指定 tsconfig.json 的路径，这样 ESLint 才能利用 TypeScript 的类型信息进行更深入的检查（如 no-floating-promises）。如果这里配置错误，很多高级规则将无法生效。
  • extends 顺序：确保 'prettier' 在最后，这样它可以覆盖前面可能存在的冲突规则。
  • plugin:@typescript-eslint/recommended-requiring-type-checking：这个扩展包含了需要类型信息的规则，比如检查异步函数是否被 await。由于启用它会增加 ESLint 的运行时间，建议在 CI/CD 环境中单独运行，或者在本地开发时使用轻量级的 recommended。

第三步：Prettier 格式化，解放双手

ESLint 负责逻辑和风格，Prettier 负责排版。两者结合才能达到最佳效果。

3.1 创建 .prettierrc

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "printWidth": 100,
  "trailingComma": "all",
  "bracketSpacing": true,
  "arrowParens": "always"
}

3.2 集成到 VS Code

为了让编辑器自动格式化，你需要在 VS Code 中安装 ESLint 和 Prettier 插件，并在设置中添加：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "eslint.validate": [
    "javascript",
    "typescript"
  ]
}

注意：有些开发者会选择让 ESLint 格式化，但更推荐直接使用 Prettier，因为它的规则更简单直观，且与 ESLint 冲突较少。

第四步：实战演练——一个完整的 TypeScript 项目结构

假设你要搭建一个小型的 Node.js API 服务，项目结构大致如下：

my-ts-project/
├── src/
│   ├── index.ts          # 入口文件
│   ├── controllers/      # 控制器
│   ├── services/         # 业务逻辑
│   └── types/            # 类型定义
├── tests/                # 测试文件
├── dist/                 # 编译输出
├── .eslintrc.js
├── .prettierrc
├── tsconfig.json
└── package.json

4.1 编写一个简单的服务类

在 src/services/userService.ts 中：

import { User } from '../types/user';

export class UserService {
  private users: User[] = [];

  addUser(user: User): void {
    this.users.push(user);
  }

  getUsers(): User[] {
    return this.users;
  }
}

这里我们定义了 User 类型：

// src/types/user.ts
export interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

4.2 运行检查

现在，你可以运行以下命令来检查代码：

# 运行 ESLint 检查
npx eslint src/**/*.ts

# 运行 TypeScript 编译
npx tsc

# 运行 Prettier 格式化
npx prettier --write src/**/*.ts

如果一切正常，你应该不会看到任何错误或警告。如果有，根据提示逐步修复。

第五步：进阶技巧——提升开发体验

5.1 使用 Husky 和 lint-staged 进行提交前检查

为了避免坏代码提交到仓库，我们可以使用 Husky 和 lint-staged：

npm install --save-dev husky lint-staged

在 package.json 中添加：

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.ts": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

然后运行：

npx husky add .husky/pre-commit "npx lint-staged"

这样，每次提交代码时，都会自动对暂存区的 TypeScript 文件进行 ESLint 修复和 Prettier 格式化。

5.2 区分开发环境和生产环境的配置

对于大型项目，你可能希望开发时启用更严格的检查，而生产构建时优化性能。可以通过创建多个配置文件来实现：

  • tsconfig.dev.json：包含更详细的错误检查和源地图。
  • tsconfig.prod.json：优化编译选项，如删除注释、最小化输出等。

在 package.json 中定义不同的脚本：

{
  "scripts": {
    "dev": "tsc --project tsconfig.dev.json && node dist/index.js",
    "build": "tsc --project tsconfig.prod.json"
  }
}

结语

搭建一个健壮的 TypeScript 项目并不是一件轻松的事，但一旦你掌握了 tsconfig.json 的核心配置和 ESLint/Prettier 的集成技巧，后续的开发和维护将会变得异常顺畅。记住，工具是为了服务于人，而不是束缚创造力。合理配置，适度严格，才能在保证代码质量的同时，享受编程的乐趣。

希望这篇指南能帮助你避开那些常见的坑，让你的 TypeScript 之旅更加平稳。如果你在实际操作中遇到问题，欢迎随时回来查阅，或者在社区中寻找答案。毕竟，最好的学习方式是实践和反思。

-- 展开阅读全文 --