02 — 环境搭建与项目初始化

2.1 前置条件

确保你电脑上装了：

• Node.js >= 20（建议装 LTS 版本）
• npm 或 pnpm（包管理器）
• 一个代码编辑器（VS Code 推荐）

检查版本：

node -v
npm -v

---

2.2 初始化项目

第一步：创建目录

mkdir my-backend
cd my-backend

第二步：初始化 package.json

npm init -y

会生成一个默认的 package.json。

第三步：安装依赖

# 生产依赖
npm install express

# 开发依赖
npm install -D typescript @types/express tsx
npm install -D eslint prettier

---

2.3 配置 TypeScript

在根目录创建 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

关键配置说明

配置	作用
target: "ES2022"	编译到 ES2022，Node 20 原生支持
module: "ESNext"	使用 ESM 模块系统
moduleResolution: "bundler"	配合 ESM 的模块解析方式
strict: true	严格类型检查，建议开
paths	路径别名，@/ 指向 src/

---

2.4 配置 package.json 脚本

打开 package.json，加上这些：

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "start": "tsx src/server.ts",
    "build": "tsc",
    "preview": "node dist/server.js",
    "typecheck": "tsc --noEmit",
    "lint": "eslint src/",
    "format": "prettier --write src/"
  }
}

脚本说明

命令	作用
npm run dev	开发模式，文件改动自动重启
npm start	生产环境直接运行（用 tsx）
npm run build	编译成 JS 到 dist 目录
npm run preview	运行编译后的 JS
npm run typecheck	只做类型检查，不输出
npm run lint	代码质量检查
npm run format	自动格式化代码

---

2.5 目录结构初始化

创建基础目录：

mkdir -p src/{config,routers,controllers,services,models,data,middlewares,errors,utils,types}

Windows PowerShell：

New-Item -ItemType Directory -Force -Path src/config, src/routers, src/controllers, src/services, src/models, src/data, src/middlewares, src/errors, src/utils, src/types

---

2.6 写第一个接口（验证环境）

创建 src/server.ts：

import express from 'express';

const app = express();
const PORT = 3000;

app.get('/api/hello', (_req, res) => {
  res.json({ status: 0, data: 'Hello, Express!' });
});

app.listen(PORT, () => {
  console.log(`Server running at http://localhost:${PORT}`);
});

启动：

npm run dev

打开浏览器访问 http://localhost:3000/api/hello，能看到返回的 JSON 就说明环境搭好了。

---

2.7 配置 ESLint（可选但推荐）

eslint.config.js：

import js from '@eslint/js';
import tseslint from 'typescript-eslint';

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    rules: {
      'no-unused-vars': 'off',
      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/no-explicit-any': 'warn',
    },
  },
];

安装依赖：

npm install -D @eslint/js typescript-eslint

---

2.8 配置 Prettier（可选但推荐）

prettier.config.js：

/** @type {import('prettier').Config} */
export default {
  semi: true,
  singleQuote: true,
  trailingComma: 'all',
  printWidth: 100,
  tabWidth: 2,
};

---

2.9 最终的文件清单

到这一步，你的项目应该长这样：

my-backend/
├── src/
│   └── server.ts           # 测试用的入口文件
├── package.json
├── tsconfig.json
├── eslint.config.js        # 可选
└── prettier.config.js      # 可选

接下来的章节会一步步把它变成一个完整的后端项目。