解决MySQL错误3988：Node.js中UTF8字符串转latin1_swedish_ci兼容格式

错误原因 #

你遇到的3988错误本质是：要插入的UTF8字符串包含latin1字符集无法表示的字符，或者编码转换流程冲突。另外你的原始字符串看起来是UTF8字节被错误用latin1解码导致的乱码（比如²实际是²，–实际是–），这会进一步加剧转码冲突。

解决方案 #

步骤1：修复原始字符串的乱码

先把乱码的字符串还原成正确的UTF8内容：

const messedUpStr = "Cavo 4x25 mm² CcaFG7OR 0,6/1 kV – MAE-12-02-25";
// 将乱码字符串按latin1转成Buffer，再用utf8解码，得到原始正确内容
const correctedUtf8Str = Buffer.from(messedUpStr, 'latin1').toString('utf8');
// 此时correctedUtf8Str应为："Cavo 4x25 mm² CcaFG7OR 0,6/1 kV – MAE-12-02-25"

步骤2：将UTF8字符串转成latin1兼容格式

latin1仅支持ASCII+西欧字符，像²、–这类字符不在其范围内，需要转成近似字符或替换。推荐用iconv-lite库处理（Node.js内置转码不支持错误 fallback）：

1. 安装依赖：

npm install iconv-lite

2. 转码代码：

const iconv = require('iconv-lite');

// 用iconv-lite将UTF8转成latin1，无法转换的字符用?替换（可自定义fallback字符）
const latin1CompatibleStr = iconv.encode(correctedUtf8Str, 'latin1', { fallback: '?' }).toString('latin1');

如果不想用第三方库，也可以手动替换特殊字符：

function convertToLatin1Safe(str) {
  const charMap = {
    '²': '2',
    '–': '-',
    '—': '-',
    'é': 'e',
    'è': 'e',
    // 可根据业务需求添加更多字符映射
  };
  return str.replace(/[\u0080-\uffff]/g, char => charMap[char] || '?');
}

const latin1CompatibleStr = convertToLatin1Safe(correctedUtf8Str);

步骤3：配置Sequelize确保编码一致

在Sequelize连接配置中明确指定字符集和排序规则，避免自动转码冲突：

const { Sequelize } = require('sequelize');

const sequelize = new Sequelize('your_db_name', 'db_user', 'db_password', {
  host: 'your_db_host',
  dialect: 'mysql',
  dialectOptions: {
    charset: 'latin1',
    collate: 'latin1_swedish_ci',
  },
  define: {
    charset: 'latin1',
    collate: 'latin1_swedish_ci',
  },
});

内容的提问来源于stack exchange，提问作者Stefano