跳至主要內容

环境搭建与初始化

刘春龙原创2026/3/5大约 5 分钟数据库TypeORM教程文档

一、前置环境检查

在开始搭建 TypeORM 环境前，需确保本地已安装：

  • Node.js：v14.0.0+（推荐 v16/v18 LTS 版本），可通过 node -v 验证；
  • npm/yarn/pnpm：包管理工具，npm 随 Node.js 自带，可通过 npm -v``yarn -v``pnpm -v 验证；
  • TypeScript（可选但推荐）：npm install -g typescript，通过 tsc -v 验证。

二、TypeORM 安装

1. 基础安装命令

根据包管理工具选择对应命令，核心依赖为 typeorm、reflect-metadata（装饰器支持）、数据库驱动：

# npm 安装（MySQL/MariaDB 示例）
npm install typeorm reflect-metadata mysql2

# npm 安装（PostgreSQL）
npm install typeorm reflect-metadata pg

# npm 安装（SQLite）
npm install typeorm reflect-metadata sqlite3

# npm 安装（MongoDB）
npm install typeorm reflect-metadata mongodb

# yarn 安装（MySQL/MariaDB）
yarn add typeorm reflect-metadata mysql2

# pnpm 安装（MySQL/MariaDB）
pnpm add typeorm reflect-metadata mysql2

2. TypeScript 类型依赖（可选）

# 安装 Node.js 类型 + 对应数据库类型（以 MySQL 为例）
npm install -D @types/node @types/mysql2

三、不同环境初始化步骤

1. Node.js 纯项目（TypeScript）

步骤 1：初始化项目

# 创建项目目录并初始化
mkdir typeorm-node-demo && cd typeorm-node-demo
npm init -y

# 生成 TypeScript 配置文件
tsc --init

步骤 2：配置 tsconfig.json（关键项）

修改 tsconfig.json，确保开启装饰器相关配置：

{
  "compilerOptions": {
    "target": "ES2018",                          // 编译目标版本
    "module": "CommonJS",                        // 模块系统
    "outDir": "./dist",                          // 输出目录
    "rootDir": "./src",                          // 源码目录
    "strict": true,                              // 严格模式
    "esModuleInterop": true,                     // ES 模块互操作
    "experimentalDecorators": true,              // 必须开启（装饰器支持）
    "emitDecoratorMetadata": true,               // 必须开启（元数据反射）
    "skipLibCheck": true,                        // 跳过库类型检查
    "forceConsistentCasingInFileNames": true     // 强制文件名大小写一致
  },
  "include": ["src/**/*"],                       // 包含的源码文件
  "exclude": ["node_modules"]                    // 排除的文件
}

步骤 3：配置数据源（data-source.ts）

TypeORM 0.3.x 及以上版本推荐使用 data-source.ts 替代旧版 ormconfig.json，在 src 目录下创建：

import "reflect-metadata";
import { DataSource } from "typeorm";

// 数据源配置
export const AppDataSource = new DataSource({
  type: "mysql",                // 数据库类型
  host: "localhost",            // 数据库地址
  port: 3306,                   // 端口
  username: "root",             // 用户名
  password: "your-db-password", // 数据库密码（替换为自己的）
  database: "typeorm_demo",     // 数据库名（需提前创建）
  entities: ["src/entity/**/*.ts"], // 实体文件路径
  migrations: ["src/migration/**/*.ts"], // 迁移文件路径
  subscribers: ["src/subscriber/**/*.ts"], // 订阅者文件路径
  synchronize: false,           // 生产环境禁用（自动同步表结构）
  logging: true,                // 打印 SQL 日志（开发环境开启）
  poolSize: 10,                 // 数据库连接池大小
  connectTimeout: 10000,        // 连接超时时间
});

// 初始化数据源
AppDataSource.initialize()
  .then(() => {
    console.log("数据库连接成功！");
  })
  .catch((err) => {
    console.error("数据库连接失败：", err);
  });

步骤 4：启动项目

在 src/index.ts 中引入数据源：

import "./data-source";

// 业务逻辑示例
console.log("TypeORM Node.js 项目初始化完成！");

添加启动脚本到 package.json：

{
  "scripts": {
    "dev": "ts-node src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

启动项目：

npm run dev

2. NestJS 项目集成

步骤 1：创建 NestJS 项目（若未创建）

# 全局安装 NestJS 脚手架
npm install -g @nestjs/cli

# 创建项目
nest new nest-typeorm-demo
cd nest-typeorm-demo

步骤 2：安装 TypeORM 依赖

# 安装 NestJS TypeORM 模块 + 核心依赖 + MySQL 驱动
npm install @nestjs/typeorm typeorm reflect-metadata mysql2

步骤 3：配置 TypeORM 模块

在 src/app.module.ts 中注册 TypeORM 模块：

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'mysql',
      host: 'localhost',
      port: 3306,
      username: 'root',
      password: 'your-db-password',
      database: 'nest_typeorm_demo',
      entities: [__dirname + '/**/*.entity{.ts,.js}'], // 实体文件路径
      synchronize: false,
      logging: true,
    }),
  ],
})
export class AppModule {}

3. Express 项目集成

步骤 1：初始化 Express 项目

# 创建项目目录并初始化
mkdir express-typeorm-demo && cd express-typeorm-demo
npm init -y

# 安装 Express 及 TypeScript 依赖
npm install express
npm install -D typescript ts-node @types/express @types/node
tsc --init

步骤 2：安装 TypeORM 依赖

npm install typeorm reflect-metadata mysql2

步骤 3：配置数据源 + 集成 Express

创建 src/data-source.ts（同 Node.js 纯项目配置），再创建 src/index.ts：

import "reflect-metadata";
import express from "express";
import { AppDataSource } from "./data-source";

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

// 初始化数据源后启动服务
AppDataSource.initialize().then(() => {
  app.get("/", (req, res) => {
    res.send("Express + TypeORM 初始化完成！");
  });

  app.listen(PORT, () => {
    console.log(`服务运行在 http://localhost:${PORT}`);
  });
});

四、配置文件详解（ormconfig / data-source.ts）

1. 核心配置项说明

配置项说明
type数据库类型（mysql/postgres/sqlite/mongodb/mssql 等）
host/port数据库地址/端口（SQLite 无需配置）
username/password数据库账号/密码（SQLite 无需配置）
database数据库名（SQLite 为文件路径，如 ./db.sqlite）
entities实体文件路径，支持通配符（如 src/entity/**/*.ts）
migrations迁移文件路径
subscribers订阅者文件路径
synchronize自动同步实体到数据库（开发环境可临时开启，生产环境必须禁用）
logging日志级别（true/false/"query"/"error"）
poolSize连接池大小，控制并发连接数
extra数据库驱动额外配置（如 MySQL 的 { connectTimeout: 10000 }）

2. 旧版 ormconfig.json 配置（兼容参考）

{
  "type": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "your-db-password",
  "database": "typeorm_demo",
  "entities": ["src/entity/**/*.ts"],
  "migrations": ["src/migration/**/*.ts"],
  "subscribers": ["src/subscriber/**/*.ts"],
  "logging": true,
  "synchronize": false,
  "cli": {
    "entitiesDir": "src/entity",
    "migrationsDir": "src/migration",
    "subscribersDir": "src/subscriber"
  }
}

五、不同数据库配置差异

1. MySQL/MariaDB

{
  type: "mysql",
  host: "localhost",
  port: 3306,
  username: "root",
  password: "your-password",
  database: "demo",
  charset: "utf8mb4", // 支持 emoji 等特殊字符
  extra: {
    connectionLimit: 10 // 连接池限制
  }
}

2. PostgreSQL

{
  type: "postgres",
  host: "localhost",
  port: 5432,
  username: "postgres",
  password: "your-password",
  database: "demo",
  schema: "public", // PostgreSQL 模式
  ssl: process.env.NODE_ENV === "production" ? { rejectUnauthorized: false } : false
}

3. SQLite

{
  type: "sqlite",
  database: "./demo.sqlite", // 本地文件路径
  synchronize: true, // 轻量场景可开启自动同步
  logging: true
}

4. MongoDB

{
  type: "mongodb",
  url: "mongodb://localhost:27017/demo", // 连接字符串
  useUnifiedTopology: true,
  entities: ["src/entity/**/*.ts"]
}

至此，本章节的学习就到此结束了，如有疑惑，可对接技术客服进行相关咨询。

嘉美开发社区 https://jiameisq.top
Copyright © 2026 刘春龙