TypeScript全局增强需副作用导入？模块猴子补丁加载问题咨询

更新 #

提问前已查阅以下资料：

• 使用TypeScript和Node.js通过模块增强安全注入运行时方法
• TypeScript官方文档：声明合并
• MDN：仅为副作用导入模块
• Stack Overflow：如何在TypeScript模块中为全局对象添加polyfill

更新2 #

index.ts的声明文件如下：

/// <reference types="node" />
export declare const dooFoo : (error: Error ) => void;

tsconfig.json配置如下：

{
  "compilerOptions": {
    "module": "ES2022",
    "target": "ES2022",
    "allowJs": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "strict": true,
    "outDir": "./build"
  },
  "include": ["source"],
  "exclude": ["node_modules", "tests", "build"]
}

这是预期行为吗？ #

是，完全符合ES模块和TypeScript的工作机制：

• ES模块采用静态分析，当仅导入dooFoo时，打包工具或Node.js模块解析器会尝试做树摇（Tree Shaking），只保留与dooFoo直接相关的代码。Error.prototype.foo的赋值属于模块顶级副作用代码，未被任何导出成员引用，会被判定为“无用代码”跳过执行。
• 只有显式导入整个模块（import "core.error"）时，模块所有顶级代码（包括全局对象修改）才会执行，这种导入方式本身就是为触发模块副作用设计的。

是否需要两次导入？ #

不需要，两次导入是冗余操作。ES模块是单例的，无论导入多少次，模块只会被执行一次。你可以选择先导入副作用再导入成员，但没必要分开写——只要执行过一次副作用导入，后续的成员导入不会重复执行模块代码。

更优解决方案 #

修改core.error包的配置或代码，确保导入任意导出成员时，副作用代码自动执行，无需用户单独导入副作用：

方案1：配置package.json的sideEffects字段

在core.error的package.json中添加：

{
  "sideEffects": true
}

或者更精准地指定包含副作用的文件：

{
  "sideEffects": ["source/index.ts"]
}

打包工具会识别到该模块存在不可移除的副作用，当用户导入dooFoo时，模块顶级代码（包括Error.prototype.foo的赋值）会被执行。这是最推荐的方案。

方案2：完善声明文件，确保类型自动生效

当前声明文件仅导出dooFoo，可以在声明文件中直接合并全局类型，这样用户导入dooFoo时，TypeScript会自动识别Error.foo的类型：

/// <reference types="node" />
export declare const dooFoo : (error: Error ) => void;

declare global {
  interface Error {
    foo(): void;
  }
}

配合sideEffects配置，就能同时解决类型提示和运行时生效的问题。

方案3：代码层面绑定副作用与导出成员

可以用立即执行函数包裹副作用代码，给树摇工具明确提示：

// index.ts
(() => {
  Error.prototype.foo = function (this: Error): void {
    // 实现逻辑
  };
})();

export const dooFoo = (err: Error): void => {
  err.foo();
};

不过这种方式的可靠性不如sideEffects配置，仅作为备选方案。

总结 #

• 该现象是预期的，由ES模块的树摇机制导致；
• 无需两次导入模块，ES模块的单例特性确保模块只会执行一次；
• 最优方案是在core.error的package.json中配置sideEffects，同时完善声明文件，让类型和运行时逻辑自动生效。

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