小狐狸与小道士作为后端开发，我几乎每个月都要在开发库、测试库、预发布库之间来回折腾数据。最痛的一种场景是：测试环境账务数据被回归脚本跑乱了，开发环境代码里依赖某张配置表的最新状态，可表里还停在三天前；或者是前端联调需要一批跟线上结构一致的模拟数据，我只能靠手工写SQL一条条补。时间一久我就发现，这种“把A库的表数据对齐到B库”的需求，频率远比想象中高，而且纯手搓SQL不仅慢，还特别容易漏字段、错类型。
后来我用 Node.js + mysql2 写了一个非常轻量的同步助手，专门解决开发/测试环境下快速对齐表数据的问题。它不需要安装额外客户端，不依赖图形界面，一条命令就能把源库指定表的数据结构、字段映射关系、同步到目标库，支持全量对齐、条件过滤、增量更新，还有 dry-run 和备份这些保命功能。这篇文章就把这个工具从设计到实现、再到实际运维中踩过的坑完整拆一遍，适合正在被多环境数据一致性折磨的后端开发、测试工程师，以及想用 Node.js 写内部效率工具的朋友参考。
1. 为什么我决定写这个同步助手
1.1 开发/测试环境的数据同步需求从哪来
在做业务系统的时候，环境一般分四套：本地开发环境、测试环境、预发布环境、生产环境。生产环境数据敏感不能随便动，但本地和测试环境就没那么多讲究了，反而需要频繁地“造数据”和“修数据”。
最常见的场景有这么几类。第一类是配置表同步，比如订单状态机配置、支付渠道参数、风控规则阈值这些，通常以配置表的形式存在，开发环境改了配置，测试环境没跟上，测试同学一测就报“跟预期不符”。第二类是基础数据初始化，比如新接了一个第三方服务的字典表，需要把测试环境已有的字典数据整体灌到本地库，不然代码一跑全是空指针。第三类是脏数据修复的逆向操作，测试环境被回归脚本弄乱了，需要拿开发环境的备份数据重新覆盖。
这些操作如果靠人工，基本就是导出SQL文件，再导入目标库。一张两张表还能忍，一旦牵扯到十来张关联表，每个表几十个字段，手工维护映射关系就会出很多低级错误——比如源表字段顺序看错了、时间字段格式没转、TINYINT当成了布尔值。这类问题在低代码平台或者强类型系统里尤其致命。
1.2 已有方案的对比：为什么不用现成工具
实现表数据同步的方案其实不少，但我逐个试过之后发现，在“开发/测试环境”这个特定场景下，它们各有各的别扭。
用 mysqldump 是最经典的方式，导出整个库或单张表，再导入目标库。它对整库迁移很顺手，但有几个硬伤：一是会带上表结构定义，如果你只想同步数据不想动目标表结构，得额外加参数；二是导出的 SQL 文件里包含 DROP TABLE / CREATE TABLE 之类的语句，在生产环境习惯的谨慎模式下，反而容易误操作；三是如果只是部分数据（比如只同步 status=1 的记录），mysqldump 需要配合 WHERE 条件做二次加工，很啰嗦。另外在 Windows 开发机上装 mysqldump 客户端，本身又是一轮环境配置问题。
Navicat 这类 GUI 工具自带数据同步功能，操作简单直观，但它是按“两张表之间的差额同步”设计的，每次同步前会先做全表对比，表一大就慢，而且它是图形界面，没法塞进自动化脚本里。你也不可能每天上班先打开 Navicat 手动点一遍同步。
还有不少开源的同步中间件，比如 DataX、Canal 之类，能力很强，但部署成本也高。为了“开发环境对齐一张表”去搭一套 DataX 任务调度，属实杀鸡用牛刀，而且这类工具面向的是异构数据源或者大规模数据同步，对日常轻量需求来说过于笨重。
所以我的诉求很明确：一个命令行工具，读取一个配置文件，把源库指定表的数据同步到目标库指定表，支持字段映射、条件过滤、增量更新、安全预览。Node.js 生态里 mysql2 足够成熟，async/await 写起来很舒服，npm 包几秒钟装完，不污染系统环境。于是这个同步助手就诞生了。
1.3 技术选型：为什么是 Node.js + mysql2
Node.js 做这类“胶水工具”非常合适。它的安装包在所有主流操作系统上都有，解压即用，不像 Python 那样在 Windows 上配环境变量偶尔出幺蛾子，也不像 Java 那样要带一整套 JRE。最重要的是，Node.js 的包管理让人写小工具时完全没有负担——npm install 一个 mysql2，几秒搞定，不需要额外装原生编译工具链。
mysql2 这个库本身也有很多值得说的点。它是 mysql 这个老牌 Node.js 驱动库的升级维护分支，api 兼容性很好，同时带来了 Promise 原生支持。早期用 mysql 库写异步代码，得靠 util.promisify 包一层，而 mysql2 直接支持 await 风格，代码写起来顺滑很多。另外 mysql2 对预处理语句（Prepared Statement）的支持更完善，可以显著减少 SQL 注入风险，在把表名、字段名、值拼进 SQL 的时候，这个优势会被无限放大。
还有一点是连接池的支持。mysql2/promise 提供了 createPool 接口，配合连接池，在同步多张表、批量读写的时候能复用连接，不会出现连接数被打满的尴尬。这些特性让 mysql2 成为这个场景下的最佳选择。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 同步助手的功能设计与核心思路
2.1 核心能力拆解：同步什么、怎么同步、怎么安全地同步
动手写代码之前，我先把“同步表数据”这件事拆成了五个子问题。
第一，源表数据从哪来。最直接的方式就是 SELECT * FROM source_table，但实际场景里可能要加 WHERE 条件，比如只同步最近七天的数据，或者只同步某些渠道的记录。所以数据读取必须支持条件过滤。
第二，目标表结构跟源表未必一致。开发环境和测试环境的表结构可能因为版本迭代产生了差异，比如源表叫 user_info，目标表叫 users，字段名也不完全一样。所以字段映射是必须的，让用户显式声明“源表的这N个字段对应目标表的哪N个字段”。
第三，怎么对齐。对齐不等于删掉目标表全部数据再插入，那样既慢又危险。合理的方式是基于业务主键做对比：目标表存在这条数据就更新，不存在就插入。如果业务上要求目标表“只能有源表这些数据”，还需要把目标表里多余的数据删掉。
第四，同步过程不能失控。万一 WHERE 条件写漏了，或者字段映射配错了，直接把目标表几百万行数据覆盖掉，那就真成了事故。所以必须提供 dry-run 模式，先预览将要执行的 SQL，并且支持在同步前自动备份被修改的表。
第五，性能要可控。一次同步几万条数据，如果逐条 UPDATE 或者逐条 INSERT，时间会非常感人。需要实现批量写入，以及分批读取、分批更新，避免占用过大内存。
整个工具的设计难点不在于单个 SQL 怎么写，而在于把这些约束组合成一个配置驱动的流程，让使用者不用改代码，只改 JSON 配置就能完成不同表和不同字段的同步。
2.2 配置驱动：用一份JSON描述所有同步任务
我理想的用法是：node sync.js --config sync.config.json，一份配置搞定一个同步任务。配置文件里必须包含源库连接、目标库连接、同步任务列表三部分。
粗略的配置结构是这样的：
json复制{
"source": {
"host": "127.0.0.1",
"port": 3306,
"user": "root",
"password": "123456",
"database": "dev_db"
},
"target": {
"host": "127.0.0.1",
"port": 3306,
"user": "root",
"password": "123456",
"database": "test_db"
},
"tasks": [
{
"table": "sys_config",
"targetTable": "sys_config",
"primaryKey": "id",
"fields": ["id", "config_key", "config_value", "updated_at"],
"where": "",
"deleteExtra": false,
"chunkSize": 1000
}
]
}
用 JSON 而不是 JS 配置，有一个很实际的原因：很多测试同学和运维同学不一定擅长写代码，但他们都会改 JSON。把同步逻辑写成死代码，每次都要让会写代码的人去改，这个工具就失去了“给团队用”的价值。而 JSON 配置足够直观，复制一份改一改，一个新任务就出来了。
primaryKey 字段至关重要，它决定了同步时如何匹配两条记录。默认情况下，我要求配置里必须显式指定主键，如果表没有主键，就无法启用 UPDATE 分支，只能先 DELETE 再 INSERT，这一点我会在代码里强制校验。
2.3 同步策略：全量对齐 / 增量更新 / 条件过滤
同步策略我实现了三种，对应不同场景。
第一种是全量对齐，目标表以源表数据为准。执行方式是：把目标表整表数据先清掉（或者按条件清掉），再把源表所有符合条件的数据插入进去。这种策略最省事，但风险也最大，必须在配置里加 "forceFullReplace": true 才能启用，防止手滑。
第二种是基于主键的 upsert，这是默认策略。流程是先查询源表数据，再针对每一条记录查询目标表是否存在相同主键——如果存在，执行 UPDATE；不存在，执行 INSERT。为提高效率，我不会一条条 SELECT 判断，而是先把源表主键集合一次性查出来，再在目标表用 SELECT ... WHERE primary_key IN (...) 批量判断，落库性能会好很多。
第三种是增量更新，针对那些有 update_time 或者 updated_at 字段的表。配置文件里可以加 "incrementalField": "updated_at" 和 "incrementalValue": "2024-06-01 00:00:00"，读取源表时自动追加 WHERE updated_at > :incrementalValue。这样跑定时任务的时候，每次只需要同步最近改动的记录，而不是把整张表都拖一遍。
条件过滤配合增量更新使用，效果更好。例如只同步某个租户下的配置："where": "tenant_id = 1001"，工具会自动拼接在 SELECT 语句中。所有策略的本质，都是把用户想要表达的业务规则转换成一组可追溯、可预览的 SQL 语句，而不是在代码里写死流程。
2.4 关键安全机制：dry-run、备份、事务与条件保护
写数据同步工具，第一条原则是“默认不执行，显式才执行”。所以我在工具里加入了一个开关，只有命令行指定 --apply 参数时，才会真正把数据写入目标库；否则默认只打印将要执行的 SQL，以及统计信息，比如“会更新 100 条，新增 50 条，删除 20 条”。
同时，在真正 apply 之前，工具会检查配置里是否声明了 "allowApply": true。如果没有这个字段，即使加了 --apply 也会拒绝执行。这个双重保险防止了有人拿着没改过的默认配置直接覆盖数据。
针对单表更新量超过阈值的场景，工具会在同步前自动在目标库创建一张备份表，命名规则是 {table_name}_backup_{timestamp}，把目标表当前的数据整体复制进去。这样万一同步逻辑有 bug，还能一键回滚。备份操作本身也放在同一个事务里，避免备份成功但同步失败造成的不一致状态。
事务的使用我是按“每张表一个事务”来设计的。源库读取不开启事务（快照读），目标库写入时开启事务，如果中途出现批量写入失败，整表回滚。这里有个经验：不要把所有表放在同一个大事务里，因为一旦某张表的数据量特别大，事务持续时间会很长时间，容易造成行锁冲突和 binlog 暴涨，分表事务更可控。
条件保护则是对 DELETE 的约束。工具里默认的 DELETE FROM target_table 语句是禁止执行的，必须显式配 "deleteExtra": true 且提供 "deleteWhere": "1=1"（任何非空条件），否则多余数据不会被清理。这么做看起来很繁琐，但确实能拦住很多次误操作。
3. 核心代码实现与关键细节
3.1 项目结构一览
同步助手的项目结构非常简洁，主要文件就五个：
text复制sync-helper/
├── package.json
├── sync.js
├── config/
│ └── sync.config.json
├── src/
│ ├── db.js
│ ├── reader.js
│ ├── writer.js
│ └── compare.js
└── README.md
sync.js 是入口，负责解析命令行参数、读取配置、编排整个同步流程。src/db.js 封装了源库和目标库的连接池创建。src/reader.js 负责从源库读取数据并解析字段。src/compare.js 负责对比源表和目标表的差异，生成同步决策。src/writer.js 负责执行批量写入和删除。
我特意把读取和写入拆成两个模块，这样如果想扩展成支持更多源数据库，比如 PostgreSQL，只需替换 reader 模块，不需要动 writer 和 compare 模块。
3.2 数据库连接与连接池管理
数据库连接部分，我用 mysql2/promise 的 createPool 创建连接池，连接参数从配置读取。这里有几个细节值得展开说说。
第一，连接池的 waitForConnections 要设置为 true，connectionLimit 默认 10 即可。同步场景并发不高，连接池主要是为了复用连接，避免每条 SQL 都走一次 TCP 握手。第二，需要设置 charset: 'UTF8MB4_UNICODE_CI'，否则遇到 emoji 或者生僻字会乱码。第三，要开启 dateStrings: true，将日期类型直接作为字符串返回。这个细节很关键，如果让驱动默认把 DATE 转成 JS Date 对象，再进行 JSON 序列化，时区很容易出现偏移，导致同步到目标库的时间比源库早 8 小时或者晚 8 小时。统一用字符串传递，反而最安全。
连接池初始化代码大致是：
javascript复制const mysql = require('mysql2/promise');
async function createPool(config) {
return mysql.createPool({
host: config.host,
port: config.port || 3306,
user: config.user,
password: config.password,
database: config.database,
waitForConnections: true,
connectionLimit: 10,
charset: 'UTF8MB4_UNICODE_CI',
dateStrings: true,
decimalNumbers: false,
supportBigNumbers: true,
bigNumberStrings: true
});
}
这里 supportBigNumbers 和 bigNumberStrings 也很重要。MySQL 的 BIGINT 如果超出 JS 安全整数范围，默认会被截断成不精确的数字，导致主键或金额字段精度丢失。开启 bigNumberStrings 后，这类值会作为字符串返回，规避精度问题。如果你拿 BIGINT 当主键，我建议务必打开这个选项。
3.3 读取源表数据与数据类型处理
读取源表数据时，我会先根据配置里的 fields 字段拼接 SELECT 语句。默认情况下列出所有字段，但更推荐显式指定字段列表，因为字段少一点，网络传输和内存占用都会少一点，而且能避免把 password、token 这类敏感字段意外同步到测试环境。
拼接 SQL 时，表名和字段名都要经过反引号转义，防止表名撞上 MySQL 保留字。mysql2 的 escapeId 方法正好能做这件事。值则使用 ? 占位符交给驱动预处理，靠库本身的能力做转义，不手动拼字符串。
接下来是从结果集中读取行数据。这里我直接使用 connection.execute 而不是 connection.query，因为 execute 走预处理协议，返回的数据结构和类型更稳定。对于大表，不能一次性把所有行都读进内存，我用 LIMIT ? OFFSET ? 做分页读取，每次处理一个 chunk。但要注意，分页读取要求主键稳定，如果同步过程中源表本身有写入，可能会产生重复或遗漏。对一个开发/测试场景的工具来说，这个风险是可接受的，毕竟源表数据本来就允许有一定程度的动态变化。
如果表里存在 JSON 类型的字段，mysql2 返回的会是字符串。我封装了一个 normalizeRow 函数，把字段值统一做一次整理：null 保持 null，Buffer 转成 base64（二进制字段无法直接靠 SQL 语句传输，必须转换），JSON 字符串原样保留，数字统一转成字符串或数字类型。这种转换可能看起来多此一举，但实际同步过程中，字段类型不一致引起的异常大多能在这里被提前“熨平”。
3.4 数据对比与同步SQL生成（upsert 与 delete）
核心逻辑在 compare.js。拿到源表数据和目标表已有主键集合之后，工具会生成三类操作：需要插入的记录、需要更新的记录、需要删除的主键值。
对比算法不复杂。把目标表主键集合构造成一个 Set，遍历源表数据时，如果主键不在 Set 中，标记为 insert；如果主键在 Set 中，标记为 update。删除逻辑则反过来，对目标表所有主键遍历，如果主键不在源表主键集合中，且配置允许删除，就标记为 delete。为了减少内存占用，我还会维护一个目标主键集合，只存主键值，不存完整记录。
拿到分类结果后，我不立即执行，而是先生成一条条可读的 SQL 语句队列。比如 insert 语句长这样：
sql复制INSERT INTO `test_db`.`sys_config` (`id`, `config_key`, `config_value`, `updated_at`) VALUES (?, ?, ?, ?)
ON DUPLICATE KEY UPDATE `config_key` = VALUES(`config_key`)
这里用到了 MySQL 的 INSERT ... ON DUPLICATE KEY UPDATE，一条语句同时覆盖 insert 和 update 的需求。不过在 compare 阶段我依然会区分二者，因为这会直接影响 SQL 的数量和日志的可读性。如果你更想严格区分，可以只用 INSERT 处理新数据，用 UPDATE 处理旧数据；但 ON DUPLICATE KEY UPDATE 的写法在大多数场景下更简洁，而且不需要先查一次目标表是否存在。配合我前面说过的“先批量查主键集合再比较”，两套方案都可以，实际效率差别不大，看使用习惯。
生成 delete 语句时会限定只按主键删除：
sql复制DELETE FROM `test_db`.`sys_config` WHERE `id` IN (?, ?)
同时因为删除无法用预处理语句绑定动态数组，我需要将参数展开为多个占位符。这个数组如果太大，还会触发 MySQL 的 max_allowed_packet 限制，所以删除也会分块执行，块大小默认 500，可配置。
3.5 分批执行与进度反馈
同步的数据量一旦超过几千条，就必须分批执行。我默认的一个 chunk 大小是 1000 行，这意味着每次事务里最多拼接 1000 条 INSERT 语句的参数，然后一次性交给 mysql2 执行。
批量执行可以极大减少网络往返，1000 条插入可能在 200ms 内完成，而逐条插入可能要八秒以上。分批的大小需要根据字段数和单行数据长度调整：字段多、单行大，chunk 要小一点；字段少、单行小，chunk 可以拉大到 5000。如果单行包含很大的 TEXT 字段，建议 chunk 降到 200，否则很容易触发 MySQL 的 max_allowed_packet 报错。
执行过程中，我在终端打印实时进度，每一批完成后显示“已处理 5000/12000 条”。这样同步几十万数据的时候不会让人以为程序卡死了。进度输出的代码很简单，用 process.stdout.write('\r') 覆盖当前行的输出，保持单行刷新比逐行打印好看得多。
4. 完整实操：从安装到跑通一次同步
4.1 环境准备与项目初始化
先说 Node.js 的安装。去官网下载 LTS 版本，Windows 直接装 msi 包，macOS 可以下载 pkg 包，Linux 可以用包管理器，或者下载二进制 tar 包解压后放到 /usr/local 目录。安装完成后，在终端执行 node -v 和 npm -v 确认版本号，能看到输出就说明环境没问题。
我遇到过一些团队同事在 Windows 上安装后 node 命令提示不是内部或外部命令，大概率是安装时没有勾选“Add to PATH”，或者安装路径里带了空格。重新执行一遍安装包，把 Add to PATH 勾上，重启终端即可解决。
接着初始化项目：
bash复制mkdir sync-helper
cd sync-helper
npm init -y
npm install mysql2
npm init -y 会生成一个默认的 package.json，不需要修改太多内容，npm install mysql2 会自动把依赖写进去。
因为这是一个内部工具，不涉及发布，我并不会在 package.json 里把 type 设置成 module，直接用 CommonJS 的 require 语法，兼容性更好，也省得在写脚本时额外考虑 ES Module 的路径问题。
4.2 编写配置文件
我把配置文件放在 config 目录下，文件名 sync.config.json。下面是实际使用过的一份配置，演示如何把开发库的用户标签表同步到测试库：
json复制{
"source": {
"host": "192.168.1.21",
"port": 3306,
"user": "sync_user",
"password": "Sync@2024",
"database": "dev_shop"
},
"target": {
"host": "192.168.1.31",
"port": 3306,
"user": "sync_user",
"password": "Sync@2024",
"database": "test_shop"
},
"tasks": [
{
"table": "user_tag",
"targetTable": "user_tag",
"primaryKey": "id",
"fields": ["id", "user_id", "tag_name", "tag_type", "created_at", "updated_at"],
"where": "tag_type IN ('vip', 'new_user')",
"deleteExtra": true,
"deleteWhere": "tag_type IN ('vip', 'new_user')",
"chunkSize": 1000,
"incrementalField": "updated_at",
"incrementalValue": "2024-06-01 00:00:00"
}
]
}
这个配置表达了几个意图：源库是 dev_shop，目标库是 test_shop；只处理 tag_type 为 vip 或 new_user 的标签；目标库中同样条件的数据会被完整对齐，多余部分删除；更新时间从 6 月 1 日之后的数据才会被读取。
字段列表里没有把表里所有字段都加进来，比如 remark 业务备注字段就没同步。在实际项目中，有些字段就是不需要跨环境同步的，比如本地调试产生的临时标记。用得越久我越觉得，字段白名单比“全字段同步”更安全。
4.3 用 dry-run 查看将要执行的 SQL
配置写好后，先不要急着真同步，用 dry-run 模式预览一下。入口命令是：
bash复制node sync.js --config config/sync.config.json
注意我没有加 --apply，所以工具进入只读预览模式。它会先连接源库和目标库，读取源表符合条件的行数、目标表当前行数，比对主键，然后打印将要生成的 SQL 数量。
实际输出会是这样：
text复制[源库] dev_shop.user_tag 读取到 1280 条记录
[目标库] test_shop.user_tag 当前匹配记录 1250 条
[比对结果] 将新增 80 条，更新 1200 条，删除 0 条
[预览模式] 未执行任何写入操作，请检查以上结果
这个环节非常关键。如果同步前忘记看数据量，直接 apply，你可能会惊讶地发现目标库的某张表被写入了几十万条不符合预期的数据。先预览，再执行，这两分钟不会白花。
预览模式下还会打印每个字段的类型差异。比如源表的 tag_type 是 varchar(20)，目标表是同名同类型，那就没问题；如果源表是 int，目标表是 varchar，工具会提示“字段类型不一致”，但不会阻断运行，只做告警——毕竟某些情况下隐式转换是可以接受的。
4.4 执行同步与结果验证
预览结果没问题，再真正执行：
bash复制node sync.js --config config/sync.config.json --apply
工具首先会检查配置中是否包含 "allowApply": true。我上面的示例配置里并没有这个字段，所以实际执行前我会在配置中补上：
json复制"allowApply": true
加上之后，程序会继续。同步前会先创建备份表，备份表名称通过日志打印出来，比如 test_shop.user_tag_backup_20240615120000。备份完成后进入事务，分批执行插入和更新。如果没有报错，事务提交，打印最终统计：
text复制[备份] 已创建 backup 表: user_tag_backup_20240615120000
[同步完成] 新增 80 条，更新 1200 条，删除 0 条，耗时 4.2s
完成后，我会习惯性地在目标库执行一次对比查询：
sql复制SELECT COUNT(*) FROM test_shop.user_tag WHERE tag_type IN ('vip', 'new_user');
然后到源库执行同样的查询，确保数字一致。如果两边一致，再抽查几条数据，比如比较 user_id=1024 的记录在两边是否完全一致：
sql复制SELECT * FROM dev_shop.user_tag WHERE user_id = 1024;
SELECT * FROM test_shop.user_tag WHERE user_id = 1024;
对比完字段值，同步才算真正结束。这一步虽然简单，但非常重要——工具只能保证 SQL 没错，不能保证业务语义就一定符合预期。只有抽查过真实数据，才敢跟测试同学说“环境数据已经对齐了”。
5. 常见问题与排查技巧实录
5.1 同步时字段值明显不对：类型边界与精度
有次同步订单表时，我发现目标库里的订单金额跟源库差了 0.01 元。排查后发现，源库 amount 字段是 DECIMAL(10,2)，mysql2 默认返回的是字符串，但我批量生成参数时，为了图方便把所有值都用 parseFloat 转了一遍。parseFloat 在一些场景下会遇到浮点数精度问题，比如 0.1 + 0.2 变成 0.30000000000000004，再存回 DECIMAL 字段，第 15 位小数之后就会产生误差。
这个问题的解法是：DECIMAL 字段一律当作字符串处理，写入时直接传给预处理语句，不要让 JS 做任何数字转换。只要用字符串拼接进 SQL，MySQL 在执行时会安全地完成数值转换，精度不会丢。同理，BIGINT 字段也要当作字符串处理，配合前文说到的 bigNumberStrings 配置。这类问题不踩一次坑很难注意到，因为开发/测试环境数据量小，误差不明显，但一旦开始同步合计金额之类的统计字段，就会立刻暴露。
5.2 中文/emoji乱码：字符集问题
同步用户昵称的时候，目标库里出现了一堆问号。早期排查方向一直是目标表字符集，但检查之后发现表已经是 utf8mb4，最后才意识到问题出在连接字符串上。
mysql2 连接配置中的 charset 如果设置成 utf8_general_ci 或干脆不设置，那么连接层使用的字符集会与表字符集不一致。遇到四字节 emoji 时，数据会在连接层被截断成问号。后来我把连接配置统一改成 UTF8MB4_UNICODE_CI，同时确认目标表存储引擎的默认字符集也是 utf8mb4，问题就消失了。这是个很隐蔽的坑，因为很多工具只处理普通中文，遇到 emoji 才暴露。
5.3 同步速度慢：分批大小与索引
几次同步超过十万行数据的经验告诉我，影响同步速度的最大瓶颈不是 SQL 执行本身，而是“目标表更新时的行定位成本”。如果配置的主键在目标表上没有索引，每次 UPDATE 都要全表扫描，一百条还行，一万条就变成灾难。
所以我在工具里加了一个启动检查：比对任务开始前，查询目标表对应主键列的索引信息，如果发现主键没有索引，直接打印警告，并建议先建索引。这不算程序 bug，更像是一种操作规范提醒。更常见的优化手段是调整 chunkSize。默认 1000 对大多数表都是合适的，但如果你发现执行时间集中在前几批、后面突然变慢，大概率是单批参数过大，触发了 MySQL 的临时排序或行锁升级，把 chunkSize 降到 500 会好很多。
5.4 mysqldump 参数报错 / mysql2 连接报错：环境相关问题
虽然主推 Node.js 原生方案，但有些同事习惯先用 mysqldump 做一次全量备份再同步，期间会碰到几个常见问题。mysqldump: unknown variable 'default-character-set=utf8mb4' 这类报错，通常是因为 MySQL 客户端配置文件 my.ini 里有旧语法。这个参数用 --default-character-set=utf8mb4 作为命令行参数没问题，但写在 [client] 组里，老版本驱动不认这个写法。把它挪到 [mysqld] 组，或者干脆删掉，问题就解了。
mysql2 连接时报 ER_ACCESS_DENIED_ERROR，大概率是账号没有指定来源 IP。开发环境经常出现 root 只允许 localhost 访问，而 Node.js 工具跑在另一台机器上的情况。要么在 MySQL 中授权远程访问，要么把工具部署在同一台主机上。我建议专门为同步工具创建一个最小权限账号，只给 SELECT、INSERT、UPDATE、DELETE 权限，避免直接使用 root。
还有一类报错是 Cannot read properties of undefined (reading 'query')，这多半是哪一个连接池初始化失败了，但代码里没有捕获，导致后续拿到 undefined。排查时先检查源库和目标库的 host、port、database 是否都能连通，最简单的做法是用命令行工具先测试一次连接，再跑同步程序。
5.5 遇到重复键/外键约束时怎么办
同步时报 ER_DUP_ENTRY 是最常见的写入异常。如果源表数据本身存在重复主键，但配置里没开 upsert 逻辑，就会撞主键。我后来在代码里做了一个防护：每次同步开始前检查源表主键是否有重复，有重复直接中止，并提示用户先清洗数据。
如果是外键约束导致插入失败，比如子表引用了父表不存在的记录，那么同步顺序就很重要。我们的工具目前按任务列表的顺序执行，建议把父表任务排在子表前面。同时，目标库如果开启了 FOREIGN_KEY_CHECKS，同步过程中可以先在备份表阶段临时关闭外键检查，完成后再恢复。不过这个操作有一定风险，最好在明确知道子表数据结构的情况下使用。
6. 一些经验和后续扩展方向
这个同步助手已经在团队里用了大半年，基本上每周都会派上用场。我自己总结下来，它最大的价值倒不是省了多少时间，而是把“环境数据对齐”这个过程变得可以追溯、可以复现。以前靠人肉执行 SQL，做完就完了，根本说不清三个环境的数据到底差在哪；现在每个同步动作都有日志、有 SQL 预览、有备份表，出了问题还能倒查。
不少同事问过我，能不能加一个定时调度的功能，让测试环境每天凌晨自动同步一次。其实这个需求很容易实现，在 sync.js 外层套一个循环，或者直接用系统的 cron / 计划任务，每天凌晨跑一次带 --apply 的命令即可。需要注意的是定时执行时不要关闭日志输出，最好把标准输出重定向到文件，这样哪天发现环境数据不对，还能翻日志。
另一个值得扩展的方向是支持多表事务。目前工具是对单张表分别处理，碰到强关联的表组可能需要自己拼多个 task。如果要支持“A表和B表同时同步成功或同时失败”，就需要引入一个外层事务，把多个 writer 调用放在同一个事务上下文里。这个改造不算复杂，但会增加代码复杂度，我暂时没有做。
如果你也想写一个类似的内部工具，我的建议是从最简版本开始：连接池读取配置、单表 upsert、dry-run 预览、逐表事务。跑通之后再加备份和条件删除，最后才考虑多表关联和定时调度。功能做得越多，维护成本越高，对开发/测试环境这个场景来说，简单可靠往往比大而全更重要。