如何在目标为ESM的TypeScript项目中正确使用Sequelize

为什么代码能正常通过TypeScript编译但运行报错 #

TypeScript仅负责类型校验，sequelize提供的类型声明文件中明确声明了支持Sequelize、DataTypes等命名导出，因此TypeScript会判定你的导入写法合法，编译可以正常通过。
但Node.js的ESM加载器处理CommonJS格式的第三方包时，只会把CommonJS包的module.exports整体作为默认导出返回，不会自动拆分出对应的命名导出，因此运行时会抛出找不到命名导出的错误。

可直接生成可运行代码的配置方案 #

1. TypeScript配置调整（推荐生产环境使用） #

修改tsconfig.json的对应配置项，开启Node ESM规则适配，既可以兼容仅提供ESM的包，也可以在编译阶段直接校验出不合法的导入写法：

{
    "compilerOptions": {
        "target": "esnext",
        "module": "NodeNext", // 替换原有ESNext，适配Node的ESM加载规则
        "moduleResolution": "NodeNext",
        "strict": true,
        "outDir": "dist",
        "esModuleInterop": true, // 开启ESM与CJS的互操作支持
        "allowSyntheticDefaultImports": true
    }
}

调整配置后重新执行npm run build，如果导入写法不符合运行时规则，TypeScript会在编译阶段直接抛出错误，无需等到运行时排查。

2. Node.js实验性启动参数（仅适合开发环境临时使用） #

Node 21及以上版本提供了实验性参数--experimental-import-named-commonjs，开启后可以让ESM加载器支持从CommonJS包直接导入命名导出，不需要修改业务代码。启动命令修改为：

node --experimental-import-named-commonjs dist/main.js

该功能属于实验特性，稳定性没有保障，不建议在生产环境使用。

编辑器提前提示错误的ESLint方案 #

使用eslint-plugin-import的校验规则，可以在编码阶段就识别出不合法的导入写法，提前在编辑器提示错误：

1. 安装依赖：

npm install eslint eslint-plugin-import @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev

2. 新增.eslintrc.json配置：

{
    "parser": "@typescript-eslint/parser",
    "plugins": ["import", "@typescript-eslint"],
    "rules": {
        "import/named": "error",
        "import/default": "error",
        "import/namespace": "error"
    },
    "settings": {
        "import/resolver": {
            "typescript": true,
            "node": true
        }
    }
}

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