Node.js工程化实践：包管理、TypeScript配置与代码质量

预计时间：2 天

🎯 本章目标

搭建一个规范、高效的 TypeScript Node.js 开发环境。

1. ESLint（代码规范）

bash 复制代码

pnpm add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

javascript 复制代码

// eslint.config.js（flat config，ESLint 9+）
import tseslint from '@typescript-eslint/eslint-plugin';
import tsparser from '@typescript-eslint/parser';

export default [
  {
    files: ['src/**/*.ts'],
    languageOptions: {
      parser: tsparser,
      parserOptions: { ecmaVersion: 2022, sourceType: 'module' }
    },
    plugins: { '@typescript-eslint': tseslint },
    rules: {
      '@typescript-eslint/no-unused-vars': 'warn',
      '@typescript-eslint/no-explicit-any': 'warn',
      '@typescript-eslint/explicit-function-return-type': 'off',
      'no-console': 'warn',
    }
  }
];

2. Prettier（代码格式化）

bash 复制代码

pnpm add -D prettier

json 复制代码

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100,
  "tabWidth": 2
}

json 复制代码

// package.json scripts
"format": "prettier --write src/**/*.{ts,json}"

3. 调试配置

VS Code 调试

json 复制代码

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug TS",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "tsx",
      "args": ["${workspaceFolder}/src/index.ts"],
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "name": "Jest Tests",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/vitest",
      "args": ["run"]
    }
  ]
}

代码中断点调试

typescript 复制代码

// 在代码中插入 debugger 语句
async function handleRequest(req, res) {
  debugger; // VS Code 会在这里暂停
  const data = await getData();
  res.json(data);
}

4. 日志系统

bash 复制代码

pnpm add pino  # 高性能日志库（比 console.log 快 5x）

typescript 复制代码

import pino from 'pino';

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  transport: process.env.NODE_ENV === 'development'
    ? { target: 'pino-pretty' }
    : undefined
});

logger.info('Server started on port %d', 3000);
logger.error({ err }, 'Failed to connect to database');
logger.debug({ userId: 1 }, 'Processing request');

export default logger;

与 Java 日志对比

Java	Node.js
SLF4J / Logback	pino / winston
`logger.info("msg {}", arg)`	`logger.info('msg %s', arg)`
`logger.error("msg", e)`	`logger.error({ err: e }, 'msg')`

5. 环境变量管理

bash 复制代码

pnpm add dotenv
pnpm add -D @types/node

typescript 复制代码

// src/config/env.ts
import 'dotenv/config';
import { z } from 'zod'; // 用 zod 做运行时校验

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

const env = envSchema.parse(process.env);

export type Env = z.infer<typeof envSchema>;
export default env;

env 复制代码

# .env
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
JWT_SECRET=your-super-secret-key-here
LOG_LEVEL=debug

gitignore 复制代码

# .gitignore
.env
node_modules/
dist/
*.log

6. 构建工具选择

对比

工具	特点	适用场景
`tsc`	官方编译器，只转译不打包	库、简单项目
`tsup`	基于 esbuild，快，零配置	推荐，API 项目
`esbuild`	极快，底层工具	构建插件开发
`swc`	Rust 写的编译器，极快	大型项目
`webpack`	功能全面，配置复杂	前端项目

tsup 配置

bash 复制代码

pnpm add -D tsup

json 复制代码

// package.json scripts
"build": "tsup src/index.ts --format esm --dts --clean",
"dev": "tsup src/index.ts --format esm --watch --onSuccess 'node dist/index.js'"

7. Git Hooks（提交规范）

bash 复制代码

pnpm add -D husky lint-staged
pnpm exec husky init

json 复制代码

// package.json
"lint-staged": {
  "src/**/*.ts": [
    "eslint --fix",
    "prettier --write"
  ]
}

bash 复制代码

# .husky/pre-commit
pnpm exec lint-staged

8. 完整开发工作流

bash 复制代码

# 1. 克隆项目
git clone <repo> && cd <repo>

# 2. 安装依赖
pnpm install

# 3. 复制环境变量
cp .env.example .env

# 4. 开发（热重载）
pnpm dev

# 5. 代码检查
pnpm lint
pnpm format

# 6. 构建
pnpm build

# 7. 测试
pnpm test

# 8. 生产部署
pnpm start

下一步：Express基础