环境准备：搭建你的迁移开发工作站
好，工具选好了，思路也理清了。接下来就是动手干活。但别急，很多同学上来就写脚本，结果一半时间花在排查环境问题上。我自己早期踩过不少坑，最惨的一次是项目快上线了，发现脚本在服务器上跑不起来——就因为Node版本不一样。
所以这一章，咱们把地基打牢。环境准备搞定了，后面写脚本才顺手。
工具链选型：你真正需要什么？
迁移脚本本质上是数据处理程序，不需要太重型的框架。我个人习惯按这个清单来准备：
| 工具/组件 | 推荐选型 | 为什么选它 |
|---|---|---|
| 运行时 | Node.js 18 LTS 或更高 | 原生支持ESM，worker_threads，性能稳定 |
| 包管理器 | pnpm 或 yarn berry | 解决了node_modules依赖地狱，速度快 |
| 语言 | TypeScript 5.x | 类型安全，重构时少掉头发 |
| 数据库驱动 | 具体看数据源，常见有mysql2、pg、mongosh | 连接池、流式读取，能扛大量数据 |
| 日志工具 | pino 或 winston | 结构化的日志，排查问题时救命用的 |
我建议：先装好 nvm（Node Version Manager），方便切换版本。很多遗留系统还在用 Node 14，但你本地开发用 18 更舒服。nvm 让你在两者之间一键切换，不用折腾系统全局。
项目初始化实战
就拿TypeScript + pnpm来举个例子。这配置我目前觉得最顺手的。
# 创建目录并初始化
mkdir migration-toolkit
cd migration-toolkit
pnpm init
# 安装核心依赖
pnpm add typescript -D
pnpm add @types/node -D
pnpm add tsx -D # 开发时直接跑ts，不用编译
# 生成tsconfig.json
npx tsc --init嗯，这里要注意，tsconfig.json 里几个字段必须改：
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"esModuleInterop": true,
"strict": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}然后你还需要一个 .gitignore。这个不能省，我在项目里见过有人把 node_modules 和 .env 提交到仓库的，后果非常难堪。
node_modules/
dist/
*.log
.env
.env.local
依赖管理的黄金原则
迁移脚本虽然不像大型应用那样有几十个依赖，但依赖管理没做好，照样会翻车。我曾经接手过一个项目，依赖没锁版本，结果一次生产部署时，底层库自动升级了一个小版本，数据类型判断逻辑变了，跑出来的数据全是错的。
所以，依赖锁定必须做：
- pnpm-lock.yaml 纳入版本控制 —— 保证所有人本地一致
- 不轻易升级依赖版本 —— 尤其要注意数据库驱动的版本兼容性
- 开发依赖和生产依赖分开 —— 生产容器里只装 dependencies 那一块
特别提醒：迁移脚本常常要连接多个数据库。如果你同时装了 mysql2、pg、mongodb 这些驱动，注意它们可能依赖不同版本的 libuv 或 openssl。在 macOS 上可能没事，但部署到 CentOS 或 Alpine 容器时就出问题。我建议用 Docker 提前模拟生产环境来测试。
推荐的目录结构
项目不能一团乱。我个人习惯这套结构，拿过来就能用：
migration-toolkit/
├── src/
│ ├── connectors/ # 数据库连接器
│ ├── extractors/ # 数据抽取逻辑
│ ├── transformers/ # 数据清洗、转换
│ ├── loaders/ # 数据加载到目标库
│ ├── config/ # 配置文件读取
│ ├── utils/ # 通用工具函数
│ └── main.ts # 入口
├── config/
│ ├── default.yaml
│ └── production.yaml
├── scripts/ # 辅助脚本
├── .env.example
├── .gitignore
├── package.json
├── tsconfig.json
├── pnpm-lock.yaml
└── README.md结构清晰，找东西不费劲。每个模块只做一件事，你想想看，如果 extractors 里混了数据库连接代码，后期改一个连接配置，你得翻遍整个项目。
调试与验证工具
光有配置还不够，开发时调试手段必须跟上。我记得以前调试迁移脚本只能 console.log，效率低得让人想哭。现在推荐这么一套：
| 场景 | 工具 | 说明 |
|---|---|---|
| 本地热更新 | tsx --watch | 改完代码自动重启，有点好用 |
| 断点调试 | VSCode launch.json + tsx | 配置一次，后面就一直用 |
| 环境变量验证 | zod 校验 env | 启动前就能发现配置丢失，不用跑到一半才报错 |
| 数据预览 | quick-lint + 日志输出到文件 | 调试阶段不直接写目标库，先打日志看看数据对不对 |
环境准备不是一次性的。项目每增加一个新的数据源，就要重新检查驱动兼容性、网络连通性、认证方式。这是持续的过程。
一张图梳理你的环境
下面这张图概括了完整的开发环境工作流——从初始化到调试验证，每一步都对应着实际要安装和配置的组件。你对着这张图，一个一个核对过去，环境就不容易出错了。
环境这块，说到底就是个“磨刀不误砍柴工”的事。把 Node 版本、包管理、项目结构、调试手段都搞定了，写脚本就是顺水推舟。下一件事，才是真正开始写数据抽取的代码。