第八章：工具链与构建

1. tsconfig.json 进阶

超越基础配置，掌握影响项目结构和编译行为的关键选项。

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "incremental": true,
    "tsBuildInfoFile": "./dist/.tsbuildinfo",

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

    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

2. ESLint

ESLint 配合 typescript-eslint 可以在编码阶段捕获潜在问题。推荐使用 Flat Config 新格式。

npm install -D eslint @eslint/js typescript-eslint

// eslint.config.js
import eslint from "@eslint/js";
import tseslint from "typescript-eslint";

export default tseslint.config(
    eslint.configs.recommended,
    ...tseslint.configs.recommended,
    {
        rules: {
            "@typescript-eslint/no-unused-vars": ["error", {
                argsIgnorePattern: "^_",
            }],
            "@typescript-eslint/explicit-function-return-type": "warn",
            "@typescript-eslint/no-explicit-any": "error",
            "no-console": ["warn", { allow: ["warn", "error"] }],
        },
    },
    {
        ignores: ["dist/", "node_modules/"],
    }
);

npx eslint .          # 检查所有文件
npx eslint --fix .    # 自动修复可修复的问题

3. Prettier

Prettier 负责代码格式化——统一风格，结束无谓的格式之争。

npm install -D prettier eslint-config-prettier

// .prettierrc
{
  "semi": true,
  "singleQuote": false,
  "tabWidth": 4,
  "trailingComma": "all",
  "printWidth": 100,
  "arrowParens": "always"
}

在 ESLint 配置中加入 eslint-config-prettier，关闭与 Prettier 冲突的规则：

// eslint.config.js 中追加
import prettier from "eslint-config-prettier";

export default tseslint.config(
    // ...其他配置
    prettier, // 放在最后，覆盖冲突规则
);

编辑器设置 Format on Save，即可在保存时自动格式化。

4. 构建工具对比

5. npm 包发布

发布 TypeScript 包时，需要同时提供编译后的 JS 和类型声明文件。

// package.json 关键字段
{
  "name": "my-ts-lib",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  }
}

npm login
npm publish     # 发布到 npm registry

files 字段指定发布包含的文件，比 .npmignore 更直观——白名单优于黑名单。

6. Docker 部署

多阶段构建：第一阶段编译 TypeScript，第二阶段只保留运行时需要的 JS 文件，大幅减小镜像体积。

# Dockerfile
# ===== 构建阶段 =====
FROM node:20-alpine AS builder
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

# ===== 生产阶段 =====
FROM node:20-alpine AS production
WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev

COPY --from=builder /app/dist ./dist

ENV NODE_ENV=production
EXPOSE 3000

USER node
CMD ["node", "dist/index.js"]

# 构建并运行
docker build -t my-ts-app .
docker run -p 3000:3000 --env-file .env my-ts-app

📝 本章要点 & 教程完结