Sequelize NodeJS服务抛出ERR_UNKNOWN_ENCODING错误，求排查

从你的报错信息和代码来看，核心问题是程序错误地把Handshake对象当成了编码格式参数，导致Node.js抛出了未知编码的异常。结合你使用的Docker部署MariaDB 10.5.7的环境，我整理了几个实用的排查和解决方向：

1. 优先检查Sequelize与mariadb驱动的版本兼容性 #

你用的是mariadb dialect，底层依赖的是mariadb npm包（而非mysql2），版本不匹配很容易触发这类奇怪的握手/编码问题：

• 先查看当前的版本组合：

  npm list sequelize mariadb
  

• 推荐使用兼容的版本搭配：比如Sequelize v6.x + mariadb驱动v2.x（MariaDB 10.5属于稳定版本，v2.x驱动对其支持更完善）。如果版本不匹配，执行如下命令调整：

  # 卸载现有版本
  npm uninstall sequelize mariadb
  # 安装兼容组合
  npm install sequelize@6 mariadb@2
  

2. 显式指定字符编码配置 #

自动协商编码偶尔会出问题，你可以在Sequelize初始化时强制指定字符集：

const sequelize = new Sequelize(process.env.DB_DATABASE, process.env.DB_USER, process.env.DB_PASSWORD, {
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  dialect: 'mariadb',
  dialectOptions: {
    charset: 'utf8mb4',
    encoding: 'utf8mb4'
  }
});

MariaDB 10.5推荐用utf8mb4，它支持完整的Unicode字符集，能避免多数编码冲突问题。

3. 确认Docker MariaDB容器的编码配置 #

确保你的MariaDB容器启动时设置了正确的默认字符集，避免容器内部编码和应用端不匹配：
如果是新启动容器，加上编码参数：

docker run -d \
  --name mariadb \
  -e MYSQL_ROOT_PASSWORD=你的密码 \
  -e MYSQL_DATABASE=你的数据库名 \
  -e MYSQL_USER=你的用户名 \
  -e MYSQL_PASSWORD=你的密码 \
  -p 3306:3306 \
  mariadb:10.5.7-focal \
  --character-set-server=utf8mb4 \
  --collation-server=utf8mb4_unicode_ci

如果容器已经在运行，可以进入容器修改配置后重启：

# 进入容器
docker exec -it mariadb bash
# 追加编码配置到my.cnf（路径可能是/etc/mysql/my.cnf或/etc/mysql/mariadb.conf.d/50-server.cnf）
echo -e "[mysqld]\ncharacter-set-server=utf8mb4\ncollation-server=utf8mb4_unicode_ci" >> /etc/mysql/my.cnf
# 重启容器生效
docker restart mariadb

4. 排查环境变量是否正确传递 #

先确认你的DB_HOST、DB_PORT等环境变量没有为空或被意外覆盖，在代码里临时打印验证：

console.log("当前数据库配置：", {
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  database: process.env.DB_DATABASE,
  user: process.env.DB_USER
});

如果是Docker Compose环境，还要确认应用容器和MariaDB容器在同一个网络下，能正常访问3306端口。

5. 用原生mariadb驱动测试连接（排除Sequelize问题） #

为了区分是Sequelize的问题还是驱动/数据库的问题，你可以写个简单的原生连接测试：

const mariadb = require('mariadb');
const pool = mariadb.createPool({
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_DATABASE
});

pool.getConnection()
  .then(conn => {
    console.log("数据库连接成功！");
    conn.release();
  })
  .catch(err => {
    console.log("原生驱动连接错误：", err);
  });

如果这个测试也报错，问题大概率在驱动和数据库的兼容性上；如果测试成功，那就是Sequelize的配置或版本问题。

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