Node.js v18自定义Loader处理JSON模块导入断言问题排查

核心问题分析 #

静态导入报错原因 #

Node.js对静态import语句的校验分为解析阶段和加载阶段：导入JSON模块时，会在解析阶段就强制检查是否携带{ type: "json" }的导入断言，这个环节早于自定义loader的resolve钩子执行，所以你的loader根本没机会介入静态导入的断言补全，错误会直接抛出。

动态导入修改不生效原因 #

你直接修改原context对象的importAssertions属性可能无效——Node.js内部会对传入的上下文做快照处理，原对象可能被冻结或使用了引用拷贝，导致你的修改无法同步到内部逻辑。正确做法是创建新的上下文对象传递给默认解析函数。

修正后的resolve钩子代码 #

export async function resolve(specifier, context, defaultResolve) {
  // 解构并初始化importAssertions，避免undefined
  let { importAssertions = {} } = context;
  // 匹配JSON后缀的模块，强制设置type为json
  if (/\.json$/.test(specifier)) {
    importAssertions = { ...importAssertions, type: "json" };
  }
  // 传递包含新断言的上下文给默认解析函数
  return defaultResolve(specifier, { ...context, importAssertions }, defaultResolve);
}

绕开断言强制校验的替代方案 #

如果想完全自定义断言规则（而非仅补全），可以通过load钩子直接处理JSON模块，绕开Node.js默认的JSON模块逻辑：

export async function load(url, context, defaultLoad) {
  // 处理所有JSON后缀的模块
  if (url.endsWith('.json')) {
    const fs = await import('fs/promises');
    // 读取文件内容并转成ESM导出格式
    const content = await fs.readFile(new URL(url), 'utf8');
    return {
      format: 'module',
      source: `export default ${content}`
    };
  }
  // 其他模块走默认加载逻辑
  return defaultLoad(url, context, defaultLoad);
}

这种方式下，JSON文件会被转换成普通ES模块导出，静态/动态导入都不需要额外添加导入断言。

你的问题直接解答 #

1. 是否错误修改了导入上下文？
   是的，直接修改原context对象的属性无法被Node.js内部感知，必须创建新的上下文对象传递给默认解析函数。
2. 静态JSON导入是否真的不会进入resolve阶段？
   是的，静态导入的断言校验在解析阶段就已完成，早于resolve钩子的执行时机，loader无法介入。
3. 声明式断言类型真的是必需的吗？
   在Node.js默认的JSON模块处理逻辑下是必需的；但通过自定义load钩子绕开默认逻辑后，可以不需要断言。

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